@skaile/workspaces 0.8.5

package/dist/base-assets/connectors/flow/engine/types.d.ts

@@ -0,0 +1,298 @@
+import type { Approval, InputRequest, NodeError, NodeOutput, NodeStatus } from "@skaile/workspaces/types";
+export type { Approval, ArtifactRef, FlowExecution, FlowExecutionStatus, FormField, InputChoice, InputRequest, InputSchema, NodeError, NodeExecution, NodeExecutionSnapshot, NodeOutput, NodeStatus, } from "@skaile/workspaces/types";
+/**
+ * Discriminates the three edge semantics used by the flow engine:
+ * - `'flow'`     — hard dependency: target cannot start until source is complete or skipped.
+ * - `'parallel'` — soft concurrent dependency: target may run alongside source, but source
+ *                  should finish before the flow considers the target "done".
+ * - `'optional'` — advisory dependency: source output enriches target but target can run
+ *                  without it.
+ *
+ * @docLink packages/flow-engine/concepts#edge-type
+ */
+export type EdgeType = "flow" | "parallel" | "optional";
+/**
+ * A single node in a flow definition.
+ *
+ * Nodes with `type === 'group'` are visual containers used by the flow editor — the engine
+ * filters them out before any computation. Only `type === 'skill'` nodes are executed.
+ *
+ * Note: `node.id` is the canvas identifier; `node.data.skill` is the skill that runs.
+ * They may differ when the same skill is aliased to multiple canvas positions.
+ *
+ * @docLink packages/flow-engine/concepts#flow-node
+ */
+export interface FlowNode {
+    /** Canvas-unique node identifier. Used as the key in completed/running/skipped sets. */
+    id: string;
+    /**
+     * Node kind. `'skill'` nodes are executed by the runner; `'group'` nodes are
+     * visual containers only and are ignored by the engine.
+     */
+    type: "skill" | "group";
+    /** ID of the parent group node when this node is nested inside a group container. */
+    parentNode?: string;
+    /** Visual position on the canvas — not used by the engine. */
+    position?: {
+        x: number;
+        y: number;
+    };
+    /** Inline CSS style applied by the canvas renderer — not used by the engine. */
+    style?: Record<string, any>;
+    /** Execution metadata for skill nodes. Absent on pure group nodes. */
+    data?: {
+        /** Skill identifier passed to the runner. Falls back to `node.id` when absent. */
+        skill?: string;
+        /** Optional semver range for skill version pinning (e.g. "^1.0.0"). */
+        version?: string;
+        /** Human-readable label shown in the UI. Falls back to `skill` then `node.id`. */
+        label?: string;
+        /**
+         * When `true` the node can be skipped without blocking the flow.
+         * The `done` condition only requires non-optional nodes to be complete or skipped.
+         */
+        optional?: boolean;
+        /** Static input parameters forwarded to the skill at runtime. */
+        parameters?: Record<string, any>;
+        /** Logical phase label used for grouping in the UI — not used by the engine. */
+        phase?: string;
+        /**
+         * Parallel group tag. Nodes sharing the same tag are dispatched concurrently
+         * by the runner. The engine itself does not process this field — it reports all
+         * `available` node IDs and the runner groups them.
+         */
+        parallel_group?: string;
+        /**
+         * Runner-level overrides applied before executing this node.
+         * Not processed by the engine — consumed by the runner.
+         */
+        overrides?: {
+            /** File paths to skip checking (guaranteed by prior nodes in this flow). */
+            skip_checks?: string[];
+        };
+        [key: string]: any;
+    };
+}
+/**
+ * A directed edge connecting two nodes in a flow definition.
+ *
+ * The `type` field controls how the engine treats the dependency:
+ * - `'flow'`     — hard: target is blocked until source is `complete` or `skipped`.
+ * - `'parallel'` — soft: target may start while source is still running.
+ * - `'optional'` — advisory: target can start regardless of source state.
+ *
+ * @docLink packages/flow-engine/concepts#flow-edge
+ */
+export interface FlowEdge {
+    /** Unique edge identifier. */
+    id: string;
+    /** ID of the source (upstream) node. */
+    source: string;
+    /** ID of the target (downstream) node. */
+    target: string;
+    /** Dependency semantics — see {@link EdgeType}. */
+    type: EdgeType;
+}
+/**
+ * UI and catalog metadata attached to a flow definition. Not used by the engine.
+ *
+ * @docLink packages/flow-engine/concepts#flow-meta
+ */
+export interface FlowMeta {
+    /** Icon identifier for the UI. */
+    icon?: string;
+    /** Category label used for grouping flows in the catalog. */
+    category?: string;
+    /** Free-form tags for filtering and search. */
+    tags?: string[];
+    /** Onboarding hints for the first-run experience. */
+    onboarding?: {
+        /** Whether the initial prompt is free-form text or a structured form. */
+        input_style?: "freeform" | "structured";
+        /** Placeholder text shown in the input field before the user types. */
+        placeholder?: string;
+    };
+}
+/**
+ * Default runtime parameters applied to every skill execution in the flow.
+ *
+ * @docLink packages/flow-engine/concepts#flow-globals
+ */
+export interface FlowGlobals {
+    /** Controls how deeply the research mode skill explores topics. */
+    research_depth?: string;
+    /**
+     * When and how the runner requests human approval:
+     * - `'checkpoint'` — approval at designated checkpoint nodes only.
+     * - `'auto'`       — runner approves automatically (no human in the loop).
+     * - `'manual'`     — every node requires explicit approval.
+     */
+    approval_mode?: "checkpoint" | "auto" | "manual";
+    /** Whether the runner automatically triggers a review skill after each node. */
+    auto_review?: boolean;
+    /** Enables sub-agent dispatch for nodes that support it. */
+    subagent_mode?: boolean;
+    /** Verbosity level forwarded to each skill invocation. */
+    verbosity?: string;
+    /** Enables CLI-friendly output mode (no interactive prompts). */
+    cli_mode?: boolean;
+    [key: string]: any;
+}
+/**
+ * Optional feature modes that can be toggled on a per-flow basis.
+ *
+ * @docLink packages/flow-engine/concepts#flow-modes
+ */
+export interface FlowModes {
+    /** Background research skill that enriches nodes with external context. */
+    research?: {
+        /** Whether the research mode is active for this flow. */
+        enabled: boolean;
+        /** Skill ID to invoke for research enrichment. */
+        skill?: string;
+        /** Node IDs or events that trigger a research pass. */
+        triggers?: string[];
+        /** Parameters forwarded to the research skill. */
+        parameters?: Record<string, any>;
+    };
+    /** Standards injection mode that prepends coding standards to each skill. */
+    standards?: {
+        /** Whether standards injection is active for this flow. */
+        enabled: boolean;
+        /** Skill ID used to discover and inject standards. */
+        skill?: string;
+    };
+}
+/**
+ * A flow that can be suggested to the user after the current flow completes.
+ *
+ * @docLink packages/flow-engine/concepts#next-flow
+ */
+export interface NextFlow {
+    /** Flow identifier matching a `FlowDefinition.id`. */
+    id: string;
+    /** Domain the target flow belongs to. */
+    domain: string;
+    /** Human-readable label shown in the suggestion UI. */
+    label: string;
+    /** Optional hint explaining why this flow is a natural next step. */
+    hint?: string;
+}
+/**
+ * Complete parsed representation of a `*.flow.json` / `*.flow.yaml` file.
+ *
+ * Loaded from disk by `loader.ts` and consumed by the engine functions in `engine.ts`.
+ * Matches the JSON schema at `ai-assets/skaileup-conceptualization/flows/flow.schema.json`.
+ *
+ * @docLink packages/flow-engine/concepts#flow-definition
+ */
+export interface FlowDefinition {
+    /** JSON Schema URL — present in authored files, stripped at runtime if desired. */
+    $schema?: string;
+    /** Unique flow identifier used as the key in catalogs and routing. */
+    id: string;
+    /** Semantic version string (e.g. `"1.0.0"`). */
+    version: string;
+    /** Human-readable flow name shown in the UI and CLI. */
+    name: string;
+    /** Short description of what the flow accomplishes. */
+    description?: string;
+    /** UI and catalog metadata — not used by the engine. */
+    meta?: FlowMeta;
+    /** Default runtime parameters inherited by every node in the flow. */
+    globals?: FlowGlobals;
+    /** Optional feature modes (research enrichment, standards injection). */
+    modes?: FlowModes;
+    /** All nodes in the flow, including visual group containers. */
+    nodes: FlowNode[];
+    /** All directed edges defining the dependency graph. */
+    edges: FlowEdge[];
+    /** ID of the first node to execute. Defaults to whichever node has no incoming flow edges. */
+    entry?: string;
+    /** Flows suggested to the user once this flow reaches the `done` state. */
+    next_flows?: NextFlow[];
+}
+/**
+ * Runtime state for a single node, computed by the engine from the flow definition
+ * and the caller-supplied completed/running/skipped sets (or snapshot map).
+ *
+ * Turn-based execution fields (`approval`, `input`, `output`, `error`, timestamps)
+ * are populated only when the caller passes a `NodeExecutionSnapshot` via
+ * `computeFlowStateFromSnapshots`. They are absent when using the legacy
+ * `computeFlowState(flow, completed, running, skipped)` signature.
+ *
+ * @docLink packages/flow-engine/concepts#node-state
+ */
+export interface NodeState {
+    /** Canvas node ID — matches `FlowNode.id`. */
+    nodeId: string;
+    /** Effective skill identifier (`FlowNode.data.skill ?? FlowNode.id`). */
+    skillId: string;
+    /** Human-readable label for display (`FlowNode.data.label ?? skillId`). */
+    label: string;
+    /**
+     * Current execution status. Possible values:
+     * - `'not_started'`       — has unresolved hard-dependency blockers.
+     * - `'available'`         — all hard dependencies satisfied; ready to dispatch.
+     * - `'running'`           — currently executing.
+     * - `'awaiting_approval'` — paused pending human sign-off.
+     * - `'awaiting_input'`    — paused pending additional user input.
+     * - `'complete'`          — finished successfully.
+     * - `'skipped'`           — explicitly skipped (counts as satisfied for dependents).
+     * - `'failed'`            — unrecoverable error; blocks dependents unless `optional`.
+     */
+    status: NodeStatus;
+    /** Whether this node is optional (`FlowNode.data.optional`). Optional nodes do not block the flow when skipped or failed. */
+    optional: boolean;
+    /** `true` when all incoming `flow`-type edges have complete or skipped sources. */
+    canRun: boolean;
+    /** IDs of upstream nodes whose incomplete state currently blocks this node. Empty when `canRun` is `true`. */
+    blockers: string[];
+    /** Current or most recent approval request on this node. */
+    approval?: Approval;
+    /** Full history of approval requests on this node, oldest first. */
+    approvalHistory?: Approval[];
+    /** Current or pending input request on this node. */
+    input?: InputRequest;
+    /** Full history of input requests on this node, oldest first. */
+    inputHistory?: InputRequest[];
+    /** Structured output produced by the node once the skill executes. */
+    output?: NodeOutput;
+    /** Current error (if the node is `failed`) or the last error before a retry. */
+    error?: NodeError;
+    /** Every failure on this node — retries append here. */
+    errorHistory?: NodeError[];
+    /** ISO timestamp when the node first transitioned to `running`. */
+    startedAt?: string;
+    /** ISO timestamp when the node transitioned to `complete` / `skipped` / `failed`. */
+    completedAt?: string;
+}
+/**
+ * Complete computed state of a flow at a point in time.
+ *
+ * Produced by `computeFlowState` or `computeFlowStateFromSnapshots`. All fields
+ * are derived — the engine never mutates the `FlowDefinition` or any caller-supplied sets.
+ *
+ * @docLink packages/flow-engine/concepts#flow-state
+ */
+export interface FlowState {
+    /** ID of the flow this state was computed from (`FlowDefinition.id`). */
+    flowId: string;
+    /** Per-node state for every skill node in the flow (group nodes excluded). */
+    nodes: NodeState[];
+    /** IDs of nodes whose status is `'available'` — ready to be dispatched by the runner. */
+    available: string[];
+    /** IDs of nodes whose status is `'complete'`. */
+    completed: string[];
+    /**
+     * IDs of nodes currently in flight — status is `'running'`, `'awaiting_approval'`,
+     * or `'awaiting_input'`. Empty when the runner is idle between turns.
+     */
+    focus: string[];
+    /**
+     * `true` when every non-optional node is `complete` or `skipped`.
+     * A single required node stuck in `failed` or `awaiting_*` keeps this `false`.
+     */
+    done: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/base-assets/connectors/flow/engine/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../base-assets/connectors/flow/engine/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,UAAU,EACV,UAAU,EACX,MAAM,0BAA0B,CAAC;AAKlC,YAAY,EACV,QAAQ,EACR,WAAW,EACX,aAAa,EACb,mBAAmB,EACnB,SAAS,EACT,WAAW,EACX,YAAY,EACZ,WAAW,EACX,SAAS,EACT,aAAa,EACb,qBAAqB,EACrB,UAAU,EACV,UAAU,GACX,MAAM,0BAA0B,CAAC;AAMlC;;;;;;;;;GASG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;AAExD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,QAAQ;IACvB,wFAAwF;IACxF,EAAE,EAAE,MAAM,CAAC;IACX;;;OAGG;IACH,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACxB,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,sEAAsE;IACtE,IAAI,CAAC,EAAE;QACL,kFAAkF;QAClF,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,uEAAuE;QACvE,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,kFAAkF;QAClF,KAAK,CAAC,EAAE,MAAM,CAAC;QACf;;;WAGG;QACH,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,iEAAiE;QACjE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACjC,gFAAgF;QAChF,KAAK,CAAC,EAAE,MAAM,CAAC;QACf;;;;WAIG;QACH,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB;;;WAGG;QACH,SAAS,CAAC,EAAE;YACV,4EAA4E;YAC5E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;SACxB,CAAC;QACF,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KACpB,CAAC;CACH;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,QAAQ;IACvB,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,qDAAqD;IACrD,UAAU,CAAC,EAAE;QACX,yEAAyE;QACzE,WAAW,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;QACxC,uEAAuE;QACvE,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAC;IACjD,gFAAgF;IAChF,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4DAA4D;IAC5D,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE;QACT,yDAAyD;QACzD,OAAO,EAAE,OAAO,CAAC;QACjB,kDAAkD;QAClD,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,uDAAuD;QACvD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,kDAAkD;QAClD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAClC,CAAC;IACF,6EAA6E;IAC7E,SAAS,CAAC,EAAE;QACV,2DAA2D;QAC3D,OAAO,EAAE,OAAO,CAAC;QACjB,sDAAsD;QACtD,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,sEAAsE;IACtE,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,yEAAyE;IACzE,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,gEAAgE;IAChE,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,wDAAwD;IACxD,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,8FAA8F;IAC9F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAC;CACzB;AAaD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,SAAS;IACxB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;;OAUG;IACH,MAAM,EAAE,UAAU,CAAC;IACnB,6HAA6H;IAC7H,QAAQ,EAAE,OAAO,CAAC;IAClB,mFAAmF;IACnF,MAAM,EAAE,OAAO,CAAC;IAChB,8GAA8G;IAC9G,QAAQ,EAAE,MAAM,EAAE,CAAC;IAKnB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,oEAAoE;IACpE,eAAe,CAAC,EAAE,QAAQ,EAAE,CAAC;IAC7B,qDAAqD;IACrD,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,iEAAiE;IACjE,YAAY,CAAC,EAAE,YAAY,EAAE,CAAC;IAC9B,sEAAsE;IACtE,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,gFAAgF;IAChF,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,wDAAwD;IACxD,YAAY,CAAC,EAAE,SAAS,EAAE,CAAC;IAC3B,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,yFAAyF;IACzF,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iDAAiD;IACjD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB;;;OAGG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;CACf"}

package/dist/base-assets/connectors/flow/engine.js

@@ -0,0 +1,4 @@
+export { FlowManifestSchema, computeFlowState, computeFlowStateFromSnapshots, computeSkippable, flowKindProvider, isBlocking, loadAllFlows, loadFlow, loadFlowsFromDir, resolveNextNodes, validateFlow } from '../../../chunk-ZUQIXLRJ.js';
+import '../../../chunk-NSBPE2FW.js';
+//# sourceMappingURL=engine.js.map
+//# sourceMappingURL=engine.js.map

package/dist/base-assets/connectors/flow/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"engine.js"}

package/dist/base-assets/connectors/flow/index.d.ts

@@ -0,0 +1,3 @@
+export { createAdapter, FlowAdapter } from "./adapter.js";
+export type { FlowAdapterConnectOptions, FlowAdapterState, FlowAdapterStimulusBus, } from "./adapter.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/base-assets/connectors/flow/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../base-assets/connectors/flow/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC1D,YAAY,EACV,yBAAyB,EACzB,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,cAAc,CAAC"}

package/dist/base-assets/connectors/flow/prompt-fragments.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Prompt fragments for the flow connector.
+ *
+ * Pure functions that translate a {@link TurnStimulus} into the strings the
+ * runner's flow orchestrator splices into the per-turn agent prompt.
+ * Extracted from `runner/src/flow-orchestrator.ts` in Phase 3 of the
+ * flow-connector extraction (2026-05-08) so the connector owns its
+ * prompt-rendering surface without a runtime dep on the orchestrator.
+ *
+ * The contract is byte-identical to the previous inline implementation —
+ * any divergence is a regression.
+ *
+ * @docLink packages/base-assets/flow#prompt-fragments
+ */
+import type { FlowExecution } from "@skaile/workspaces/types";
+import type { FlowDefinition } from "./engine/types.js";
+/**
+ * Reasons why a new turn is starting. The flow orchestrator's prompt template
+ * renders a stimulus-specific paragraph (via {@link renderStimulusPrompt}) so
+ * the agent knows exactly why it has been invoked.
+ *
+ * @docLink packages/base-assets/flow#turn-stimulus
+ */
+export type TurnStimulus = {
+    kind: "flow_started";
+} | {
+    kind: "approval_received";
+    nodeId: string;
+    decision: "approved" | "rejected";
+    feedback?: string;
+    decidedBy: string;
+} | {
+    kind: "input_received";
+    nodeId: string;
+    response: unknown;
+    providedBy: string;
+} | {
+    kind: "retry_requested";
+    nodeId: string;
+    requestedBy: string;
+} | {
+    kind: "user_message";
+    text: string;
+    senderId: string;
+} | {
+    kind: "resumed_after_hibernation";
+} | {
+    kind: "cancelled";
+} | {
+    kind: "state_changed";
+};
+/**
+ * Render the stimulus paragraph the agent sees at turn start.
+ *
+ * The output is a single paragraph (one or more sentences, no surrounding
+ * whitespace) describing why the runner has woken the agent. Spliced into
+ * the orchestrator prompt under the `## Why this turn is happening` heading.
+ *
+ * @docLink packages/base-assets/flow#render-stimulus-prompt
+ */
+export declare function renderStimulusPrompt(stimulus: TurnStimulus): string;
+/**
+ * Build the full agent-orchestrator prompt for a flow turn.
+ *
+ * Reassembles the five-section prompt from the current FlowExecution snapshot
+ * and the supplied stimulus:
+ *
+ *  1. Flow definition (markdown table of nodes)
+ *  2. Current state (progress, available/blocked, interaction pointers)
+ *  3. Why this turn is happening (stimulus-specific paragraph)
+ *  4. Flow tools available (static documentation)
+ *  5. Rules
+ *
+ * Identical to `FlowOrchestrator.buildOrchestratorPrompt` (Phase 3 lift —
+ * any divergence is a regression). Pure — depends only on its inputs.
+ *
+ * @docLink packages/base-assets/flow#build-orchestrator-prompt
+ * @since 2.2.0
+ */
+export declare function buildOrchestratorPrompt(flowDef: FlowDefinition, state: FlowExecution, stimulus: TurnStimulus): string;
+/**
+ * Single-line tag suitable for telemetry / logging. Derives a short, stable
+ * summary of a stimulus that's safe to attach to spans, log entries, and
+ * trace events. The kind is always included; node-specific stimuli also
+ * include their `nodeId` so log queries can pivot on it.
+ *
+ * @docLink packages/base-assets/flow#describe-stimulus
+ */
+export declare function describeStimulus(stimulus: TurnStimulus): string;
+//# sourceMappingURL=prompt-fragments.d.ts.map

package/dist/base-assets/connectors/flow/prompt-fragments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-fragments.d.ts","sourceRoot":"","sources":["../../../../base-assets/connectors/flow/prompt-fragments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,UAAU,GAAG,UAAU,CAAC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACjF;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,2BAA2B,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC;AAE9B;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAyBnE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,YAAY,GACrB,MAAM,CAwFR;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAmB/D"}

package/dist/base-assets/connectors/flow/prompt-fragments.js

@@ -0,0 +1,4 @@
+export { buildOrchestratorPrompt, describeStimulus, renderStimulusPrompt } from '../../../chunk-GZWJGNNN.js';
+import '../../../chunk-NSBPE2FW.js';
+//# sourceMappingURL=prompt-fragments.js.map
+//# sourceMappingURL=prompt-fragments.js.map

package/dist/base-assets/connectors/flow/prompt-fragments.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"prompt-fragments.js"}

package/dist/base-assets/connectors/flow/run-flow.d.ts

@@ -0,0 +1,159 @@
+/**
+ * runFlow / resumeFlow — CLI entry helpers for the flow connector.
+ *
+ * Moved from `runner/src/runner.ts` to `base-assets/connectors/flow/run-flow.ts`
+ * in Phase 3 of the flow-connector extraction (2026-05-08). Behaviour is
+ * byte-identical to the previous runner-side implementation; only the log
+ * source changes from `runner:flow:<runId>` to `flow-connector:run:<runId>`.
+ *
+ * The runner re-exports these symbols with a deprecation warning for one
+ * release. CLI consumers should switch to
+ * `import { runFlow, resumeFlow } from "@skaile/workspaces/base-assets/connectors/flow/run-flow"`.
+ *
+ * Internal runner helpers (FlowOrchestrator, bootstrapRunnerLogStore,
+ * createAgentSession, resolveDriverPaths, session helpers) are loaded lazily
+ * via dynamic `await import("@skaile/workspaces/runner")` inside
+ * `loadRunnerModule()` below. The lazy load avoids a static package-level
+ * cycle (runner → connectors → base-assets → runner) — the cycle exists at
+ * the workspace level but never resolves at module-load time because
+ * base-assets only ever calls `import` from inside an async function body.
+ * The string-literal specifier preserves `bun --compile` and tsup static
+ * analysis.
+ */
+import type { AgentEvent } from "@skaile/workspaces/bridge";
+/** Type-only re-export of SessionState so the runner tombstone shim still works. */
+export type SessionState = import("@skaile/workspaces/runner").SessionState;
+/**
+ * Options for {@link runFlow}.
+ *
+ * Wraps `FlowOrchestrator` with autonomous mode turned on by default so
+ * interactive approval/input gates don't block a terminal run.
+ *
+ * @docLink packages/base-assets/flow#run-flow
+ */
+export interface RunOptions {
+    /** The working directory for the project being orchestrated. */
+    projectDir: string;
+    /** Absolute path to the `.flow.yaml` or `.flow.json` definition file. */
+    flowPath: string;
+    /**
+     * Directory containing `agent.yaml`, `SOUL.md`, `RULES.md`, `knowledge/`.
+     * Resolved from `skaile.yaml` via `resolveAgentDir` when absent.
+     */
+    agentDir?: string;
+    /**
+     * Agent driver backend. Defaults to `settings.driver` (`"omp"` or `"claude-sdk"`).
+     */
+    driver?: string;
+    /**
+     * LLM provider override (e.g. `"anthropic"`, `"openrouter"`).
+     * Falls back to `settings.provider` when absent.
+     */
+    provider?: string;
+    /**
+     * Model name override. Falls back to `settings.model` when absent.
+     */
+    model?: string;
+    /**
+     * Path to a specific `settings.json` to load instead of the default
+     * layered resolution chain (project → parent → global → built-in defaults).
+     */
+    settingsFile?: string;
+    /**
+     * When `true`, prints the initial flow state without starting the agent
+     * and returns immediately.
+     */
+    dryRun?: boolean;
+    /**
+     * Per-session timeout in milliseconds. Defaults to
+     * {@link DEFAULT_SESSION_TIMEOUT_MS} (4 hours).
+     */
+    sessionTimeoutMs?: number;
+    /** Optional human-readable label shown in the session list. */
+    sessionLabel?: string;
+    /** Autonomous mode for CLI runs — defaults to true so interactive approval gates are skipped. */
+    autonomousMode?: boolean;
+    /**
+     * Called for each {@link AgentEvent} emitted during the run
+     * (e.g. `text`, `tool_call`, `state_changed`).
+     */
+    onEvent?: (event: AgentEvent) => void;
+    /**
+     * Called for each diagnostic log line. Defaults to `process.stdout`.
+     */
+    onLog?: (line: string) => void;
+}
+/**
+ * Options for resuming an existing CLI session.
+ *
+ * Reconnects the driver's conversation thread (conversation history is
+ * preserved via the stored `driverSessionId`) but restarts flow execution
+ * from scratch — flow state is not persisted in CLI mode. For governed,
+ * resumable flow runs use a host that persists flow state (e.g. the Skaile
+ * platform).
+ *
+ * @docLink packages/base-assets/flow#resume-flow
+ */
+export interface ResumeOptions {
+    /** The working directory for the project being orchestrated. */
+    projectDir: string;
+    /**
+     * Specific run ID to resume. When absent, the current session pointer
+     * at `<projectDir>/.skaile/current` is used.
+     */
+    sessionId?: string;
+    /**
+     * Agent definition directory override. Defaults to the directory stored
+     * in the session file.
+     */
+    agentDir?: string;
+    /**
+     * When `true`, prints the initial flow state without starting the agent
+     * and returns immediately.
+     */
+    dryRun?: boolean;
+    /**
+     * Per-session timeout in milliseconds. Defaults to
+     * {@link DEFAULT_SESSION_TIMEOUT_MS} (4 hours).
+     */
+    sessionTimeoutMs?: number;
+    /**
+     * Called for each {@link AgentEvent} emitted during the run.
+     */
+    onEvent?: RunOptions["onEvent"];
+    /**
+     * Called for each diagnostic log line. Defaults to `process.stdout`.
+     */
+    onLog?: RunOptions["onLog"];
+}
+/**
+ * Start a new flow session from the CLI.
+ *
+ * Wraps `FlowOrchestrator` with autonomous mode turned on by default so
+ * interactive approval/input gates don't block a terminal run. The
+ * runner remains idle between turns — for the CLI use case, a single
+ * turn should carry the flow to completion in autonomous mode. Non-CLI
+ * hosts (Skaile platform, Pichi) use the orchestrator directly via the
+ * serve command surface and drive gates through user actions.
+ *
+ * @docLink packages/base-assets/flow#run-flow
+ */
+export declare function runFlow(opts: RunOptions): Promise<void>;
+/**
+ * Resume an existing session from the CLI.
+ *
+ * With the Phase 2 turn-based model, flow state is NOT persisted to
+ * local session files — only the driver session ID is kept. The CLI
+ * can resume the agent's conversation thread, but the flow execution
+ * itself starts from scratch because the runner has no durable store
+ * for per-run state.
+ *
+ * For a governed, resumable flow run, use a host that persists flow
+ * state (e.g. the Skaile platform). CLI resume is retained as a
+ * driver-level convenience only: we load the session, restart the
+ * flow, and the SDK will reconnect to the prior conversation thread.
+ *
+ * @docLink packages/base-assets/flow#resume-flow
+ */
+export declare function resumeFlow(opts: ResumeOptions): Promise<void>;
+//# sourceMappingURL=run-flow.d.ts.map

package/dist/base-assets/connectors/flow/run-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-flow.d.ts","sourceRoot":"","sources":["../../../../base-assets/connectors/flow/run-flow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAsC5D,oFAAoF;AACpF,MAAM,MAAM,YAAY,GAAG,OAAO,2BAA2B,EAAE,YAAY,CAAC;AAK5E;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iGAAiG;IACjG,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC;;OAEG;IACH,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;OAEG;IACH,OAAO,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;IAChC;;OAEG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;CAC7B;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAkQ7D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAuDnE"}

package/dist/base-assets/connectors/flow/run-flow.js

@@ -0,0 +1,23 @@
+export { resumeFlow, runFlow } from '../../../chunk-7HCGI2GW.js';
+import '../../../chunk-Y46TBPLI.js';
+import '../../../chunk-IPUYL6TD.js';
+import '../../../chunk-3W7Z74ZP.js';
+import '../../../chunk-Q5URN24L.js';
+import '../../../chunk-7H7EOIRH.js';
+import '../../../chunk-GCRKAFH7.js';
+import '../../../chunk-ZUQIXLRJ.js';
+import '../../../chunk-GZWJGNNN.js';
+import '../../../chunk-FVTV7M76.js';
+import '../../../chunk-65CYXYUW.js';
+import '../../../chunk-JKNWJ64A.js';
+import '../../../chunk-O4JH3KUE.js';
+import '../../../chunk-K5GBV4SA.js';
+import '../../../chunk-KLNL7QHN.js';
+import '../../../chunk-XEGHWFAX.js';
+import '../../../chunk-CSUBFKAN.js';
+import '../../../chunk-BVHFSUFM.js';
+import '../../../chunk-JLPC4YWT.js';
+import '../../../chunk-V37HONL7.js';
+import '../../../chunk-NSBPE2FW.js';
+//# sourceMappingURL=run-flow.js.map
+//# sourceMappingURL=run-flow.js.map

package/dist/base-assets/connectors/flow/run-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"run-flow.js"}

package/dist/base-assets/connectors/flow/stimulus-driver.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure state-change → stimulus translator for the flow connector.
+ *
+ * Given the previous and current {@link FlowExecution} snapshots, decides
+ * whether the runner should be woken with a fresh turn and (if so) what
+ * kind of stimulus to render. Returns `null` when no turn is warranted
+ * (e.g. the snapshots are deep-equal).
+ *
+ * Today's FlowOrchestrator subscribes to `adapter.onStateChange(...)` and
+ * forwards the snapshot to the host without kicking a turn — the host
+ * issues explicit turn-kicking commands (`approve_flow_node`, etc.). Phase
+ * 3 of the flow-connector extraction adds this function as the connector-
+ * side decision point so a future direct path (FlowAdapter →
+ * SessionStimulusBus → runner) can reproduce today's coalesced "state
+ * changed → maybe a turn" semantics without going through the orchestrator.
+ *
+ * Default behaviour mirrors today exactly: any structural change in the
+ * FlowExecution snapshot produces a single `{ kind: "state_changed" }`
+ * stimulus. Phase 4 may refine this with kind discriminators (approval-
+ * received, input-received, etc.) once the orchestrator's onStateChange
+ * subscription is removed; until then we keep gating purely on equality.
+ *
+ * @docLink packages/base-assets/flow#stimulus-driver
+ */
+import type { FlowExecution } from "@skaile/workspaces/types";
+import type { TurnStimulus } from "./prompt-fragments.js";
+/**
+ * Decide whether a state transition warrants kicking an agent turn, and
+ * which kind of stimulus to render. Returns `null` to suppress turn-kicking
+ * when nothing observable changed.
+ *
+ * Pure — depends only on its inputs.
+ *
+ * @param oldExec - Previous FlowExecution snapshot (or `undefined` on the
+ *   first emission, e.g. immediately after `connect()`).
+ * @param newExec - Current FlowExecution snapshot.
+ * @returns A {@link TurnStimulus} when a turn should be kicked, or `null`.
+ *
+ * @docLink packages/base-assets/flow#compute-stimulus
+ */
+export declare function computeStimulus(oldExec: FlowExecution | undefined, newExec: FlowExecution): TurnStimulus | null;
+//# sourceMappingURL=stimulus-driver.d.ts.map