stageflow 0.33.0 → 0.36.0

package/dist/config/loadOutcome.d.ts

@@ -1,32 +1,36 @@
 import type { ValidationFindingCode } from "./validateCatalog.js";
 export type TaskLoadCode = "task.invalid_shape" | "task.load_error" | "task.binding_conflict" | "task.repository_ref_required" | "task.ref_without_repository" | "task.repository_invalid";
 export type TriggerLoadCode = "trigger.invalid_shape" | "trigger.load_error" | "trigger.unknown_pipeline" | "trigger.unknown_task";
-export type LoadIssue = {
+type LoadIssueLocation = {
+    line?: number;
+    column?: number;
+};
+export type LoadIssue = ({
     code: ValidationFindingCode;
     message: string;
     category: "pipeline";
     pipelineId?: string;
     stageId?: string;
-} | {
+} & LoadIssueLocation) | ({
     code: ValidationFindingCode;
     message: string;
     category: "stage";
     stageId?: string;
-} | {
+} & LoadIssueLocation) | ({
     code: TaskLoadCode;
     message: string;
     category: "task";
     taskId?: string;
-} | {
+} & LoadIssueLocation) | ({
     code: TriggerLoadCode;
     message: string;
     category: "trigger";
     triggerId?: string;
-} | {
+} & LoadIssueLocation) | ({
     code: ValidationFindingCode | string;
     message: string;
     category: "catalog";
-};
+} & LoadIssueLocation);
 export type LoadOutcome<T> = {
     ok: true;
     value: T;
@@ -37,3 +41,4 @@ export type LoadOutcome<T> = {
 };
 export declare function loadFailure<T>(issues: LoadIssue[]): LoadOutcome<T>;
 export declare function loadSuccess<T>(value: T, issues?: LoadIssue[]): LoadOutcome<T>;
+export {};

package/dist/config/loadPipeline.js

@@ -1,3 +1,4 @@
+import { MAX_STAGE_CHANNELS, channelLimitMessage, mergeChannelDefaults, stageChannelLimit } from "../channels/stageChannels.js";
 import { access } from "node:fs/promises";
 import path from "node:path";
 import { compilePayloadSchema, expandPayloadSchemaRefs, isPayloadSchemaSubset, UnresolvedSchemaRefError, } from "../envelope/payloadSchema.js";
@@ -128,9 +129,25 @@ export async function loadPipelineFromObject(raw, options = {}) {
     }
     return outcome.value;
 }
+function applyPipelineChannels(stage, defaults, pipelineId) {
+    const channels = mergeChannelDefaults(defaults, stage.channels);
+    if (channels === undefined)
+        return loadSuccess(stage);
+    if (channels.length > Math.min(MAX_STAGE_CHANNELS, stageChannelLimit())) {
+        return loadFailure([
+            {
+                code: "stage.invalid_channels",
+                message: `Pipeline ${pipelineId}: stage "${stage.id}" ends up with ${channels.length} channels after merging pipeline defaults, but ${channelLimitMessage()}. Use \`channels: []\` on the stage to drop the pipeline default.`,
+                category: "stage",
+                stageId: stage.id,
+            },
+        ]);
+    }
+    return loadSuccess({ ...stage, channels });
+}
 async function buildLoadedPipelineFromMerge(merge, options) {
     const { projectRoot, requireIo, pipelinePath } = options;
-    const { entries: rawEntries, pipelineId, agent: pipelineAgent, model: pipelineModel, schemas: pipelineSchemas, requires: pipelineRequires, warnings: mergeWarnings, } = merge;
+    const { entries: rawEntries, pipelineId, agent: pipelineAgent, model: pipelineModel, schemas: pipelineSchemas, requires: pipelineRequires, channels: pipelineChannels, warnings: mergeWarnings, } = merge;
     const ctx = { pipelineId, path: pipelinePath };
     const warnings = [...mergeWarnings];
     const normalizeOutcome = normalizePipelineStageEntries(rawEntries, ctx);
@@ -199,7 +216,10 @@ async function buildLoadedPipelineFromMerge(merge, options) {
             if (inlineRequires.value !== undefined) {
                 stage = { ...stage, requires: inlineRequires.value };
             }
-            stages.push(stage);
+            const inlineChannels = applyPipelineChannels(stage, pipelineChannels, pipelineId);
+            if (!inlineChannels.ok)
+                return loadFailure(inlineChannels.issues);
+            stages.push(inlineChannels.value);
             stageSources[stageId] = { kind: "inline" };
             continue;
         }
@@ -259,10 +279,12 @@ async function buildLoadedPipelineFromMerge(merge, options) {
         if (!fileRequires.ok)
             return loadFailure(fileRequires.issues);
         stageRequires = fileRequires.value;
+        const withChannels = applyPipelineChannels(stageOutcome.value, pipelineChannels, pipelineId);
+        if (!withChannels.ok)
+            return loadFailure(withChannels.issues);
         const stage = {
-            ...stageOutcome.value,
+            ...withChannels.value,
             ...(browser !== undefined ? { browser } : {}),
-            ...(entry.skill !== undefined ? { skill: entry.skill } : {}),
             ...(entry.mcp !== undefined ? { mcp: entry.mcp } : {}),
             ...(entry.secrets !== undefined ? { secrets: entry.secrets } : {}),
             ...(stageRequires !== undefined ? { requires: stageRequires } : {}),
@@ -316,6 +338,7 @@ async function buildLoadedPipelineFromMerge(merge, options) {
         ...(pipelineModel !== undefined ? { model: pipelineModel } : {}),
         ...(pipelineSchemas !== undefined ? { schemas: pipelineSchemas } : {}),
         ...(pipelineRequires !== undefined ? { requires: pipelineRequires } : {}),
+        ...(pipelineChannels !== undefined ? { channels: pipelineChannels } : {}),
     };
     const effectiveRequires = mergeToolRequires([pipelineRequires, ...loadedStages.map((s) => s.requires)], { pipelineId });
     if (!effectiveRequires.ok)

package/dist/config/loadStage.js

@@ -1,3 +1,4 @@
+import { parseChannels } from "../channels/stageChannels.js";
 import { parseAgentField } from "../agent/agentBackend.js";
 import { STAGEFLOW_MCP_SERVER_NAME } from "../agent/claudeTools.js";
 import { STAGE_GATE_KINDS, } from "../types/stage.js";
@@ -7,6 +8,7 @@ import { parseModelField } from "./modelField.js";
 import { allowLegacyYamlAuthoring, dialectWarningForDocument, legacyAuthoringRejected, presentLegacyKeys, } from "./legacyYaml.js";
 import { parsePreEmitChecks } from "./parsePreEmitChecks.js";
 import { readYamlObject } from "./readYamlObject.js";
+import { yamlParsePosition } from "./yamlParsePosition.js";
 import { z } from "zod";
 import { parseStageSecrets } from "../runtime/stageSecretDecl.js";
 import { parseToolRequires } from "./toolRequires.js";
@@ -361,6 +363,20 @@ function parseStageFields(raw, label, entryId, deferSchemaRefs, requireIo, compi
     if (mcpOutcome.value !== undefined) {
         stage.mcp = mcpOutcome.value;
     }
+    if (raw.channels !== undefined) {
+        const channels = parseChannels(raw.channels);
+        if (!channels.ok) {
+            return loadFailure([
+                {
+                    code: "stage.invalid_channels",
+                    message: `Invalid stage ${label}: ${channels.message}`,
+                    category: "stage",
+                    stageId: entryId,
+                },
+            ]);
+        }
+        stage.channels = channels.value;
+    }
     const secretsOutcome = parseStageSecrets(raw.secrets, label, entryId);
     if (!secretsOutcome.ok)
         return secretsOutcome;
@@ -436,6 +452,7 @@ export async function loadStageOutcome(filePath, options = {}) {
                 code: "stage.load_error",
                 message,
                 category: "stage",
+                ...yamlParsePosition(err),
             },
         ]);
     }

package/dist/config/loadStageflowManifest.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { parseAgentField } from "../agent/agentBackend.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { yamlParsePosition } from "./yamlParsePosition.js";
 import { parseModelField } from "./modelField.js";
 const DEFAULT_PIPELINE_PATTERN = "*.pipeline.yaml";
 const DEFAULT_TASK_PATTERN = "*.task.yaml";
@@ -87,7 +88,9 @@ export function parseStageflowManifestOutcome(yamlText, manifestPath, projectRoo
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return loadFailure([catalogIssue("catalog.manifest_load_error", message)]);
+        return loadFailure([
+            { ...catalogIssue("catalog.manifest_load_error", message), ...yamlParsePosition(err) },
+        ]);
     }
     const issues = [];
     const record = raw;

package/dist/config/loadTask.js

@@ -2,6 +2,7 @@ import { readFile } from "node:fs/promises";
 import { parse as parseYaml } from "yaml";
 import { resolveWorkspaceBinding } from "../runtime/workspaceBinding.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { yamlParsePosition } from "./yamlParsePosition.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -86,6 +87,7 @@ export function loadTaskFromYamlOutcome(yamlText, source = "task yaml") {
                 code: "task.load_error",
                 message,
                 category: "task",
+                ...yamlParsePosition(err),
             },
         ]);
     }

package/dist/config/loadTrigger.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { parse as parseYaml } from "yaml";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { yamlParsePosition } from "./yamlParsePosition.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -84,6 +85,7 @@ export function loadTriggerFromYamlOutcome(yamlText, source = "trigger yaml") {
                 code: "trigger.load_error",
                 message,
                 category: "trigger",
+                ...yamlParsePosition(err),
             },
         ]);
     }

package/dist/config/mergePipelineIncludes.d.ts

@@ -2,6 +2,7 @@ import type { PayloadSchemaMap } from "../envelope/payloadSchema.js";
 import type { InlinePipelineDefinition } from "../types/pipeline.js";
 import { type LoadIssue, type LoadOutcome } from "./loadOutcome.js";
 import { type ToolRequirement } from "./toolRequires.js";
+import type { StageChannel } from "../types/stage.js";
 export type RawMergedEntry = {
     raw: unknown;
     declaringPath: string;
@@ -13,6 +14,7 @@ export declare function mergePipelineStages(rootPath: string): Promise<LoadOutco
     model?: string;
     schemas?: PayloadSchemaMap;
     requires?: ToolRequirement[];
+    channels?: StageChannel[];
     warnings: LoadIssue[];
 }>>;
 /** Synthetic `declaringPath` for stage entries with no backing file. */
@@ -24,5 +26,6 @@ export declare function mergeInlinePipelineStages(raw: InlinePipelineDefinition)
     model?: string;
     schemas?: PayloadSchemaMap;
     requires?: ToolRequirement[];
+    channels?: StageChannel[];
     warnings: LoadIssue[];
 }>>;

package/dist/config/mergePipelineIncludes.js

@@ -4,7 +4,9 @@ import { loadFailure, loadSuccess } from "./loadOutcome.js";
 import { allowLegacyYamlAuthoring, dialectWarningForDocument, legacyAuthoringRejected, presentLegacyKeys, } from "./legacyYaml.js";
 import { parseModelField } from "./modelField.js";
 import { readYamlObject } from "./readYamlObject.js";
+import { yamlParsePosition } from "./yamlParsePosition.js";
 import { parseToolRequires } from "./toolRequires.js";
+import { parseChannels } from "../channels/stageChannels.js";
 import { classifyYamlDocument, collectDocumentKeys, mixedDialectIssue, } from "./yamlDialect.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -39,6 +41,7 @@ async function visitPipelineFile(filePath, stack, idLocations, entries, warnings
                 code: "pipeline.load_error",
                 message,
                 category: "pipeline",
+                ...yamlParsePosition(err),
             },
         ]);
     }
@@ -128,6 +131,7 @@ export async function mergePipelineStages(rootPath) {
                 code: "pipeline.load_error",
                 message,
                 category: "pipeline",
+                ...yamlParsePosition(err),
             },
         ]);
     }
@@ -186,6 +190,10 @@ export async function mergePipelineStages(rootPath) {
     if (!requiresOutcome.ok)
         return requiresOutcome;
     const requires = requiresOutcome.value;
+    const channelsOutcome = parsePipelineChannels(raw.channels, `pipeline ${absRoot}`, pipelineId);
+    if (!channelsOutcome.ok)
+        return channelsOutcome;
+    const channels = channelsOutcome.value;
     const idLocations = new Map();
     const entries = [];
     const warnings = [];
@@ -208,6 +216,7 @@ export async function mergePipelineStages(rootPath) {
         ...(model !== undefined ? { model } : {}),
         ...(schemas !== undefined ? { schemas } : {}),
         ...(requires !== undefined ? { requires } : {}),
+        ...(channels !== undefined ? { channels } : {}),
         warnings,
     });
 }
@@ -270,6 +279,10 @@ export async function mergeInlinePipelineStages(raw) {
     if (!requiresOutcome.ok)
         return requiresOutcome;
     const requires = requiresOutcome.value;
+    const channelsOutcome = parsePipelineChannels(raw.channels, `inline pipeline ${pipelineId}`, pipelineId);
+    if (!channelsOutcome.ok)
+        return channelsOutcome;
+    const channels = channelsOutcome.value;
     const entries = [];
     for (let index = 0; index < raw.stages.length; index++) {
         const entry = raw.stages[index];
@@ -292,9 +305,26 @@ export async function mergeInlinePipelineStages(raw) {
         ...(model !== undefined ? { model } : {}),
         ...(schemas !== undefined ? { schemas } : {}),
         ...(requires !== undefined ? { requires } : {}),
+        ...(channels !== undefined ? { channels } : {}),
         warnings: [],
     });
 }
+function parsePipelineChannels(raw, label, pipelineId) {
+    if (raw === undefined)
+        return loadSuccess(undefined);
+    const parsed = parseChannels(raw);
+    if (!parsed.ok) {
+        return loadFailure([
+            {
+                code: "pipeline.invalid_channels",
+                message: `Invalid ${label}: ${parsed.message}`,
+                category: "pipeline",
+                pipelineId,
+            },
+        ]);
+    }
+    return loadSuccess(parsed.value);
+}
 function parsePipelineSchemas(raw, absPath, pipelineId) {
     if (raw === undefined)
         return loadSuccess(undefined);

package/dist/config/normalizePipelineStageEntry.js

@@ -43,7 +43,6 @@ function extractBodyRaw(raw) {
 }
 function hasBodyKey(raw) {
     return Object.keys(raw).some((key) => BODY_KEYS.has(key) &&
-        key !== "skill" &&
         key !== "mcp" &&
         key !== "secrets" &&
         key !== "requires" &&
@@ -116,6 +115,16 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
             return skillOutcome;
         }
         const skill = skillOutcome?.ok ? skillOutcome.value : undefined;
+        if (uses && skill !== undefined) {
+            return loadFailure([
+                {
+                    code: "pipeline.stage_wrapper_skill_rejected",
+                    message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage entry at index ${index} sets skill: on a uses: wrapper; put skill: on the stage file (${uses}) instead`,
+                    category: "pipeline",
+                    pipelineId: ctx.pipelineId,
+                },
+            ]);
+        }
         const mcpOutcome = parseStageMcp(raw.mcp, `entry at index ${index} in ${declaringPath}`);
         if (!mcpOutcome.ok)
             return mcpOutcome;

package/dist/config/pipelineStageKeys.js

@@ -29,6 +29,7 @@ export const WIRING_KEYS = new Set([
 /** Stage body keys. Target: `io` / `verify`. IR/legacy: `payload_schema`, `pre_emit_checks`, `clone_input_schema`. */
 export const BODY_KEYS = new Set([
     "email",
+    "channels",
     "system_prompt",
     "model",
     "payload_schema",

package/dist/config/printTargetYaml.js

@@ -163,7 +163,6 @@ const STAGE_BODY_ORDER = [
 const PIPELINE_WIRING_ORDER = [
     "id",
     "uses",
-    "skill",
     "mcp",
     "needs",
     "fork",

package/dist/config/publishDraftPackage.d.ts

@@ -1,7 +1,11 @@
 import { type CreateDraftPackageInput, type DraftPackageWriteResult } from "./draftPackage.js";
+import type { CatalogRootKind } from "./resolveCatalogRoots.js";
 export type PublishDraftPackageMode = "create" | "overwrite" | "auto";
+export type PublishDraftPackageOptions = {
+    catalogRootKind?: CatalogRootKind;
+};
 export type PublishDraftPackageResult = {
     write: DraftPackageWriteResult;
     catalogChanged: boolean;
 };
-export declare function publishDraftPackage(projectRoot: string, input: CreateDraftPackageInput, mode: PublishDraftPackageMode): Promise<PublishDraftPackageResult>;
+export declare function publishDraftPackage(projectRoot: string, input: CreateDraftPackageInput, mode: PublishDraftPackageMode, options?: PublishDraftPackageOptions): Promise<PublishDraftPackageResult>;

package/dist/config/publishDraftPackage.js

@@ -1,6 +1,6 @@
 import { createDraftPackage, overwriteDraftPackage, } from "./draftPackage.js";
 import { ensureCatalogScanRoot } from "./ensureCatalogScanRoot.js";
-export async function publishDraftPackage(projectRoot, input, mode) {
+export async function publishDraftPackage(projectRoot, input, mode, options = {}) {
     let write;
     if (mode === "create") {
         write = await createDraftPackage(projectRoot, input);
@@ -20,6 +20,9 @@ export async function publishDraftPackage(projectRoot, input, mode) {
     if (!write.ok) {
         return { write, catalogChanged: false };
     }
+    if (options.catalogRootKind === "workspace") {
+        return { write, catalogChanged: false };
+    }
     const catalogChanged = await ensureCatalogScanRoot(projectRoot, input.directory);
     return { write, catalogChanged };
 }

package/dist/config/resolveCatalogRoots.d.ts

@@ -1,5 +1,5 @@
 import type { RunStore } from "../runstore/port.js";
-export type CatalogRootKind = "registered" | "seeded";
+export type CatalogRootKind = "registered" | "seeded" | "workspace";
 export type CatalogRoot = {
     /** Wire id: absolute path for registered; symbolic id for seeded (e.g. "examples"). */
     project_root: string;
@@ -7,6 +7,9 @@ export type CatalogRoot = {
     path: string;
     kind: CatalogRootKind;
     read_only: boolean;
+    /** False when workspace provisioning failed at boot. */
+    available?: boolean;
+    unavailable_reason?: string;
 };
 export type ResolveCatalogRootsOptions = {
     store: RunStore;

package/dist/config/resolveCatalogRoots.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { realpathSync, constants } from "node:fs";
 import { access } from "node:fs/promises";
+import { WORKSPACE_CATALOG_ID, lastWorkspaceProvisionResult, workspaceCatalogPath, } from "../project/workspaceCatalog.js";
 function realOrResolve(p) {
     const resolved = path.resolve(p);
     try {
@@ -19,6 +20,7 @@ export async function resolveCatalogRoots(options) {
     const seenPaths = new Set();
     const seededRoots = options.seededRoots ??
         (await import("./seededCatalog.js")).defaultSeededRoots();
+    const workspaceAbs = realOrResolve(workspaceCatalogPath());
     let registered = [];
     try {
         registered = await options.store.listRegisteredProjects();
@@ -28,7 +30,7 @@ export async function resolveCatalogRoots(options) {
     }
     for (const root of registered) {
         const abs = realOrResolve(root);
-        if (seenPaths.has(abs))
+        if (seenPaths.has(abs) || abs === workspaceAbs)
             continue;
         seenPaths.add(abs);
         roots.push({
@@ -38,6 +40,21 @@ export async function resolveCatalogRoots(options) {
             read_only: false,
         });
     }
+    if (!seenPaths.has(workspaceAbs)) {
+        seenPaths.add(workspaceAbs);
+        const provision = lastWorkspaceProvisionResult();
+        const available = provision === undefined || provision.ok;
+        roots.push({
+            project_root: WORKSPACE_CATALOG_ID,
+            path: workspaceCatalogPath(),
+            kind: "workspace",
+            read_only: false,
+            available,
+            ...(provision !== undefined && !provision.ok && provision.reason
+                ? { unavailable_reason: provision.reason }
+                : {}),
+        });
+    }
     for (const seeded of seededRoots) {
         const abs = realOrResolve(seeded.path);
         if (seenPaths.has(abs))

package/dist/config/skillUsageIndex.d.ts

@@ -0,0 +1,6 @@
+export type SkillUsageEntry = {
+    stage_ids: string[];
+    pipeline_ids: string[];
+};
+export type SkillUsageIndex = Record<string, SkillUsageEntry>;
+export declare function buildSkillUsageIndex(cwd: string): Promise<SkillUsageIndex | null>;

package/dist/config/skillUsageIndex.js

@@ -0,0 +1,39 @@
+import { loadPipelineOutcome } from "./loadPipeline.js";
+import { getCatalogScanPaths } from "./browseCatalog.js";
+import { catalogContextFromStageflow } from "./resolveCatalogContext.js";
+import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+function addUsage(index, skillName, pipelineId, stageId) {
+    const entry = index[skillName] ?? { stage_ids: [], pipeline_ids: [] };
+    if (!entry.pipeline_ids.includes(pipelineId)) {
+        entry.pipeline_ids.push(pipelineId);
+        entry.pipeline_ids.sort((a, b) => a.localeCompare(b));
+    }
+    if (!entry.stage_ids.includes(stageId)) {
+        entry.stage_ids.push(stageId);
+        entry.stage_ids.sort((a, b) => a.localeCompare(b));
+    }
+    index[skillName] = entry;
+}
+export async function buildSkillUsageIndex(cwd) {
+    const ctx = catalogContextFromStageflow(await resolveStageflowContext(cwd));
+    const scanPaths = await getCatalogScanPaths(ctx);
+    if (!scanPaths) {
+        return null;
+    }
+    const index = {};
+    const loadCwd = ctx.projectRoot ?? cwd;
+    for (const pipelinePath of scanPaths.pipelinePaths) {
+        const outcome = await loadPipelineOutcome(pipelinePath, { cwd: loadCwd });
+        if (!outcome.ok) {
+            continue;
+        }
+        const pipelineId = outcome.value.pipeline.id;
+        for (const stage of outcome.value.stages) {
+            if (stage.skill === undefined) {
+                continue;
+            }
+            addUsage(index, stage.skill, pipelineId, stage.id);
+        }
+    }
+    return index;
+}

package/dist/config/stageBrowser.js

@@ -4,6 +4,16 @@ export const BROWSER_TOOL_NAME = "agent-browser";
 const ALLOWED_KEYS = new Set(["profile", "headed", "allow_domains", "login_url", "check"]);
 const CHECK_KEYS = new Set(["url", "logged_in_url", "logged_out_url"]);
 const REJECTED_KEYS = new Set(["path", "scope", "secret"]);
+const HOST_ONLY_KEYS = new Set([
+    "launch_args",
+    "args",
+    "executable_path",
+    "executable",
+    "display",
+    "headless",
+    "xvfb",
+    "env",
+]);
 const PROFILE_NAME = /^[A-Za-z0-9_-]{1,64}$/;
 const DOMAIN = /^(\*\.)?[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$/;
 function isPlainObject(value) {
@@ -67,6 +77,9 @@ export function parseStageBrowser(raw, label, stageId) {
         if (REJECTED_KEYS.has(key)) {
             return fail(label, stageId, `"${key}" is not allowed (the Host chooses profile location and scope)`);
         }
+        if (HOST_ONLY_KEYS.has(key)) {
+            return fail(label, stageId, `"${key}" is not allowed (browser launch options are Host config: browser.launch_args and browser.executable_path in $STAGEFLOW_HOME/config.yaml)`);
+        }
         if (!ALLOWED_KEYS.has(key)) {
             return fail(label, stageId, `unknown key "${key}" (allowed: profile, headed, allow_domains, login_url, check)`);
         }

package/dist/config/triggerAdapterStatus.d.ts

@@ -0,0 +1,11 @@
+import type { TriggerFile } from "../types/trigger.js";
+import type { RunStore } from "../runstore/port.js";
+export type TriggerAdapterStatus = {
+    adapter: string;
+    state: string;
+    detail?: string;
+    last_poll_at?: string;
+    last_seen_at?: string;
+    last_error?: string;
+};
+export declare function readTriggerAdapterStatus(trigger: TriggerFile, store: RunStore): Promise<TriggerAdapterStatus>;

package/dist/config/triggerAdapterStatus.js

@@ -0,0 +1,90 @@
+function parseGithubCursor(raw) {
+    if (raw === null) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.updatedAt === "string") {
+            return { updatedAt: parsed.updatedAt };
+        }
+        return {};
+    }
+    catch {
+        return null;
+    }
+}
+function mailboxKeyForTrigger(trigger) {
+    const config = trigger.event?.config;
+    const host = config?.host;
+    const port = config?.port;
+    const user = config?.user;
+    if (typeof host !== "string" ||
+        host.length === 0 ||
+        typeof port !== "number" ||
+        !Number.isFinite(port) ||
+        typeof user !== "string" ||
+        user.length === 0) {
+        return undefined;
+    }
+    return `email:${host}:${port}:${user}`;
+}
+async function adapterStateUpdatedAt(store, adapterId, key) {
+    const meta = await store.getTriggerAdapterStateMeta(adapterId, key);
+    return meta?.updated_at;
+}
+export async function readTriggerAdapterStatus(trigger, store) {
+    if (!trigger.enabled) {
+        return { adapter: trigger.kind, state: "disabled" };
+    }
+    if (trigger.kind === "manual") {
+        return { adapter: "manual", state: "idle" };
+    }
+    if (trigger.kind === "schedule") {
+        return { adapter: "schedule", state: "scheduled" };
+    }
+    const source = trigger.event?.source ?? "";
+    if (source === "webhook") {
+        return { adapter: "webhook", state: "ready", detail: "Endpoint ready when host is running" };
+    }
+    if (source.startsWith("github.")) {
+        const repo = trigger.event?.config?.repo;
+        if (typeof repo !== "string" || repo.length === 0) {
+            return {
+                adapter: "github",
+                state: "error",
+                detail: "event.config.repo is required",
+            };
+        }
+        const adapterId = `github:${repo}`;
+        const cursor = parseGithubCursor(await store.getTriggerAdapterState(adapterId, "cursor"));
+        const lastPoll = await adapterStateUpdatedAt(store, adapterId, "etag");
+        const lastSeen = cursor?.updatedAt ?? lastPoll;
+        return {
+            adapter: "github",
+            state: cursor !== null || lastPoll !== undefined ? "polling" : "idle",
+            ...(lastPoll !== undefined ? { last_poll_at: lastPoll } : {}),
+            ...(lastSeen !== undefined ? { last_seen_at: lastSeen } : {}),
+        };
+    }
+    if (source === "email.message") {
+        const mailboxKey = mailboxKeyForTrigger(trigger);
+        if (mailboxKey === undefined) {
+            return {
+                adapter: "email",
+                state: "error",
+                detail: "Incomplete email event.config",
+            };
+        }
+        const uid = await store.getTriggerAdapterState(mailboxKey, "uid");
+        const lastSeen = await adapterStateUpdatedAt(store, mailboxKey, "uid");
+        return {
+            adapter: "email",
+            state: uid !== null ? "connected" : "watching",
+            ...(lastSeen !== undefined ? { last_seen_at: lastSeen } : {}),
+        };
+    }
+    return {
+        adapter: source.length > 0 ? source : "event",
+        state: "idle",
+    };
+}