@qontinui/shared-types 0.2.1

package/src/ui-bridge-ir/state.ts

@@ -0,0 +1,90 @@
+/**
+ * IR-level state declaration.
+ *
+ * Authoring-time superset of ui-bridge-auto's runtime State shape. The
+ * IR -> WorkflowConfig adapter strips IR-only fields (provenance, metadata,
+ * elementIds, incomingTransitions, visualRefs) before handing to the runtime.
+ */
+
+import type { IRElementCriteria } from "./element-criteria";
+import type { IRCrossRef, IRMetadata, IRProvenance, IRVisualRef } from "./primitives";
+
+/**
+ * Property-level condition on a matched element. Mirrors
+ * `StateCondition` in ui-bridge-auto/src/types/state.ts:83.
+ */
+export interface IRStateCondition {
+  element: IRElementCriteria;
+  property:
+    | "visible"
+    | "enabled"
+    | "checked"
+    | "expanded"
+    | "selected"
+    | "text"
+    | "value";
+  expected: unknown;
+  comparator?: "equals" | "contains" | "matches" | "greaterThan" | "lessThan";
+}
+
+/**
+ * IR state declaration.
+ *
+ * Anchored to ui-bridge-auto's `State` shape (ui-bridge-auto/src/types/state.ts:23)
+ * — extends it with IR-only fields. Runtime tracking fields (enteredAt,
+ * exitedAt, observationCount) are deliberately absent: those are managed by
+ * the state machine at execution time.
+ */
+export interface IRState {
+  // Identity --------------------------------------------------------------
+  id: string;
+  name: string;
+  description?: string;
+
+  // Predicates (canonical) -----------------------------------------------
+  /** Element criteria that must ALL be satisfied for this state to be active. */
+  requiredElements: IRElementCriteria[];
+  /** Element criteria where NONE may be satisfied (any match disqualifies). */
+  excludedElements?: IRElementCriteria[];
+  /** Additional property checks on matched elements. */
+  conditions?: IRStateCondition[];
+
+  // Lifecycle / pathfinding hints ----------------------------------------
+  /** Whether this is a valid initial/starting state. */
+  isInitial?: boolean;
+  /** Whether this is a terminal state (no outgoing transitions). */
+  isTerminal?: boolean;
+  /** Whether this state is modal/blocking (e.g., a dialog). */
+  blocking?: boolean;
+  /** Logical group this state belongs to. */
+  group?: string;
+  /** Navigation cost weight for pathfinding (default 1.0). */
+  pathCost?: number;
+  /**
+   * Free-text precondition required for this state to be entered, mirroring
+   * legacy `assertion.precondition` strings (e.g., "A workflow is paused at a
+   * breakpoint"). Authoring-time documentation; not enforced at runtime.
+   */
+  precondition?: string;
+
+  // IR-only fields (stripped by adapter) ---------------------------------
+  /**
+   * Optional companion list of element IDs that resolved at registration
+   * time. The runtime SDK fills this in when criteria resolve to specific
+   * registered elements. Authors do not set this directly.
+   */
+  elementIds?: string[];
+  /**
+   * Derived/computed at IR-emission time — list of transitions that activate
+   * this state. Authoring-time hint for visualization; not authored directly.
+   */
+  incomingTransitions?: string[];
+  /** Semantic metadata routed through useUIAnnotation store at runtime. */
+  metadata?: IRMetadata;
+  /** Where this declaration came from. */
+  provenance?: IRProvenance;
+  /** Cross-document references. */
+  crossRefs?: IRCrossRef[];
+  /** Optional visual reference (section 8). */
+  visualRefs?: IRVisualRef[];
+}

package/src/ui-bridge-ir/transition.ts

@@ -0,0 +1,92 @@
+/**
+ * IR-level transition declaration.
+ *
+ * Anchored to ui-bridge-auto's `Transition` shape
+ * (ui-bridge-auto/src/types/transition.ts:103) and extended with IR-only
+ * fields (effect, provenance, crossRefs).
+ *
+ * `exitStates` is a HINT at the IR level — when omitted, the adapter populates
+ * `[]` so the runtime contract (which requires the field) is satisfied.
+ */
+
+import type { IRElementCriteria } from "./element-criteria";
+import type { IRCrossRef, IREffect, IRMetadata, IRProvenance } from "./primitives";
+
+/**
+ * Wait specification for the runtime to settle after an action.
+ * Mirrors `WaitSpec` in ui-bridge-auto/src/types/transition.ts:56.
+ */
+export interface IRWaitSpec {
+  type: "idle" | "element" | "state" | "time" | "condition" | "vanish" | "change" | "stable";
+  query?: IRElementCriteria;
+  stateId?: string;
+  ms?: number;
+  timeout?: number;
+  property?: string;
+  quietPeriodMs?: number;
+}
+
+/**
+ * A single action step within a transition. Mirrors `TransitionAction` in
+ * ui-bridge-auto/src/types/transition.ts:81 with the difference that `type`
+ * is a free-form string here — the IR doesn't bind authors to a specific
+ * action vocabulary; that constraint applies at the runtime adapter layer.
+ */
+export interface IRTransitionAction {
+  /** The action to perform (e.g., "click", "type", "submit"). */
+  type: string;
+  /** Criteria to find the target element. */
+  target: IRElementCriteria;
+  /** Action-specific parameters. */
+  params?: Record<string, unknown>;
+  /** Optional wait specification applied after this action completes. */
+  waitAfter?: IRWaitSpec;
+}
+
+/**
+ * IR transition declaration.
+ *
+ * Authoring-time superset of ui-bridge-auto's `Transition`. Reliability
+ * tracking fields (successCount, failureCount, averageDurationMs,
+ * lastExecutedAt) are deliberately absent — the runtime owns them.
+ */
+export interface IRTransition {
+  // Identity --------------------------------------------------------------
+  id: string;
+  name: string;
+  description?: string;
+
+  // Pre/post conditions ---------------------------------------------------
+  /** Precondition: all of these states must be active. */
+  fromStates: string[];
+  /** States to enter after the transition completes. */
+  activateStates: string[];
+  /**
+   * States to leave after the transition completes.
+   *
+   * IR-level HINT: omit it and the adapter defaults to `[]`. The runtime
+   * type (`Transition.exitStates: string[]` in
+   * ui-bridge-auto/src/types/transition.ts:116) requires the field; the
+   * adapter normalizes.
+   */
+  exitStates?: string[];
+
+  // Action sequence -------------------------------------------------------
+  actions: IRTransitionAction[];
+
+  // Pathfinding hints -----------------------------------------------------
+  /** Navigation cost for pathfinding (default 1.0). */
+  pathCost?: number;
+  /** Whether this transition can be reversed. */
+  bidirectional?: boolean;
+
+  // IR-only fields (stripped by adapter) ----------------------------------
+  /** Side-effect annotation. Drives counterfactual + auto-regression gating. */
+  effect?: IREffect;
+  /** Semantic metadata routed through useUIAnnotation store at runtime. */
+  metadata?: IRMetadata;
+  /** Where this declaration came from. */
+  provenance?: IRProvenance;
+  /** Cross-document references. */
+  crossRefs?: IRCrossRef[];
+}

package/src/workflow/_api.ts

@@ -0,0 +1,474 @@
+/**
+ * Workflow Types
+ *
+ * Canonical type definitions for the unified Workflow Builder system.
+ * Shared across qontinui-runner and qontinui-web.
+ *
+ * All automation is organized into four phases: Setup, Verification, Agentic, Completion.
+ *
+ * Execution Order:
+ *   Setup (once) -> [Verification <-> Agentic]* -> Completion (once)
+ *
+ * Step Types (4 core types):
+ *   command   - Shell commands, checks, check groups, tests
+ *   ui_bridge - UI Bridge SDK interactions (navigate, execute, assert, snapshot)
+ *   prompt    - AI task instructions
+ *   workflow  - Run a saved workflow inline (composition)
+ */
+
+// =============================================================================
+// Generated frame types — source of truth is qontinui-schemas/rust/src/workflow.rs
+// These are produced by the schemars -> JSON Schema -> json-schema-to-typescript
+// pipeline. Do NOT redeclare them here; re-export from ../generated/*.
+//
+// Step arrays on UnifiedWorkflow / WorkflowStage are typed as `unknown[]` by
+// the generator. Typed step arrays are part of the Wave 4 step migration and
+// remain hand-authored below (BaseStep, CommandStep, PromptStep, UiBridgeStep,
+// WorkflowStep, and the per-phase aliases).
+// =============================================================================
+
+export type { LogSourceSelection } from "../generated/LogSourceSelection";
+export type { HealthCheckUrl } from "../generated/HealthCheckUrl";
+export type { RoutingRule } from "../generated/RoutingRule";
+export type { ModelOverrideConfig } from "../generated/ModelOverrideConfig";
+export type { StageCondition } from "../generated/StageCondition";
+export type { RetryPolicy } from "../generated/RetryPolicy";
+export type { StageOutput } from "../generated/StageOutput";
+export type { StageInput } from "../generated/StageInput";
+export type { WorkflowStage } from "../generated/WorkflowStage";
+export type { UnifiedWorkflow } from "../generated/UnifiedWorkflow";
+export type { WorkflowArchitecture } from "../generated/WorkflowArchitecture";
+
+export type { BaseStepFields } from "../generated/BaseStepFields";
+export type { RetrySpec } from "../generated/RetrySpec";
+
+// Step DTOs (generated from qontinui-types::workflow_step)
+export type { CommandStep } from "../generated/CommandStep";
+export type { PromptStep } from "../generated/PromptStep";
+export type { UiBridgeStep } from "../generated/UiBridgeStep";
+export type { WorkflowStep } from "../generated/WorkflowStep";
+export type { UnifiedStep } from "../generated/UnifiedStep";
+export type { CanonicalStep } from "../generated/CanonicalStep";
+export type { HttpMethod } from "../generated/HttpMethod";
+export type { ApiContentType } from "../generated/ApiContentType";
+export type { ApiAssertion } from "../generated/ApiAssertion";
+export type { ApiVariableExtraction } from "../generated/ApiVariableExtraction";
+export type { TestType } from "../generated/TestType";
+export type { PlaywrightExecutionMode } from "../generated/PlaywrightExecutionMode";
+export type { CheckType } from "../generated/CheckType";
+export type { CommandMode } from "../generated/CommandMode";
+export type { UiBridgeAction } from "../generated/UiBridgeAction";
+export type { VerificationCategoryKind } from "../generated/VerificationCategoryKind";
+
+// ModelOverrides is a hand-authored convenience alias: the generated
+// UnifiedWorkflow / WorkflowStage type `model_overrides` as an open
+// `{ [k: string]: ModelOverrideConfig }`, but downstream code prefers a
+// named type with known phase keys. Keep as a local alias over the generated
+// per-phase config.
+import type { ModelOverrideConfig as _ModelOverrideConfig } from "../generated/ModelOverrideConfig";
+
+export type ModelOverrides = {
+  setup?: _ModelOverrideConfig;
+  agentic?: _ModelOverrideConfig;
+  completion?: _ModelOverrideConfig;
+  verification?: _ModelOverrideConfig;
+  investigation?: _ModelOverrideConfig;
+  summary?: _ModelOverrideConfig;
+  generation?: _ModelOverrideConfig;
+};
+
+// =============================================================================
+// Phases
+// =============================================================================
+
+export type WorkflowPhase = "setup" | "verification" | "agentic" | "completion";
+
+// =============================================================================
+// Skill Types (re-exported from ./skill)
+// =============================================================================
+
+export type {
+  SkillCategory,
+  SkillAuthor,
+  SkillParameterOption,
+  SkillParameter,
+  SingleStepTemplate,
+  MultiStepTemplate,
+  CompositionTemplate,
+  SkillRef,
+  SkillTemplate,
+  SkillDefinition,
+  SkillOrigin,
+  SkillExportManifest,
+  SkillExport,
+  SkillImportResult,
+} from "./skill";
+
+export type {
+  PlannedActionType,
+  ElementTarget,
+  PlannedAction,
+  ActionPlan,
+  PlannedActionResult,
+  ActionPlanResult,
+  ActionPlanExecuteRequest,
+} from "./action-plan";
+
+// =============================================================================
+// Step Types — generated from qontinui-types::workflow_step
+//
+// The four canonical step variants (CommandStep, PromptStep, UiBridgeStep,
+// WorkflowStep) and their helper unions (HttpMethod, ApiContentType, …) are
+// re-exported at the top of this file from ../generated/*. The remaining
+// hand-authored types in this section are TS-only sugar: a `BaseStep` alias
+// for consumers that still want a name for the shared-fields subset, a
+// `StepTypeName` literal that includes non-canonical runner-side variants
+// (e.g. native_accessibility) for UI listings, and the phase-alias types.
+//
+// Phase narrowing is TS-only sugar — not a wire concern. The generator emits
+// a narrow `phase` field on each variant; these aliases just group the four
+// variants by the phase that can carry them.
+// =============================================================================
+
+import type { CommandStep as _CommandStep } from "../generated/CommandStep";
+import type { PromptStep as _PromptStep } from "../generated/PromptStep";
+import type { UiBridgeStep as _UiBridgeStep } from "../generated/UiBridgeStep";
+import type { WorkflowStep as _WorkflowStep } from "../generated/WorkflowStep";
+
+/**
+ * Shared-fields subset carried by every canonical step variant.
+ *
+ * Alias for the generated `BaseStepFields` so downstream code can still
+ * reference `BaseStep` by name.  Source of truth:
+ * `qontinui-types::workflow_step::BaseStepFields`.
+ */
+import type { BaseStepFields as _BaseStepFields } from "../generated/BaseStepFields";
+export type BaseStep = _BaseStepFields;
+
+// =============================================================================
+// Step Type Names
+// =============================================================================
+
+// Includes runner-side non-canonical variants (e.g. `native_accessibility`)
+// that appear in the UI listing but are not part of the `UnifiedStep` DTO.
+export type StepTypeName = "command" | "ui_bridge" | "prompt" | "workflow" | "native_accessibility";
+
+// =============================================================================
+// Phase-alias types (TS-only sugar over the generated UnifiedStep)
+// =============================================================================
+
+export type SetupStep = _CommandStep | _PromptStep | _UiBridgeStep | _WorkflowStep;
+export type VerificationStep = _CommandStep | _PromptStep | _UiBridgeStep | _WorkflowStep;
+export type AgenticStep = _PromptStep;
+export type CompletionStep = _CommandStep | _PromptStep | _UiBridgeStep | _WorkflowStep;
+
+// =============================================================================
+// Verification Categories
+// =============================================================================
+
+// Alias for the generated `VerificationCategoryKind` union.  Source of truth:
+// `qontinui-types::workflow_step::VerificationCategoryKind`.  `VerificationCategoryKind`
+// itself is re-exported earlier in this file.
+import type { VerificationCategoryKind as _VerificationCategoryKind } from "../generated/VerificationCategoryKind";
+export type VerificationCategory = _VerificationCategoryKind;
+
+// =============================================================================
+// Dependency Graph
+// =============================================================================
+
+export interface DependencyNode {
+  id: string;
+  label: string;
+  type: string;
+  phase: WorkflowPhase;
+  is_referenced: boolean;
+  cost_category?: string;
+}
+
+export interface DependencyEdge {
+  source: string;
+  target: string;
+  label?: string;
+  edge_type: "explicit_depends_on" | "implicit_reference" | "setup_provides";
+}
+
+export interface DependencyGraph {
+  nodes: DependencyNode[];
+  edges: DependencyEdge[];
+}
+
+// =============================================================================
+// Cost Annotations
+// =============================================================================
+
+export type CostCategory =
+  | "network"
+  | "ai_call"
+  | "setup"
+  | "ui_interaction";
+
+export interface StepCost {
+  step_id: string;
+  name: string;
+  estimated_ms: number;
+  category: CostCategory;
+  has_side_effects: boolean;
+}
+
+export interface CostAnnotations {
+  steps: StepCost[];
+  total_estimated_ms: number;
+}
+
+// =============================================================================
+// Quality Report
+// =============================================================================
+
+export type QualityFindingSeverity = "critical" | "warning" | "info";
+
+export type QualityFindingCategory =
+  | "verification_gap"
+  | "missing_criterion"
+  | "unnecessary_step"
+  | "weak_retry"
+  | "required_flag_violation"
+  | "retry_inconsistency"
+  | "data_contract_violation"
+  | "false_positive_risk";
+
+export interface QualityFinding {
+  finding_id: string;
+  step_id?: string;
+  severity: QualityFindingSeverity;
+  category: QualityFindingCategory;
+  description: string;
+  suggested_fix?: string;
+}
+
+export interface CoverageMatrix {
+  criteria_to_steps: Record<string, string[]>;
+  steps_to_criteria: Record<string, string[]>;
+  uncovered_criteria: string[];
+  unlinked_steps: string[];
+}
+
+export interface QualityReport {
+  findings: QualityFinding[];
+  score: number;
+  pass: boolean;
+  coverage_matrix?: CoverageMatrix;
+}
+
+// =============================================================================
+// Export/Import Types
+// =============================================================================
+
+import type { UnifiedWorkflow as _UnifiedWorkflow } from "../generated/UnifiedWorkflow";
+
+export interface WorkflowExportManifest {
+  version: string;
+  exported_at: string;
+  app_version: string;
+  content_type: "unified_workflow";
+}
+
+export interface WorkflowExport {
+  manifest: WorkflowExportManifest;
+  workflow: _UnifiedWorkflow;
+}
+
+export interface WorkflowImportResult {
+  workflow: _UnifiedWorkflow;
+  overwritten: boolean;
+  original_id: string | null;
+}
+
+// =============================================================================
+// Feature Detection
+// =============================================================================
+
+export interface WorkflowFeatures {
+  hasSetup: boolean;
+  hasVerification: boolean;
+  hasAgentic: boolean;
+  hasCompletion: boolean;
+  hasUiBridge: boolean;
+  showIterationSettings: boolean;
+  hasAiPrompts: boolean;
+}
+
+// =============================================================================
+// Step Type Display Info
+// =============================================================================
+
+export interface StepTypeInfo {
+  type: string;
+  label: string;
+  description: string;
+  icon: string;
+  color: string;
+  phase: WorkflowPhase;
+}
+
+// =============================================================================
+// Step Type Constants
+// =============================================================================
+
+export const STEP_TYPES: Record<WorkflowPhase, StepTypeInfo[]> = {
+  setup: [
+    {
+      type: "command",
+      label: "Command",
+      description: "Run shell commands, checks, or tests",
+      icon: "Terminal",
+      color: "gray",
+      phase: "setup",
+    },
+    {
+      type: "ui_bridge",
+      label: "UI Bridge",
+      description: "Interact with UI via UI Bridge SDK",
+      icon: "Monitor",
+      color: "emerald",
+      phase: "setup",
+    },
+    {
+      type: "prompt",
+      label: "AI Task",
+      description: "AI-driven task",
+      icon: "Bot",
+      color: "violet",
+      phase: "setup",
+    },
+    {
+      type: "workflow",
+      label: "Workflow",
+      description: "Run a saved workflow",
+      icon: "Workflow",
+      color: "blue",
+      phase: "setup",
+    },
+  ],
+  verification: [
+    {
+      type: "command",
+      label: "Command",
+      description: "Run commands, checks, or tests for verification",
+      icon: "Terminal",
+      color: "gray",
+      phase: "verification",
+    },
+    {
+      type: "ui_bridge",
+      label: "UI Bridge",
+      description: "Verify UI state via UI Bridge",
+      icon: "Monitor",
+      color: "emerald",
+      phase: "verification",
+    },
+    {
+      type: "prompt",
+      label: "AI Verification",
+      description: "AI-evaluated criteria",
+      icon: "Bot",
+      color: "violet",
+      phase: "verification",
+    },
+    {
+      type: "workflow",
+      label: "Workflow",
+      description: "Run a saved workflow for verification",
+      icon: "Workflow",
+      color: "blue",
+      phase: "verification",
+    },
+    {
+      type: "native_accessibility",
+      label: "Native Accessibility",
+      description: "Run a native accessibility audit using OS-level APIs",
+      icon: "Accessibility",
+      color: "teal",
+      phase: "verification",
+    },
+  ],
+  agentic: [
+    {
+      type: "prompt",
+      label: "Prompt",
+      description: "AI task instructions",
+      icon: "MessageSquare",
+      color: "amber",
+      phase: "agentic",
+    },
+  ],
+  completion: [
+    {
+      type: "command",
+      label: "Command",
+      description: "Run cleanup commands or final tests",
+      icon: "Terminal",
+      color: "gray",
+      phase: "completion",
+    },
+    {
+      type: "ui_bridge",
+      label: "UI Bridge",
+      description: "Final UI interactions",
+      icon: "Monitor",
+      color: "emerald",
+      phase: "completion",
+    },
+    {
+      type: "prompt",
+      label: "AI Completion",
+      description: "Final AI actions",
+      icon: "Bot",
+      color: "violet",
+      phase: "completion",
+    },
+    {
+      type: "workflow",
+      label: "Workflow",
+      description: "Run a saved workflow as a completion step",
+      icon: "Workflow",
+      color: "blue",
+      phase: "completion",
+    },
+  ],
+};
+
+// =============================================================================
+// Phase Display Info
+// =============================================================================
+
+export const PHASE_INFO: Record<
+  WorkflowPhase,
+  { label: string; description: string; color: string }
+> = {
+  setup: {
+    label: "Setup",
+    description: "Runs once at the beginning",
+    color: "blue",
+  },
+  verification: {
+    label: "Verification",
+    description: "Checks success criteria, loops with agentic",
+    color: "green",
+  },
+  agentic: {
+    label: "Agentic",
+    description: "AI work, iterates until verification passes",
+    color: "amber",
+  },
+  completion: {
+    label: "Completion",
+    description: "Runs once after the loop exits",
+    color: "purple",
+  },
+};
+
+// =============================================================================
+// Summary Step Constants
+// =============================================================================
+
+export const DEFAULT_SUMMARY_PROMPT = `Write a one-paragraph summary of all the tasks completed in this workflow. Include what was accomplished, whether the stated goal was achieved, any issues encountered and how they were resolved, and remaining work if the goal was not fully achieved. Be concise but comprehensive.`;