stageflow 0.33.0 → 0.36.0

package/dist/config/validateCatalog.js

@@ -1,3 +1,5 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import path from "node:path";
 import { globalStageflowHome } from "../project/globalHome.js";
 import { INLINE_PIPELINE_PATH, loadPipelineFromObjectOutcome, loadPipelineOutcome, resolvePipelinePath, } from "./loadPipeline.js";
@@ -12,6 +14,9 @@ import { MCP_CATALOG_FILENAME, StageMcpError, assertMcpAllowlistKnown, loadMcpCa
 import { loadSecretRegistry } from "../runtime/stageSecrets.js";
 import { isForeverDeniedSecret } from "../runtime/stageEnvironment.js";
 import { findMissingMcpCommands } from "../preflight/mcpCommands.js";
+import { ChannelError } from "../channels/errors.js";
+import { ChannelRegistry } from "../channels/registry.js";
+import { validateStageChannels } from "../channels/stageChannels.js";
 export function relPath(cwd, absPath) {
     return path.relative(cwd, absPath).replace(/\\/g, "/");
 }
@@ -122,12 +127,21 @@ function findingCatalog(cwd, absPath, message, code, severity) {
         category: "catalog",
     }, severity);
 }
+function withIssueLocation(finding, issue) {
+    if (issue.line === undefined && issue.column === undefined)
+        return finding;
+    return {
+        ...finding,
+        ...(issue.line !== undefined ? { line: issue.line } : {}),
+        ...(issue.column !== undefined ? { column: issue.column } : {}),
+    };
+}
 export function findingsFromLoadIssues(cwd, absPath, issues) {
     return issues.flatMap((issue) => {
         if (issue.category === "pipeline") {
             if (issue.code === "pipeline.model_applies" || issue.code === "pipeline.route_all_gated") {
                 return [
-                    baseFinding({
+                    withIssueLocation(baseFinding({
                         cwd,
                         absPath,
                         message: issue.message,
@@ -135,26 +149,26 @@ export function findingsFromLoadIssues(cwd, absPath, issues) {
                         category: "pipeline",
                         pipelineId: issue.pipelineId,
                         stageId: issue.stageId,
-                    }, "warning"),
+                    }, "warning"), issue),
                 ];
             }
             return [
-                findingPipelineError(cwd, absPath, issue.message, issue.code, issue.pipelineId, issue.stageId),
+                withIssueLocation(findingPipelineError(cwd, absPath, issue.message, issue.code, issue.pipelineId, issue.stageId), issue),
             ];
         }
         if (issue.category === "stage") {
             return [
-                findingStageError(cwd, absPath, issue.message, issue.code, issue.stageId),
+                withIssueLocation(findingStageError(cwd, absPath, issue.message, issue.code, issue.stageId), issue),
             ];
         }
         if (issue.category === "task") {
             return [
-                findingTaskError(cwd, absPath, issue.message, issue.code),
+                withIssueLocation(findingTaskError(cwd, absPath, issue.message, issue.code), issue),
             ];
         }
         if (issue.category === "trigger") {
             return [
-                findingTriggerError(cwd, absPath, issue.message, issue.code),
+                withIssueLocation(findingTriggerError(cwd, absPath, issue.message, issue.code), issue),
             ];
         }
         if (issue.category === "catalog") {
@@ -164,7 +178,7 @@ export function findingsFromLoadIssues(cwd, absPath, issues) {
                 code === "catalog.legacy_yaml"
                 ? "warning"
                 : "error";
-            return [findingCatalog(cwd, absPath, issue.message, code, severity)];
+            return [withIssueLocation(findingCatalog(cwd, absPath, issue.message, code, severity), issue)];
         }
         return [];
     });
@@ -245,6 +259,23 @@ function collectMcpAllowlistNames(loaded) {
     }
     return [...names];
 }
+function findingsForStageChannels(cwd, pipelinePath, loaded, projectRoot, providers) {
+    const users = loaded.stages.filter((stage) => (stage.channels?.length ?? 0) > 0);
+    if (users.length === 0)
+        return [];
+    let registry;
+    try {
+        registry = new ChannelRegistry({ cwd: projectRoot, providers });
+    }
+    catch (error) {
+        const code = error instanceof ChannelError ? error.code : "CHANNEL_INVALID_INPUT";
+        const field = error instanceof ChannelError && error.detail?.connectionId
+            ? ` (connection "${error.detail.connectionId}"${error.detail.field ? `, field "${error.detail.field}"` : ""})`
+            : "";
+        return users.map((stage) => findingStageError(cwd, pipelinePath, `connections.yaml could not be loaded: ${code}${field}`, "stage.channel_unavailable", stage.id));
+    }
+    return users.flatMap((stage) => validateStageChannels(registry, stage).map((issue) => findingStageError(cwd, pipelinePath, issue.message, "stage.channel_unavailable", issue.stageId)));
+}
 function findingsForStageSecrets(cwd, pipelinePath, loaded) {
     const registry = loadSecretRegistry(process.env);
     const findings = [];
@@ -427,6 +458,7 @@ async function runPipelineValidation(nameOrPath, options) {
     }
     findings.push(...(await findingsForStageMcpCatalog(cwd, outcome.value)));
     findings.push(...findingsForStageSecrets(cwd, pipelinePath, outcome.value));
+    findings.push(...findingsForStageChannels(cwd, pipelinePath, outcome.value, projectRoot, options.channelProviders));
     findings.push(...findingsForStageflowHomeAbsolutePaths(cwd, outcome.value));
     if (validateStages && outcome.value.stageSources) {
         for (const source of Object.values(outcome.value.stageSources)) {
@@ -450,6 +482,7 @@ export async function validatePipeline(nameOrPath, options = {}) {
         cwd,
         projectRoot,
         validateStages,
+        channelProviders: options.channelProviders,
     });
     return buildValidationResult("pipeline", core.findings, strict);
 }
@@ -461,6 +494,7 @@ export async function loadPipelineValidated(nameOrPath, options = {}) {
         cwd,
         projectRoot,
         validateStages,
+        channelProviders: options.channelProviders,
     });
     if (core.ok) {
         return { ok: true, loaded: core.loaded, findings: core.findings };
@@ -615,6 +649,30 @@ async function validateSingleTask(invocationCwd, taskArg) {
     }
     return [];
 }
+async function validateSingleStage(invocationCwd, stageArg, stageContent) {
+    const ctx = await resolveCatalogContext(invocationCwd);
+    const relCwd = ctx.projectRoot ?? invocationCwd;
+    const stagePath = path.resolve(invocationCwd, stageArg);
+    if (stageContent === undefined) {
+        return validateStageFile(relCwd, stagePath);
+    }
+    const tmpDir = await mkdtemp(path.join(tmpdir(), "sf-stage-validate-"));
+    const tmpPath = path.join(tmpDir, path.basename(stagePath));
+    try {
+        await writeFile(tmpPath, stageContent, "utf8");
+        const findings = await validateStageFile(relCwd, tmpPath);
+        const displayPath = relPath(relCwd, stagePath);
+        const tmpRel = relPath(relCwd, tmpPath);
+        return findings.map((finding) => finding.path === tmpRel ||
+            finding.path === tmpPath ||
+            finding.path.includes(tmpDir)
+            ? { ...finding, path: displayPath }
+            : finding);
+    }
+    finally {
+        await rm(tmpDir, { recursive: true, force: true });
+    }
+}
 async function validateSingleTrigger(invocationCwd, triggerArg) {
     const ctx = await resolveCatalogContext(invocationCwd);
     const relCwd = ctx.projectRoot ?? invocationCwd;
@@ -647,6 +705,9 @@ export async function validateCatalog(options) {
     if (options.scope === "trigger" && !options.trigger) {
         throw new Error("validateCatalog: trigger is required when scope is \"trigger\"");
     }
+    if (options.scope === "stage" && !options.stage) {
+        throw new Error("validateCatalog: stage is required when scope is \"stage\"");
+    }
     const allFindings = [];
     if (options.scope === "pipeline") {
         return validatePipeline(options.pipeline, {
@@ -662,6 +723,9 @@ export async function validateCatalog(options) {
     else if (options.scope === "trigger") {
         allFindings.push(...(await validateSingleTrigger(cwd, options.trigger)));
     }
+    else if (options.scope === "stage") {
+        allFindings.push(...(await validateSingleStage(cwd, options.stage, options.stageContent)));
+    }
     else {
         allFindings.push(...(await validateManifestAll(cwd)));
     }

package/dist/config/workshopCatalogFilenames.d.ts

@@ -0,0 +1,37 @@
+export declare function normalizePipelineCatalogFilename(pipelineId: string, filename?: string | null): string;
+export declare function taskIdFromDraftTask(task: {
+    filename?: string;
+    body?: Record<string, unknown>;
+}): string;
+export declare function normalizeTaskCatalogFilename(taskId: string, filename?: string | null): string;
+export type DraftTaskArtifact = {
+    filename: string;
+    body: Record<string, unknown>;
+};
+export type DraftPackageFilenames = {
+    pipeline: {
+        id: string;
+    };
+    task?: DraftTaskArtifact;
+};
+export type CatalogYamlKind = "pipeline" | "task" | "other";
+export declare function classifyCatalogYamlDocument(raw: Record<string, unknown>): CatalogYamlKind;
+export declare function legacyBareCatalogFilenames(entityId: string): string[];
+export declare function isMisnamedCatalogBasename(basename: string): boolean;
+export declare function canonicalCatalogBasenameForDocument(raw: Record<string, unknown>, sourceBasename?: string): string | null;
+export type WorkshopCatalogRepairMove = {
+    from: string;
+    to: string;
+};
+export type WorkshopCatalogRepairResult = {
+    renamed: WorkshopCatalogRepairMove[];
+    removed: string[];
+};
+export declare function reconcileWorkshopCatalogFilenames(pipelineId: string, taskId?: string | null, canonicalPipelineBasename?: string, canonicalTaskBasename?: string | null): {
+    renameCandidates: WorkshopCatalogRepairMove[];
+    removeCandidates: string[];
+};
+export declare function normalizeDraftCatalogFilenames<T extends DraftPackageFilenames>(draft: T, pipelineFilename?: string | null): {
+    draft: T;
+    pipelineFilename: string;
+};

package/dist/config/workshopCatalogFilenames.js

@@ -0,0 +1,125 @@
+const PIPELINE_SUFFIX = ".pipeline.yaml";
+const TASK_SUFFIX = ".task.yaml";
+function basenameOnly(name) {
+    const trimmed = name.trim();
+    const parts = trimmed.split(/[\\/]/);
+    return parts[parts.length - 1]?.trim() || trimmed;
+}
+export function normalizePipelineCatalogFilename(pipelineId, filename) {
+    const id = pipelineId.trim() || "untitled";
+    const base = filename?.trim() ? basenameOnly(filename) : "";
+    if (base.endsWith(PIPELINE_SUFFIX)) {
+        const stem = base.slice(0, -PIPELINE_SUFFIX.length);
+        if (stem === id)
+            return base;
+    }
+    return `${id}${PIPELINE_SUFFIX}`;
+}
+export function taskIdFromDraftTask(task) {
+    const bodyId = task.body?.id;
+    if (typeof bodyId === "string" && bodyId.trim())
+        return bodyId.trim();
+    const base = task.filename?.trim() ? basenameOnly(task.filename) : "";
+    if (!base)
+        return "task";
+    return (base
+        .replace(/\.task\.ya?ml$/i, "")
+        .replace(/\.ya?ml$/i, "")
+        .trim() || "task");
+}
+export function normalizeTaskCatalogFilename(taskId, filename) {
+    const id = taskId.trim() || "task";
+    const base = filename?.trim() ? basenameOnly(filename) : "";
+    if (base.endsWith(TASK_SUFFIX)) {
+        const stem = base.slice(0, -TASK_SUFFIX.length);
+        if (stem === id)
+            return base;
+    }
+    return `${id}${TASK_SUFFIX}`;
+}
+const CATALOG_KIND_SUFFIX_PATTERN = /\.(pipeline|task|trigger)\.ya?ml$/i;
+const BARE_YAML_PATTERN = /\.ya?ml$/i;
+export function classifyCatalogYamlDocument(raw) {
+    if (Array.isArray(raw.stages))
+        return "pipeline";
+    if (typeof raw.goal === "string" || typeof raw.pipeline === "string") {
+        return "task";
+    }
+    return "other";
+}
+export function legacyBareCatalogFilenames(entityId) {
+    const id = entityId.trim();
+    if (!id)
+        return [];
+    return [`${id}.yaml`, `${id}.yml`];
+}
+export function isMisnamedCatalogBasename(basename) {
+    const name = basename.trim();
+    if (!BARE_YAML_PATTERN.test(name))
+        return false;
+    if (!CATALOG_KIND_SUFFIX_PATTERN.test(name))
+        return true;
+    return /\.(pipeline|task)\.yml$/i.test(name);
+}
+export function canonicalCatalogBasenameForDocument(raw, sourceBasename) {
+    const kind = classifyCatalogYamlDocument(raw);
+    const id = raw.id;
+    if (typeof id !== "string" || !id.trim())
+        return null;
+    if (kind === "pipeline")
+        return normalizePipelineCatalogFilename(id);
+    if (kind === "task")
+        return normalizeTaskCatalogFilename(id);
+    if (sourceBasename && CATALOG_KIND_SUFFIX_PATTERN.test(sourceBasename)) {
+        const stem = sourceBasename.replace(/\.ya?ml$/i, "");
+        const kindSuffix = stem.match(/\.(pipeline|task|trigger)$/i)?.[1]?.toLowerCase();
+        if (kindSuffix === "pipeline") {
+            return normalizePipelineCatalogFilename(id);
+        }
+        if (kindSuffix === "task") {
+            return normalizeTaskCatalogFilename(id);
+        }
+    }
+    return null;
+}
+export function reconcileWorkshopCatalogFilenames(pipelineId, taskId, canonicalPipelineBasename, canonicalTaskBasename) {
+    const renameCandidates = [];
+    const removeCandidates = [];
+    const pipelineCanonical = canonicalPipelineBasename?.trim() ||
+        normalizePipelineCatalogFilename(pipelineId);
+    const taskCanonical = taskId?.trim()
+        ? canonicalTaskBasename?.trim() ||
+            normalizeTaskCatalogFilename(taskId)
+        : null;
+    for (const legacy of legacyBareCatalogFilenames(pipelineId)) {
+        if (legacy === pipelineCanonical)
+            continue;
+        removeCandidates.push(legacy);
+    }
+    if (taskId?.trim()) {
+        for (const legacy of legacyBareCatalogFilenames(taskId)) {
+            if (legacy === taskCanonical || legacy === pipelineCanonical)
+                continue;
+            removeCandidates.push(legacy);
+        }
+    }
+    return { renameCandidates, removeCandidates };
+}
+export function normalizeDraftCatalogFilenames(draft, pipelineFilename) {
+    const pipelineFilenameOut = normalizePipelineCatalogFilename(draft.pipeline.id, pipelineFilename);
+    if (!draft.task) {
+        return { draft, pipelineFilename: pipelineFilenameOut };
+    }
+    const taskId = taskIdFromDraftTask(draft.task);
+    const taskFilename = normalizeTaskCatalogFilename(taskId, draft.task.filename);
+    if (taskFilename === draft.task.filename) {
+        return { draft, pipelineFilename: pipelineFilenameOut };
+    }
+    return {
+        draft: {
+            ...draft,
+            task: { ...draft.task, filename: taskFilename },
+        },
+        pipelineFilename: pipelineFilenameOut,
+    };
+}

package/dist/config/workshopCatalogRepair.d.ts

@@ -0,0 +1,7 @@
+import { type WorkshopCatalogRepairResult } from "./workshopCatalogFilenames.js";
+export declare function repairMisnamedWorkshopCatalogFiles(packageDirectory: string): Promise<WorkshopCatalogRepairResult>;
+export declare function reconcileWorkshopCatalogPackageDir(packageDirectory: string, pipelineId: string, taskId?: string | null, options?: {
+    pipelineBasename?: string;
+    taskBasename?: string | null;
+}): Promise<WorkshopCatalogRepairResult>;
+export declare function repairWorkshopCatalogTree(projectRoot: string, relativeDirectories: string[]): Promise<WorkshopCatalogRepairResult>;

package/dist/config/workshopCatalogRepair.js

@@ -0,0 +1,144 @@
+import { readdir, rename, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { readYamlObject } from "./readYamlObject.js";
+import { canonicalCatalogBasenameForDocument, isMisnamedCatalogBasename, legacyBareCatalogFilenames, normalizePipelineCatalogFilename, normalizeTaskCatalogFilename, reconcileWorkshopCatalogFilenames, } from "./workshopCatalogFilenames.js";
+async function fileExists(absPath) {
+    try {
+        await stat(absPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function renameIfNeeded(fromAbs, toAbs, renamed) {
+    if (fromAbs === toAbs)
+        return;
+    if (!(await fileExists(fromAbs)))
+        return;
+    if (await fileExists(toAbs)) {
+        await rm(fromAbs, { force: true });
+        return;
+    }
+    await rename(fromAbs, toAbs);
+    renamed.push({
+        from: path.basename(fromAbs),
+        to: path.basename(toAbs),
+    });
+}
+export async function repairMisnamedWorkshopCatalogFiles(packageDirectory) {
+    const renamed = [];
+    const removed = [];
+    let entries;
+    try {
+        entries = await readdir(packageDirectory);
+    }
+    catch {
+        return { renamed, removed };
+    }
+    for (const entry of entries) {
+        if (!isMisnamedCatalogBasename(entry))
+            continue;
+        const absPath = path.join(packageDirectory, entry);
+        let raw;
+        try {
+            raw = await readYamlObject(absPath);
+        }
+        catch {
+            continue;
+        }
+        const canonical = canonicalCatalogBasenameForDocument(raw, entry);
+        if (!canonical || canonical === entry)
+            continue;
+        const targetAbs = path.join(packageDirectory, canonical);
+        await renameIfNeeded(absPath, targetAbs, renamed);
+    }
+    return { renamed, removed };
+}
+export async function reconcileWorkshopCatalogPackageDir(packageDirectory, pipelineId, taskId, options) {
+    const result = await repairMisnamedWorkshopCatalogFiles(packageDirectory);
+    const pipelineBasename = options?.pipelineBasename?.trim() ||
+        normalizePipelineCatalogFilename(pipelineId);
+    const taskBasename = taskId?.trim()
+        ? options?.taskBasename?.trim() ||
+            normalizeTaskCatalogFilename(taskId)
+        : null;
+    for (const legacy of legacyBareCatalogFilenames(pipelineId)) {
+        if (legacy === pipelineBasename)
+            continue;
+        const legacyAbs = path.join(packageDirectory, legacy);
+        const canonicalAbs = path.join(packageDirectory, pipelineBasename);
+        if (!(await fileExists(legacyAbs)))
+            continue;
+        if (!(await fileExists(canonicalAbs))) {
+            let raw;
+            try {
+                raw = await readYamlObject(legacyAbs);
+            }
+            catch {
+                continue;
+            }
+            if (canonicalCatalogBasenameForDocument(raw) === pipelineBasename) {
+                await renameIfNeeded(legacyAbs, canonicalAbs, result.renamed);
+                continue;
+            }
+        }
+        if (await fileExists(canonicalAbs)) {
+            await rm(legacyAbs, { force: true });
+            result.removed.push(legacy);
+        }
+    }
+    if (taskId?.trim() && taskBasename) {
+        for (const legacy of legacyBareCatalogFilenames(taskId)) {
+            if (legacy === taskBasename || legacy === pipelineBasename)
+                continue;
+            const legacyAbs = path.join(packageDirectory, legacy);
+            const canonicalAbs = path.join(packageDirectory, taskBasename);
+            if (!(await fileExists(legacyAbs)))
+                continue;
+            if (!(await fileExists(canonicalAbs))) {
+                let raw;
+                try {
+                    raw = await readYamlObject(legacyAbs);
+                }
+                catch {
+                    continue;
+                }
+                if (canonicalCatalogBasenameForDocument(raw) === taskBasename) {
+                    await renameIfNeeded(legacyAbs, canonicalAbs, result.renamed);
+                    continue;
+                }
+            }
+            if (await fileExists(canonicalAbs)) {
+                await rm(legacyAbs, { force: true });
+                result.removed.push(legacy);
+            }
+        }
+    }
+    const { removeCandidates } = reconcileWorkshopCatalogFilenames(pipelineId, taskId, pipelineBasename, taskBasename);
+    for (const legacy of removeCandidates) {
+        const legacyAbs = path.join(packageDirectory, legacy);
+        const canonicalAbs = path.join(packageDirectory, pipelineBasename);
+        if (!(await fileExists(legacyAbs)))
+            continue;
+        if (legacyAbs === canonicalAbs)
+            continue;
+        if (taskBasename && legacy === taskBasename)
+            continue;
+        if (!(await fileExists(canonicalAbs)))
+            continue;
+        await rm(legacyAbs, { force: true });
+        result.removed.push(legacy);
+    }
+    return result;
+}
+export async function repairWorkshopCatalogTree(projectRoot, relativeDirectories) {
+    const merged = { renamed: [], removed: [] };
+    for (const rel of relativeDirectories) {
+        const dir = path.resolve(projectRoot, rel);
+        const part = await repairMisnamedWorkshopCatalogFiles(dir);
+        merged.renamed.push(...part.renamed);
+        merged.removed.push(...part.removed);
+    }
+    return merged;
+}

package/dist/config/yamlParsePosition.d.ts

@@ -0,0 +1,4 @@
+export declare function yamlParsePosition(err: unknown): {
+    line: number;
+    column: number;
+} | undefined;

package/dist/config/yamlParsePosition.js

@@ -0,0 +1,9 @@
+import { YAMLParseError } from "yaml";
+export function yamlParsePosition(err) {
+    if (!(err instanceof YAMLParseError))
+        return undefined;
+    const pos = err.linePos?.[0];
+    if (!pos)
+        return undefined;
+    return { line: pos.line, column: pos.col };
+}

package/dist/errors/codes.d.ts

@@ -4,7 +4,7 @@ export declare const BUSY_CHECKOUT: "busy_checkout";
 /** Per-caller concurrency quota: queued when under global capacity; reject when queue full. */
 export declare const BUSY_CALLER_QUOTA: "busy_caller_quota";
 export declare const ABORTED: "aborted";
-export declare const NETWORK_ERROR_CODES: readonly ["busy_capacity", "busy_checkout", "busy_caller_quota", "aborted", "unknown_project_root", "absolute_path_not_allowed", "path_outside_project_root", "catalog_root_unreadable", "ensure_project_not_allowed", "config_invalid", "config_unknown_key", "provider_not_configured", "a2a_configuration_error", "untrusted_config_origin", "command_not_on_path", "missing_tool", "tool_version_mismatch", "unknown_version", "secret_unavailable", "not_ready", "internal_error", "retry_in_progress", "hitl_not_retriable", "run_not_retryable", "stage_not_failed", "manual_recovery_required", "run_not_found", "stage_not_found", "artifact_not_found", "artifact_path_denied", "envelope_not_found", "insufficient_disk", "disk_check_failed", "shutting_down", "start.token_rejected", "inline_pipeline_too_large", "skills_invalid_name", "skills_invalid_path", "skills_missing_skill_md", "skills_payload_too_large", "pinned_sha_unavailable", "store_integrity_failed", "store_unsupported_filesystem", "tmpdir_unusable", "backup_insufficient_disk"];
+export declare const NETWORK_ERROR_CODES: readonly ["busy_capacity", "busy_checkout", "busy_caller_quota", "aborted", "unknown_project_root", "absolute_path_not_allowed", "path_outside_project_root", "catalog_root_unreadable", "ensure_project_not_allowed", "config_invalid", "config_unknown_key", "provider_not_configured", "a2a_configuration_error", "untrusted_config_origin", "command_not_on_path", "missing_tool", "tool_version_mismatch", "unknown_version", "secret_unavailable", "channel_check_failed", "not_ready", "internal_error", "retry_in_progress", "hitl_not_retriable", "run_not_retryable", "stage_not_failed", "manual_recovery_required", "run_not_found", "stage_not_found", "artifact_not_found", "artifact_path_denied", "envelope_not_found", "insufficient_disk", "disk_check_failed", "shutting_down", "start.token_rejected", "inline_pipeline_too_large", "skills_invalid_name", "skills_invalid_path", "skills_missing_skill_md", "skills_payload_too_large", "pinned_sha_unavailable", "store_integrity_failed", "store_unsupported_filesystem", "tmpdir_unusable", "backup_insufficient_disk"];
 export type NetworkErrorCode = (typeof NETWORK_ERROR_CODES)[number] | string;
 export type NetworkErrorBody = {
     code: NetworkErrorCode;

package/dist/errors/codes.js

@@ -24,6 +24,7 @@ export const NETWORK_ERROR_CODES = [
     "tool_version_mismatch",
     "unknown_version",
     "secret_unavailable",
+    "channel_check_failed",
     "not_ready",
     "internal_error",
     "retry_in_progress",

package/dist/hosted/runtime.d.ts

@@ -1,11 +1,11 @@
-import type { AgentPort } from "../agent/port.js";
+import type { StagePort } from "../agent/port.js";
 import type { RunStore } from "../runstore/port.js";
 import { type HostedEventSink, type HostedPipelineInput, type HostedPipelineResult } from "./types.js";
 export type HostedRuntime = {
     run(input: HostedPipelineInput): Promise<HostedPipelineResult>;
 };
 export declare function createHostedRuntime(dependencies: {
-    agent: AgentPort;
+    agent: StagePort;
     localStore: RunStore;
     eventSink: HostedEventSink;
     eventDeliveryTimeoutMs?: number;

package/dist/hosted/types.d.ts

@@ -7,7 +7,7 @@ export declare const HOSTED_DELIVERY_ATTEMPTS = 2;
 export declare const DEFAULT_EVENT_DELIVERY_TIMEOUT_MS = 10000;
 /**
  * After cancellation or timeout, Core waits at most this long for in-flight
- * stage work to stop. `AgentPort` handles must stop inside `close()`.
+ * stage work to stop. `StagePort` handles must stop inside `close()`.
  */
 export declare const HOSTED_CANCEL_GRACE_MS = 5000;
 export type HostedRunContext = {

package/dist/hosted/types.js

@@ -5,6 +5,6 @@ export const HOSTED_DELIVERY_ATTEMPTS = 2;
 export const DEFAULT_EVENT_DELIVERY_TIMEOUT_MS = 10_000;
 /**
  * After cancellation or timeout, Core waits at most this long for in-flight
- * stage work to stop. `AgentPort` handles must stop inside `close()`.
+ * stage work to stop. `StagePort` handles must stop inside `close()`.
  */
 export const HOSTED_CANCEL_GRACE_MS = 5_000;

package/dist/index.d.ts

@@ -5,8 +5,9 @@ export { resolveStageflowContext, projectContextFromStageflow, type StageflowCon
 export { PACKAGE_NAME, PACKAGE_VERSION } from "./package-meta.js";
 export type { StageEnvelope } from "./types/envelope.js";
 export { assertRequiredEnvelope, isAdvancingEnvelope, } from "./envelope/check.js";
-export type { AgentPort, StageHandle, StageHandleEvent, StageRunInput, StageRunResult, } from "./agent/port.js";
-export { createPiAgentPort } from "./agent/resolveAgentPort.js";
+export type { StagePort, StageHandle, StageHandleEvent, StageRunInput, StageRunResult, } from "./agent/port.js";
+export { createPiStagePort } from "./agent/resolveStagePort.js";
+export { createPiAgentPort, resolveAgentPort, type AgentPort, } from "./operatorAgent/agentPort.js";
 export { configurePiProviderApiKey } from "./agent/providerAuth.js";
 export type { StageActivityEvent, StageLogLine } from "./agent/activity.js";
 export type { StageRoots } from "./runtime/stageRoots.js";

package/dist/index.js

@@ -4,7 +4,8 @@ export { resolveProjectContext, legacyProjectContext, } from "./project/resolveP
 export { resolveStageflowContext, projectContextFromStageflow, } from "./project/resolveStageflowContext.js";
 export { PACKAGE_NAME, PACKAGE_VERSION } from "./package-meta.js";
 export { assertRequiredEnvelope, isAdvancingEnvelope, } from "./envelope/check.js";
-export { createPiAgentPort } from "./agent/resolveAgentPort.js";
+export { createPiStagePort } from "./agent/resolveStagePort.js";
+export { createPiAgentPort, resolveAgentPort, } from "./operatorAgent/agentPort.js";
 export { configurePiProviderApiKey } from "./agent/providerAuth.js";
 export { runPipeline, startPipeline } from "./runtime/pipelineRunner.js";
 export { createHostedRuntime, } from "./hosted/runtime.js";

package/dist/mcp/catalogTools.js

@@ -63,6 +63,7 @@ const inlinePipelineSchema = z
     model: z.unknown().optional(),
     schemas: z.unknown().optional(),
     requires: z.unknown().optional(),
+    channels: z.unknown().optional(),
 })
     .strict();
 const startRunSchema = z

package/dist/mcp/getStartedTool.js

@@ -29,9 +29,12 @@ export function registerGetStartedTool(server, deps) {
             task_count: tasks.items.filter((t) => t.project_root === root.project_root)
                 .length,
         }));
-        const firstRoot = catalog_roots.find((r) => r.kind === "seeded") ?? catalog_roots[0];
-        const samplePipeline = pipelines.items.find((p) => p.project_root === firstRoot?.project_root);
-        const sampleTask = tasks.items.find((t) => t.project_root === firstRoot?.project_root);
+        const authoringRoot = catalog_roots.find((r) => r.kind === "workspace" && r.read_only !== true) ??
+            catalog_roots.find((r) => r.kind === "registered") ??
+            catalog_roots[0];
+        const browseRoot = catalog_roots.find((r) => r.kind === "seeded") ?? authoringRoot;
+        const samplePipeline = pipelines.items.find((p) => p.project_root === browseRoot?.project_root);
+        const sampleTask = tasks.items.find((t) => t.project_root === browseRoot?.project_root);
         return textResult({
             host: { version: PACKAGE_VERSION },
             providers: deps.providerAuthContext
@@ -42,16 +45,22 @@ export function registerGetStartedTool(server, deps) {
             next_steps: [
                 {
                     tool: "list_pipelines",
-                    args: firstRoot ? { project_root: firstRoot.project_root } : {},
+                    args: authoringRoot
+                        ? { project_root: authoringRoot.project_root }
+                        : {},
                 },
                 {
                     tool: "list_tasks",
-                    args: firstRoot ? { project_root: firstRoot.project_root } : {},
+                    args: authoringRoot
+                        ? { project_root: authoringRoot.project_root }
+                        : {},
                 },
                 {
                     tool: "start_run",
                     args: {
-                        ...(firstRoot ? { project_root: firstRoot.project_root } : {}),
+                        ...(authoringRoot
+                            ? { project_root: authoringRoot.project_root }
+                            : {}),
                         pipeline: samplePipeline?.path ?? "pipelines/demo.pipeline.yaml",
                         task_path: sampleTask?.path ?? "tasks/demo.task.yaml",
                     },