stageflow 0.42.0 → 0.46.0

package/dist/compaction/summarize.js

@@ -0,0 +1,171 @@
+import { applyClearing, planClearing, renderClearedIndex } from "./mask.js";
+import { extractDirectives, mergeDirectives, renderDirectives } from "./directives.js";
+import { extractPinnedFacts, renderPinned } from "./pin.js";
+import { scrubSecrets } from "./scrub.js";
+import { COMPACTION_PROMPT_VERSION } from "./types.js";
+import { WorkingStateStore } from "./workingState.js";
+export const COMPACTION_FOCUS = "This is an autonomous agent run, not a chat. Make the summary a working record the agent can continue from without the earlier messages. " +
+    "Copy exact identifiers, numbers, counts, timestamps, versions, paths, URLs and quoted error text verbatim; never round, reword or estimate them. " +
+    "Keep every failure, rejection and dead end explicit, with why it failed, so it is not retried. " +
+    "State what is in flight, which sources or items are already handled and which remain, and the exact next step. " +
+    "Keep decisions made by the operator or user and the deliverable the run must produce, including its required format. " +
+    "Leave out routine output that carries no decision or value.";
+export const SECTIONS_MARKER = "<!-- stageflow:compaction-sections -->";
+export const PINNED_RENDER_CHARS = 6000;
+export const CLEARED_RENDER_CHARS = 3000;
+export const STATE_RENDER_CHARS = 6000;
+export const DIRECTIVES_RENDER_CHARS = 5000;
+export const PINNED_CARRY_MAX = 400;
+export const CLEARED_CARRY_MAX = 200;
+/** The sections are always appended last, so the last marker at the start of a line is the real one. */
+export function splitSummary(summary) {
+    const afterNewline = summary.lastIndexOf(`\n${SECTIONS_MARKER}`);
+    const at = afterNewline >= 0 ? afterNewline + 1 : summary.startsWith(SECTIONS_MARKER) ? 0 : -1;
+    if (at < 0)
+        return { core: summary, sections: "" };
+    return { core: summary.slice(0, at).trimEnd(), sections: summary.slice(at) };
+}
+const FACT_KINDS = new Set(["id", "number", "timestamp", "url", "path", "error", "other"]);
+const DIRECTIVE_SOURCES = new Set(["operator", "user", "rejection"]);
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function strings(value) {
+    return Array.isArray(value) ? value.filter((x) => typeof x === "string") : undefined;
+}
+function validPinned(x) {
+    return isRecord(x) && typeof x.kind === "string" && FACT_KINDS.has(x.kind) && typeof x.value === "string" && typeof x.context === "string" && isRecord(x.source) && typeof x.source.messageIndex === "number";
+}
+function validCleared(x) {
+    return isRecord(x) && typeof x.toolName === "string" && typeof x.toolCallId === "string" && typeof x.recoverHint === "string" && typeof x.bytes === "number" && typeof x.descriptor === "string";
+}
+function validDirective(x) {
+    return isRecord(x) && typeof x.source === "string" && DIRECTIVE_SOURCES.has(x.source) && typeof x.text === "string";
+}
+/** Details come from the session file, so anything not shaped like ours is dropped rather than trusted. */
+export function readStageflowDetails(value) {
+    if (!isRecord(value))
+        return undefined;
+    const readFiles = strings(value.readFiles);
+    const modifiedFiles = strings(value.modifiedFiles);
+    return {
+        ...(readFiles ? { readFiles } : {}),
+        ...(modifiedFiles ? { modifiedFiles } : {}),
+        ...(Array.isArray(value.stageflowPinned) ? { stageflowPinned: value.stageflowPinned.filter(validPinned) } : {}),
+        ...(Array.isArray(value.stageflowCleared) ? { stageflowCleared: value.stageflowCleared.filter(validCleared) } : {}),
+        ...(Array.isArray(value.stageflowDirectives) ? { stageflowDirectives: value.stageflowDirectives.filter(validDirective) } : {}),
+        ...(typeof value.stageflowPromptVersion === "number" ? { stageflowPromptVersion: value.stageflowPromptVersion } : {}),
+    };
+}
+function factKey(f) {
+    return `${f.kind}\u0000${f.value}`;
+}
+/** Newest facts first win a tie; capped so repeated compactions cannot grow without bound. */
+export function mergePinned(previous, fresh, max = PINNED_CARRY_MAX) {
+    const seen = new Set();
+    const out = [];
+    for (const f of [...fresh, ...previous]) {
+        const key = factKey(f);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(f);
+        if (out.length >= max)
+            break;
+    }
+    return out;
+}
+export function mergeCleared(previous, fresh, max = CLEARED_CARRY_MAX) {
+    const seen = new Set();
+    const out = [];
+    for (const c of [...fresh, ...previous]) {
+        if (seen.has(c.toolCallId))
+            continue;
+        seen.add(c.toolCallId);
+        out.push(c);
+        if (out.length >= max)
+            break;
+    }
+    return out;
+}
+export function renderSections(input) {
+    const parts = [];
+    if (input.state.length > 0) {
+        const store = new WorkingStateStore();
+        for (const e of input.state)
+            store.set({ key: e.key, kind: e.kind, value: e.value, updatedAt: e.updatedAt });
+        const rendered = store.render(STATE_RENDER_CHARS);
+        if (rendered)
+            parts.push(rendered);
+    }
+    const directives = renderDirectives(input.directives ?? [], DIRECTIVES_RENDER_CHARS);
+    if (directives)
+        parts.push(directives);
+    if (input.pinned.length > 0)
+        parts.push(renderPinned(input.pinned, PINNED_RENDER_CHARS));
+    if (input.cleared.length > 0)
+        parts.push(renderClearedIndex(input.cleared, CLEARED_RENDER_CHARS));
+    if (parts.length === 0)
+        return "";
+    return `${SECTIONS_MARKER}\n${parts.join("\n\n")}`;
+}
+function scrubValue(value) {
+    if (typeof value === "string")
+        return scrubSecrets(value);
+    if (Array.isArray(value))
+        return value.map(scrubValue);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, scrubValue(v)]));
+    }
+    return value;
+}
+/** What the summarizer reads: message text, thinking and tool-call arguments with secrets removed. */
+export function redactMessages(messages) {
+    return messages.map((m) => (Array.isArray(m.content) || typeof m.content === "string" ? { ...m, content: scrubValue(m.content) } : m));
+}
+/** Everything deterministic that happens before the model-written summary is requested. */
+export function prepareSummaryInputs(input) {
+    const extracted = extractPinnedFacts(input.messages);
+    const pinned = mergePinned(input.previousDetails?.stageflowPinned ?? [], extracted);
+    const directives = mergeDirectives(input.previousDetails?.stageflowDirectives ?? [], extractDirectives(input.messages));
+    if (!input.clearInSummary) {
+        return { messagesForSummarizer: redactMessages(input.messages), pinned, directives, cleared: [...(input.previousDetails?.stageflowCleared ?? [])] };
+    }
+    const plan = planClearing(input.messages, input.clearInSummary);
+    return {
+        messagesForSummarizer: redactMessages(applyClearing(input.messages, plan)),
+        pinned,
+        directives,
+        cleared: mergeCleared(input.previousDetails?.stageflowCleared ?? [], plan.cleared),
+    };
+}
+export function stageflowDetails(piDetails, previous, pinned, cleared, directives = []) {
+    const union = (a, b) => [...new Set([...(b ?? []), ...(a ?? [])])];
+    return {
+        readFiles: union(piDetails?.readFiles, previous?.readFiles),
+        modifiedFiles: union(piDetails?.modifiedFiles, previous?.modifiedFiles),
+        stageflowPinned: [...pinned],
+        stageflowCleared: [...cleared],
+        stageflowDirectives: [...directives],
+        stageflowPromptVersion: COMPACTION_PROMPT_VERSION,
+    };
+}
+/**
+ * The whole summary pipeline in one place: pin and redact the input, ask the model for the written part,
+ * scrub it, then append the deterministic sections. The Pi hook and the evaluation harness both call this,
+ * so what the harness measures is what ships.
+ */
+export async function composeCompactionSummary(input) {
+    const prepared = prepareSummaryInputs({
+        messages: input.messages,
+        ...(input.previousDetails ? { previousDetails: input.previousDetails } : {}),
+        ...(input.clearInSummary ? { clearInSummary: input.clearInSummary } : {}),
+    });
+    const result = await input.summarize({
+        messages: prepared.messagesForSummarizer,
+        previousSummary: input.previousSummary !== undefined ? splitSummary(input.previousSummary).core : undefined,
+    });
+    const core = scrubSecrets(result.summary).split(SECTIONS_MARKER).join("").trimEnd();
+    const sections = scrubSecrets(renderSections({ pinned: prepared.pinned, cleared: prepared.cleared, state: input.state, directives: prepared.directives }));
+    return { summary: sections ? `${core}\n\n${sections}` : core, result, prepared };
+}

package/dist/compaction/toolPolicy.d.ts

@@ -0,0 +1,3 @@
+export type ClearingClass = "clearable" | "keep";
+/** Fail closed: only provably re-fetchable read results are clearable; everything else (bash included, it can have side effects) is kept. */
+export declare function classifyForClearing(toolName: string, isError: boolean, _details?: unknown): ClearingClass;

package/dist/compaction/toolPolicy.js

@@ -0,0 +1,33 @@
+import { classifyTool } from "../agents/toolRisk.js";
+import { ASK_OPERATOR_TOOL_NAME, EMIT_STAGE_ENVELOPE_TOOL_NAME, WRITE_STAGE_ARTIFACT_TOOL_NAME } from "../tools/stageToolNames.js";
+import { WORKING_STATE_TOOL_NAME } from "./types.js";
+const ALWAYS_KEEP = new Set([
+    ASK_OPERATOR_TOOL_NAME,
+    EMIT_STAGE_ENVELOPE_TOOL_NAME,
+    WRITE_STAGE_ARTIFACT_TOOL_NAME,
+    "write",
+    "edit",
+    WORKING_STATE_TOOL_NAME,
+]);
+const CLEARABLE_BUILTINS = new Set(["read", "grep", "find", "ls"]);
+/** Fail closed: only provably re-fetchable read results are clearable; everything else (bash included, it can have side effects) is kept. */
+export function classifyForClearing(toolName, isError, _details) {
+    if (isError)
+        return "keep";
+    if (typeof toolName !== "string" || toolName.length === 0)
+        return "keep";
+    if (ALWAYS_KEEP.has(toolName))
+        return "keep";
+    if (CLEARABLE_BUILTINS.has(toolName))
+        return "clearable";
+    if (toolName.startsWith("stageflow_")) {
+        const name = toolName.slice("stageflow_".length);
+        return ALWAYS_KEEP.has(name) ? "keep" : classifyTool(undefined, `stageflow.${name}`).readOnly ? "clearable" : "keep";
+    }
+    try {
+        return classifyTool(undefined, toolName).readOnly ? "clearable" : "keep";
+    }
+    catch {
+        return "keep";
+    }
+}

package/dist/compaction/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared contracts for Stageflow's built-in compaction (docs/plans/compaction-strategy.md).
+ * Pure data types only: the layers (mask, pin, state, summary, guards) import from here.
+ */
+export type PinnedFactKind = "id" | "number" | "timestamp" | "url" | "path" | "error" | "other";
+/** A value copied verbatim out of a message so a summary cannot lose or reword it. */
+export type PinnedFact = {
+    kind: PinnedFactKind;
+    /** The exact text, e.g. "INC-4471", "48211", "2026-03-14T05:52:03Z". */
+    value: string;
+    /** A short verbatim snippet around the value (single line, capped), for orientation. */
+    context: string;
+    /** Position in the message list the facts were extracted from, and the tool when from a tool result. */
+    source: {
+        messageIndex: number;
+        toolName?: string;
+    };
+};
+/** A tool result replaced by a placeholder in the model's context. */
+export type ClearedResult = {
+    toolName: string;
+    toolCallId: string;
+    /** Where the full output can be read again (a file path or a tool + args hint). */
+    recoverHint: string;
+    bytes: number;
+    /** One line describing what the result was, for the recovery index. */
+    descriptor: string;
+};
+export type WorkingStateKind = "fact" | "decision" | "progress" | "todo" | "blocker";
+/** One keyed entry in the model's working state (the `working_state` tool). */
+export type WorkingStateEntry = {
+    key: string;
+    kind: WorkingStateKind;
+    value: string;
+    updatedAt: string;
+};
+export declare const WORKING_STATE_TOOL_NAME = "working_state";
+/** Everything the compaction summary is built from, besides the model-written part. */
+export type CompactionSections = {
+    pinned: readonly PinnedFact[];
+    cleared: readonly ClearedResult[];
+    state: readonly WorkingStateEntry[];
+};
+/** Bumped whenever the focus prompt or section layout changes (like RUBRIC_PROMPT_VERSION). */
+export declare const COMPACTION_PROMPT_VERSION = 1;

package/dist/compaction/types.js

@@ -0,0 +1,7 @@
+/**
+ * Shared contracts for Stageflow's built-in compaction (docs/plans/compaction-strategy.md).
+ * Pure data types only: the layers (mask, pin, state, summary, guards) import from here.
+ */
+export const WORKING_STATE_TOOL_NAME = "working_state";
+/** Bumped whenever the focus prompt or section layout changes (like RUBRIC_PROMPT_VERSION). */
+export const COMPACTION_PROMPT_VERSION = 1;

package/dist/compaction/workingState.d.ts

@@ -0,0 +1,56 @@
+import type { WorkingStateEntry, WorkingStateKind } from "./types.js";
+export declare const WORKING_STATE_CUSTOM_TYPE = "stageflow.working_state";
+export declare const WORKING_STATE_KINDS: readonly WorkingStateKind[];
+export declare const WORKING_STATE_MAX_KEY = 80;
+export declare const WORKING_STATE_MAX_VALUE = 600;
+export declare const WORKING_STATE_MAX_ENTRIES = 60;
+export declare const WORKING_STATE_DEFAULT_RENDER_CHARS = 6000;
+export declare const WORKING_STATE_GUIDANCE = "Older messages and tool results are trimmed automatically as the conversation grows, so keep your own working state with the working_state tool. As soon as you learn or decide something you will need later, record it: exact values and identifiers (fact), choices and their reasons (decision), what is done (progress), what remains (todo) and what is stuck (blocker). Keep each entry to one or two short lines, update an existing key instead of adding a duplicate, and delete entries that no longer matter. Never store secrets or credentials in it.";
+export type WorkingStateEvent = {
+    op: "set";
+    key: string;
+    kind: WorkingStateKind;
+    value: string;
+    at: string;
+} | {
+    op: "delete";
+    key: string;
+    at: string;
+};
+export type WorkingStateSetResult = {
+    ok: true;
+    dropped: string[];
+    replaced: boolean;
+    redacted: boolean;
+    entry: WorkingStateEntry;
+} | {
+    ok: false;
+    error: string;
+};
+export type WorkingStateInput = {
+    key: string;
+    kind: WorkingStateKind;
+    value: string;
+    updatedAt?: string;
+};
+export declare class WorkingStateStore {
+    private readonly entries;
+    get size(): number;
+    set(input: WorkingStateInput): WorkingStateSetResult;
+    delete(key: string): boolean;
+    list(): WorkingStateEntry[];
+    apply(event: WorkingStateEvent): void;
+    load(events: readonly WorkingStateEvent[]): void;
+    render(maxChars?: number): string;
+    private oldestOfKind;
+}
+export declare function reduceWorkingState(events: readonly WorkingStateEvent[]): WorkingStateStore;
+type SessionEntryLike = {
+    type?: unknown;
+    customType?: unknown;
+    data?: unknown;
+};
+export declare function workingStateEventsFromEntries(entries: readonly SessionEntryLike[]): WorkingStateEvent[];
+export declare function restoreWorkingState(entries: readonly SessionEntryLike[]): WorkingStateStore;
+export declare function getWorkingStateSections(entries: readonly SessionEntryLike[]): WorkingStateEntry[];
+export {};

package/dist/compaction/workingState.js

@@ -0,0 +1,198 @@
+import { scrubSecrets } from "./scrub.js";
+export const WORKING_STATE_CUSTOM_TYPE = "stageflow.working_state";
+export const WORKING_STATE_KINDS = [
+    "fact",
+    "decision",
+    "progress",
+    "todo",
+    "blocker",
+];
+export const WORKING_STATE_MAX_KEY = 80;
+export const WORKING_STATE_MAX_VALUE = 600;
+export const WORKING_STATE_MAX_ENTRIES = 60;
+export const WORKING_STATE_DEFAULT_RENDER_CHARS = 6000;
+export const WORKING_STATE_GUIDANCE = "Older messages and tool results are trimmed automatically as the conversation grows, so keep your own working state with the working_state tool. As soon as you learn or decide something you will need later, record it: exact values and identifiers (fact), choices and their reasons (decision), what is done (progress), what remains (todo) and what is stuck (blocker). Keep each entry to one or two short lines, update an existing key instead of adding a duplicate, and delete entries that no longer matter. Never store secrets or credentials in it.";
+const RENDER_ORDER = [
+    "blocker",
+    "todo",
+    "decision",
+    "fact",
+    "progress",
+];
+const EVICTION_ORDER = [
+    "progress",
+    "fact",
+    "decision",
+    "todo",
+    "blocker",
+];
+const HEADINGS = {
+    blocker: "Blockers",
+    todo: "Todo",
+    decision: "Decisions",
+    fact: "Facts",
+    progress: "Progress",
+};
+function isKind(value) {
+    return (typeof value === "string" &&
+        WORKING_STATE_KINDS.includes(value));
+}
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+export class WorkingStateStore {
+    entries = new Map();
+    get size() {
+        return this.entries.size;
+    }
+    set(input) {
+        if (!isKind(input.kind)) {
+            return {
+                ok: false,
+                error: `kind must be one of ${WORKING_STATE_KINDS.join(", ")}`,
+            };
+        }
+        const rawKey = oneLine(String(input.key ?? ""));
+        const rawValue = oneLine(String(input.value ?? ""));
+        const key = oneLine(scrubSecrets(rawKey));
+        const value = oneLine(scrubSecrets(rawValue));
+        const redacted = key !== rawKey || value !== rawValue;
+        if (key.length === 0)
+            return { ok: false, error: "key is required" };
+        if (key.length > WORKING_STATE_MAX_KEY) {
+            return {
+                ok: false,
+                error: `key is ${key.length} chars; max ${WORKING_STATE_MAX_KEY}`,
+            };
+        }
+        if (value.length === 0)
+            return { ok: false, error: "value is required" };
+        if (value.length > WORKING_STATE_MAX_VALUE) {
+            return {
+                ok: false,
+                error: `value is ${value.length} chars; max ${WORKING_STATE_MAX_VALUE}. Shorten it.`,
+            };
+        }
+        const replaced = this.entries.delete(key);
+        const dropped = [];
+        while (this.entries.size >= WORKING_STATE_MAX_ENTRIES) {
+            const victim = this.oldestOfKind("progress");
+            if (victim === undefined) {
+                return {
+                    ok: false,
+                    error: `working state is full (${WORKING_STATE_MAX_ENTRIES} entries, none are progress). Delete entries first.`,
+                };
+            }
+            this.entries.delete(victim);
+            dropped.push(victim);
+        }
+        const entry = {
+            key,
+            kind: input.kind,
+            value,
+            updatedAt: input.updatedAt ?? new Date().toISOString(),
+        };
+        this.entries.set(key, entry);
+        return { ok: true, dropped, replaced, redacted, entry };
+    }
+    delete(key) {
+        const raw = oneLine(String(key ?? ""));
+        return this.entries.delete(raw) || this.entries.delete(oneLine(scrubSecrets(raw)));
+    }
+    list() {
+        return [...this.entries.values()];
+    }
+    apply(event) {
+        if (event.op === "set") {
+            this.set({
+                key: event.key,
+                kind: event.kind,
+                value: event.value,
+                updatedAt: event.at,
+            });
+        }
+        else if (event.op === "delete") {
+            this.delete(event.key);
+        }
+    }
+    load(events) {
+        this.entries.clear();
+        for (const event of events)
+            this.apply(event);
+    }
+    render(maxChars = WORKING_STATE_DEFAULT_RENDER_CHARS) {
+        const all = this.list();
+        if (all.length === 0)
+            return "";
+        const keep = new Set(all);
+        let omitted = 0;
+        const build = () => {
+            const lines = ["## Working state"];
+            for (const kind of RENDER_ORDER) {
+                const group = all.filter((e) => keep.has(e) && e.kind === kind);
+                if (group.length === 0)
+                    continue;
+                lines.push("", `### ${HEADINGS[kind]}`);
+                for (const e of group)
+                    lines.push(`- ${e.key}: ${e.value}`);
+            }
+            if (omitted > 0) {
+                lines.push("", `(${omitted} older entries omitted for space)`);
+            }
+            return lines.join("\n");
+        };
+        let text = build();
+        for (const kind of EVICTION_ORDER) {
+            for (const e of all) {
+                if (text.length <= maxChars)
+                    return text;
+                if (e.kind !== kind)
+                    continue;
+                keep.delete(e);
+                omitted += 1;
+                text = build();
+            }
+        }
+        return text.length <= maxChars ? text : text.slice(0, Math.max(0, maxChars));
+    }
+    oldestOfKind(kind) {
+        for (const e of this.entries.values()) {
+            if (e.kind === kind)
+                return e.key;
+        }
+        return undefined;
+    }
+}
+export function reduceWorkingState(events) {
+    const store = new WorkingStateStore();
+    for (const event of events)
+        store.apply(event);
+    return store;
+}
+function isEvent(data) {
+    if (data === null || typeof data !== "object")
+        return false;
+    const d = data;
+    if (typeof d.key !== "string")
+        return false;
+    if (d.op === "delete")
+        return true;
+    return d.op === "set" && isKind(d.kind) && typeof d.value === "string";
+}
+export function workingStateEventsFromEntries(entries) {
+    const events = [];
+    for (const entry of entries) {
+        if (entry.type === "custom" &&
+            entry.customType === WORKING_STATE_CUSTOM_TYPE &&
+            isEvent(entry.data)) {
+            events.push(entry.data);
+        }
+    }
+    return events;
+}
+export function restoreWorkingState(entries) {
+    return reduceWorkingState(workingStateEventsFromEntries(entries));
+}
+export function getWorkingStateSections(entries) {
+    return restoreWorkingState(entries).list();
+}

package/dist/config/createPipeline.js

@@ -1,5 +1,6 @@
 import { access, mkdir, readdir, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { ensureCatalogScanRoot } from "./ensureCatalogScanRoot.js";
 import { invertPredecessorEdgesToRoute, invertRouteToPredecessorEdges, parsePipelineNeeds, toPipelineNeeds, } from "./pipelineNeeds.js";
 import { STAGE_ID_PATTERN } from "./createStage.js";
 import { inferIdFromUsesPath, normalizePipelineStageEntries, toWiringRefs, } from "./normalizePipelineStageEntry.js";
@@ -548,6 +549,7 @@ export async function createPipeline(projectRoot, input) {
             error: errorFinding?.message ?? "Pipeline validation failed",
         };
     }
+    await ensureCatalogScanRoot(projectRoot, path.relative(projectRoot, pipelineDirectory));
     const loadOutcome = await loadPipelineOutcome(relPath, { cwd: projectRoot });
     if (!loadOutcome.ok) {
         await unlink(filePath).catch(() => { });

package/dist/config/createTrigger.js

@@ -6,6 +6,7 @@ import { STAGE_ID_PATTERN } from "./createStage.js";
 import { getCatalogScanPaths } from "./browseCatalog.js";
 import { catalogContextFromStageflow } from "./resolveCatalogContext.js";
 import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+import { githubMatchActionError } from "./githubTriggerAction.js";
 import { loadTriggerOutcome } from "./loadTrigger.js";
 import { collectPipelineIdsFromPaths, collectTaskIdsFromPaths } from "./validateCatalog.js";
 import { findCatalogPathById } from "../runtime/triggerCatalog.js";
@@ -56,11 +57,16 @@ export function parseEventField(raw) {
     if (raw.config !== undefined && !isPlainObject(raw.config)) {
         return { ok: false, message: "event.config must be an object" };
     }
+    const match = isPlainObject(raw.match) ? raw.match : undefined;
+    const actionError = githubMatchActionError(raw.source, match);
+    if (actionError !== undefined) {
+        return { ok: false, message: actionError };
+    }
     return {
         ok: true,
         value: {
             source: raw.source,
-            ...(isPlainObject(raw.match) ? { match: raw.match } : {}),
+            ...(match !== undefined ? { match } : {}),
             ...(isPlainObject(raw.config) ? { config: raw.config } : {}),
         },
     };

package/dist/config/ensureCatalogScanRoot.d.ts

@@ -1,6 +1,8 @@
 import type { CatalogRootKind } from "./resolveCatalogRoots.js";
 /** Directory scanned for workshop-authored pipelines and tasks. */
 export declare const WORKSHOP_PACKAGE_ROOT = "workshop";
+/** Directory the Guide always uses for pipeline packages and their stage files. */
+export declare const GUIDE_PIPELINES_ROOT = "pipelines";
 export declare function normalizeCatalogDir(directory: string): string;
 /** Untitled workshop saves land here so Run can see them without a new catalog edit. */
 export declare function defaultWorkshopPackageDirectory(pipelineId: string | undefined, catalogRootKind?: CatalogRootKind): string;

package/dist/config/ensureCatalogScanRoot.js

@@ -3,6 +3,8 @@ import { isSeq, parseDocument } from "yaml";
 import { manifestPathForProject } from "./loadStageflowManifest.js";
 /** Directory scanned for workshop-authored pipelines and tasks. */
 export const WORKSHOP_PACKAGE_ROOT = "workshop";
+/** Directory the Guide always uses for pipeline packages and their stage files. */
+export const GUIDE_PIPELINES_ROOT = "pipelines";
 export function normalizeCatalogDir(directory) {
     return directory.replace(/\\/g, "/").replace(/^\.\/+/, "").replace(/\/+$/, "");
 }
@@ -30,6 +32,10 @@ export function catalogScanRootForDirectory(directory) {
         normalized.startsWith(`${WORKSHOP_PACKAGE_ROOT}/`)) {
         return WORKSHOP_PACKAGE_ROOT;
     }
+    if (normalized === GUIDE_PIPELINES_ROOT ||
+        normalized.startsWith(`${GUIDE_PIPELINES_ROOT}/`)) {
+        return GUIDE_PIPELINES_ROOT;
+    }
     return normalized;
 }
 function isCovered(entries, root) {

package/dist/config/evalCatalog.js

@@ -1,5 +1,6 @@
 import { stat } from "node:fs/promises";
 import path from "node:path";
+import { isInsideProjectRoot } from "./catalogRelativePath.js";
 import { getModelCatalog } from "../models/catalog.js";
 import { loadDatasetFile } from "./loadDataset.js";
 import { loadEvalOutcome, resolveEvalPaths } from "./loadEval.js";
@@ -15,8 +16,35 @@ async function listFiles(manifest, kind) {
 export function listEvalFiles(manifest) {
     return listFiles(manifest, "eval");
 }
-export function listDatasetFiles(manifest) {
-    return listFiles(manifest, "dataset");
+export async function listDatasetFiles(manifest) {
+    const scanned = await listFiles(manifest, "dataset");
+    const referenced = await datasetsReferencedByEvals(manifest, scanned);
+    return [...scanned, ...referenced].sort((a, b) => (a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0));
+}
+async function datasetsReferencedByEvals(manifest, scanned) {
+    const seen = new Set(scanned.map((ref) => path.resolve(ref.absPath)));
+    const extra = [];
+    for (const ref of await listFiles(manifest, "eval")) {
+        const outcome = await loadEvalOutcome(ref.absPath, manifest.projectRoot);
+        if (!outcome.ok)
+            continue;
+        const abs = path.resolve(resolveEvalPaths(outcome.value.file, outcome.value.path).datasetPath);
+        if (seen.has(abs) || !isInsideProjectRoot(manifest.projectRoot, abs))
+            continue;
+        try {
+            if (!(await stat(abs)).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        seen.add(abs);
+        extra.push({
+            absPath: abs,
+            relPath: path.relative(manifest.projectRoot, abs).split(path.sep).join("/"),
+        });
+    }
+    return extra;
 }
 export async function loadEvalCatalog(manifest, options = {}) {
     const refs = await listEvalFiles(manifest);

package/dist/config/githubTriggerAction.d.ts

@@ -0,0 +1,8 @@
+export declare const GITHUB_TRIGGER_ACTIONS: readonly ["opened", "synchronize", "updated", "merged", "closed"];
+export type GithubTriggerAction = (typeof GITHUB_TRIGGER_ACTIONS)[number];
+export declare function isGithubTriggerAction(value: unknown): value is GithubTriggerAction;
+/**
+ * For `event.source` values starting with `github.`, `match.action` must be set
+ * to one of the five PR poll actions. Returns an error message or undefined.
+ */
+export declare function githubMatchActionError(source: string, match: Record<string, unknown> | undefined): string | undefined;