stageflow 0.42.0 → 0.46.0

package/dist/guide/cardContract.d.ts

@@ -0,0 +1,133 @@
+export declare const GUIDE_LINK_KINDS: readonly ["pipeline", "stage", "task", "agent", "trigger", "eval", "eval_run", "dataset", "connection", "memory", "run"];
+export declare const GUIDE_RESOURCE_KINDS: readonly ["agent", "trigger", "eval", "connection", "memory", "task"];
+export declare const GUIDE_UI_COMPONENTS: readonly ["pipeline", "resource", "plan", "choices", "eval_report", "links"];
+export declare const GUIDE_UI_MAX_TEXT = 300;
+export declare const GUIDE_UI_MAX_PLAN_STEPS = 12;
+export declare const GUIDE_UI_MAX_CHOICES = 6;
+export declare const GUIDE_UI_MAX_LINKS = 8;
+export declare const GUIDE_UI_MAX_FAILURES = 5;
+export declare const GUIDE_UI_MAX_MESSAGES = 5;
+export type GuideLinkKind = (typeof GUIDE_LINK_KINDS)[number];
+export type GuideUiComponent = (typeof GUIDE_UI_COMPONENTS)[number];
+export type GuideLink = {
+    kind: GuideLinkKind;
+    id: string;
+    path?: string;
+    projectRoot?: string;
+    label?: string;
+};
+export type GuidePipelineStage = {
+    id: string;
+    summary?: string;
+    model?: string;
+    needs: string[];
+    gates: string[];
+    channels: string[];
+    hasVerify: boolean;
+};
+export type GuideUi = {
+    component: "pipeline";
+    title: string;
+    pipeline: {
+        id: string;
+        path: string;
+        model?: string;
+        stages: GuidePipelineStage[];
+        memories: string[];
+        task?: {
+            id: string;
+            goal: string;
+        };
+    };
+    validation: {
+        ok: boolean;
+        errors: number;
+        warnings: number;
+        messages: string[];
+    };
+    link: GuideLink;
+} | {
+    component: "resource";
+    title: string;
+    kind: GuideLinkKind;
+    fields: Array<{
+        label: string;
+        value: string;
+    }>;
+    status?: string;
+    link: GuideLink;
+} | {
+    component: "plan";
+    title: string;
+    steps: Array<{
+        title: string;
+        detail?: string;
+        status: "todo" | "current" | "done";
+    }>;
+} | {
+    component: "choices";
+    question: string;
+    options: Array<{
+        id: string;
+        label: string;
+        description?: string;
+    }>;
+    allowOther: boolean;
+} | {
+    component: "eval_report";
+    title: string;
+    evalId: string;
+    runId: string;
+    status: string;
+    passRate: number | null;
+    passed: boolean | null;
+    cases: number;
+    failures: Array<{
+        caseId: string;
+        reason: string;
+    }>;
+    costUsd: number | null;
+    link: GuideLink;
+} | {
+    component: "links";
+    title?: string;
+    links: GuideLink[];
+};
+export type GuideChoicesUi = Extract<GuideUi, {
+    component: "choices";
+}>;
+export type GuidePlanUi = Extract<GuideUi, {
+    component: "plan";
+}>;
+export type GuideLinksUi = Extract<GuideUi, {
+    component: "links";
+}>;
+export declare class GuideCardError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+/** Structural check for a Guide card payload. Returns the same value when valid. */
+export declare function validateGuideUi(value: unknown): GuideUi | null;
+/** Card payload from a `show_ui` / confirm tool result, or null when the console cannot draw it. */
+export declare function readGuideUi(result: unknown): GuideUi | null;
+export declare function buildChoicesUi(input: {
+    question: string;
+    options: Array<{
+        id: string;
+        label: string;
+        description?: string;
+    }>;
+    allowOther?: boolean;
+}): GuideChoicesUi;
+export declare function buildPlanUi(input: {
+    title: string;
+    steps: Array<{
+        title: string;
+        detail?: string;
+        status: "todo" | "current" | "done";
+    }>;
+}): GuidePlanUi;
+export declare function buildLinksUi(input: {
+    title?: string;
+    links: GuideLink[];
+}): GuideLinksUi;

package/dist/guide/cardContract.js

@@ -0,0 +1,156 @@
+export const GUIDE_LINK_KINDS = [
+    "pipeline",
+    "stage",
+    "task",
+    "agent",
+    "trigger",
+    "eval",
+    "eval_run",
+    "dataset",
+    "connection",
+    "memory",
+    "run",
+];
+export const GUIDE_RESOURCE_KINDS = ["agent", "trigger", "eval", "connection", "memory", "task"];
+export const GUIDE_UI_COMPONENTS = ["pipeline", "resource", "plan", "choices", "eval_report", "links"];
+export const GUIDE_UI_MAX_TEXT = 300;
+export const GUIDE_UI_MAX_PLAN_STEPS = 12;
+export const GUIDE_UI_MAX_CHOICES = 6;
+export const GUIDE_UI_MAX_LINKS = 8;
+export const GUIDE_UI_MAX_FAILURES = 5;
+export const GUIDE_UI_MAX_MESSAGES = 5;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasArrays(value, keys) {
+    return isRecord(value) && keys.every((key) => Array.isArray(value[key]));
+}
+function isLinkKind(value) {
+    return typeof value === "string" && GUIDE_LINK_KINDS.includes(value);
+}
+function clipText(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return "";
+    return trimmed.length > GUIDE_UI_MAX_TEXT ? `${trimmed.slice(0, GUIDE_UI_MAX_TEXT - 1)}…` : trimmed;
+}
+function requireText(value, code = "guide.ui_invalid_args") {
+    const text = clipText(value);
+    if (!text)
+        throw new GuideCardError(code);
+    return text;
+}
+export class GuideCardError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+/** Structural check for a Guide card payload. Returns the same value when valid. */
+export function validateGuideUi(value) {
+    if (!isRecord(value) || typeof value.component !== "string")
+        return null;
+    if (!GUIDE_UI_COMPONENTS.includes(value.component))
+        return null;
+    switch (value.component) {
+        case "pipeline": {
+            if (!hasArrays(value.pipeline, ["stages"]) || !isRecord(value.validation) || !isRecord(value.link))
+                return null;
+            const stages = value.pipeline.stages;
+            if (!stages.every((stage) => isRecord(stage) && typeof stage.id === "string"))
+                return null;
+            break;
+        }
+        case "resource":
+            if (!Array.isArray(value.fields) || !isRecord(value.link))
+                return null;
+            break;
+        case "plan":
+            if (!Array.isArray(value.steps))
+                return null;
+            break;
+        case "choices":
+            if (typeof value.question !== "string" || !Array.isArray(value.options))
+                return null;
+            if (!value.options.every((option) => isRecord(option) && typeof option.id === "string" && typeof option.label === "string")) {
+                return null;
+            }
+            break;
+        case "eval_report":
+            if (!Array.isArray(value.failures) || !isRecord(value.link))
+                return null;
+            break;
+        case "links":
+            if (!Array.isArray(value.links))
+                return null;
+            break;
+        default:
+            return null;
+    }
+    return value;
+}
+/** Card payload from a `show_ui` / confirm tool result, or null when the console cannot draw it. */
+export function readGuideUi(result) {
+    if (!isRecord(result))
+        return null;
+    return validateGuideUi(result.ui);
+}
+export function buildChoicesUi(input) {
+    const question = requireText(input.question);
+    if (input.options.length < 1 || input.options.length > GUIDE_UI_MAX_CHOICES) {
+        throw new GuideCardError("guide.ui_invalid_args");
+    }
+    const options = input.options.map((option) => {
+        const id = requireText(option.id);
+        const label = requireText(option.label);
+        const description = option.description !== undefined ? clipText(option.description) : undefined;
+        return description ? { id, label, description } : { id, label };
+    });
+    return {
+        component: "choices",
+        question,
+        options,
+        allowOther: input.allowOther ?? false,
+    };
+}
+export function buildPlanUi(input) {
+    const title = requireText(input.title);
+    if (input.steps.length < 1 || input.steps.length > GUIDE_UI_MAX_PLAN_STEPS) {
+        throw new GuideCardError("guide.ui_invalid_args");
+    }
+    return {
+        component: "plan",
+        title,
+        steps: input.steps.map((step) => {
+            const detail = step.detail !== undefined ? clipText(step.detail) : undefined;
+            return {
+                title: requireText(step.title),
+                ...(detail ? { detail } : {}),
+                status: step.status,
+            };
+        }),
+    };
+}
+export function buildLinksUi(input) {
+    if (input.links.length < 1 || input.links.length > GUIDE_UI_MAX_LINKS) {
+        throw new GuideCardError("guide.ui_invalid_args");
+    }
+    const title = input.title !== undefined ? requireText(input.title) : undefined;
+    return {
+        component: "links",
+        ...(title ? { title } : {}),
+        links: input.links.map((link) => {
+            if (!isLinkKind(link.kind))
+                throw new GuideCardError("guide.ui_invalid_args");
+            const next = { kind: link.kind, id: requireText(link.id) };
+            if (link.path)
+                next.path = requireText(link.path);
+            if (link.projectRoot)
+                next.projectRoot = requireText(link.projectRoot);
+            if (link.label)
+                next.label = requireText(link.label);
+            return next;
+        }),
+    };
+}

package/dist/guide/chat.d.ts

@@ -0,0 +1,45 @@
+import { type OperatorAgentHost } from "../operatorAgent/index.js";
+import { type GuideMessage } from "./threadStore.js";
+export declare const GUIDE_MAX_MESSAGE_CHARS = 8000;
+export declare class GuideError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, status: number);
+}
+export declare const GUIDE_TOOL_RESULT_MAX_BYTES = 20000;
+export type GuideToolFrame = {
+    type: "tool";
+    id: string;
+    name: string;
+    status: "running" | "complete" | "error";
+    args?: Record<string, unknown>;
+    result?: unknown;
+    error?: string;
+};
+export type GuideFrame = {
+    type: "delta";
+    text: string;
+} | GuideToolFrame | {
+    type: "done";
+    message: GuideMessage;
+} | {
+    type: "error";
+    code: string;
+    message: string;
+};
+export declare function resetGuideSessionsForTests(): void;
+export declare function guideAgentInfo(host: OperatorAgentHost): {
+    name: string;
+    greeting: string;
+};
+export declare function isGuideThreadRunning(threadId: string): boolean;
+export declare function abortGuideTurn(threadId: string): boolean;
+export declare function streamGuideTurn(input: {
+    host: OperatorAgentHost;
+    threadId: string;
+    text: string;
+    attachments?: unknown;
+    model?: string | null;
+    storeRoot?: string;
+    signal?: AbortSignal;
+}): AsyncGenerator<GuideFrame>;