@qontinui/shared-types 0.2.1

package/src/workflow/action-plan.ts

@@ -0,0 +1,208 @@
+/**
+ * Structured Action Plan Types
+ *
+ * Defines the schema for LLM-generated UI Bridge action plans.
+ * Instead of natural language instructions interpreted by a second LLM call,
+ * action plans let the agentic-phase LLM directly specify typed UI actions
+ * that map to UI Bridge's control API.
+ *
+ * Inspired by Skyvern's structured action protocol: each action carries
+ * reasoning, confidence, and typed parameters so that execution is
+ * deterministic and auditable.
+ */
+
+// =============================================================================
+// Action Types (mirrors UI Bridge StandardAction + extensions)
+// =============================================================================
+
+/**
+ * Action types that can appear in an action plan.
+ * Maps directly to UI Bridge's StandardAction type with additions
+ * for navigation and waiting.
+ */
+export type PlannedActionType =
+  | "click"
+  | "doubleClick"
+  | "rightClick"
+  | "type"
+  | "clear"
+  | "select"
+  | "check"
+  | "uncheck"
+  | "toggle"
+  | "hover"
+  | "focus"
+  | "scroll"
+  | "scrollIntoView"
+  | "setValue"
+  | "drag"
+  | "submit"
+  | "sendKeys"
+  | "autocomplete"
+  | "navigate"
+  | "wait";
+
+// =============================================================================
+// Element Resolution
+// =============================================================================
+
+/**
+ * How to find the target element for an action.
+ * Supports multiple resolution strategies with fallback.
+ */
+export interface ElementTarget {
+  /** Direct element ID from a prior snapshot (fastest resolution) */
+  elementId?: string;
+  /** data-testid attribute value */
+  testId?: string;
+  /** Natural language description for fuzzy search (fallback) */
+  searchText?: string;
+  /** Element type hint to narrow search (e.g., "button", "input") */
+  elementType?: string;
+  /** CSS selector */
+  selector?: string;
+}
+
+// =============================================================================
+// Action Plan Entry
+// =============================================================================
+
+/**
+ * A single action in an action plan.
+ *
+ * The LLM produces an array of these, each mapping to one UI Bridge
+ * control action. The reasoning and confidence fields enable auditing
+ * and confidence-gated execution.
+ */
+export interface PlannedAction {
+  /** Action type to execute */
+  action: PlannedActionType;
+
+  /** How to find the target element */
+  target: ElementTarget;
+
+  /** LLM's reasoning for this action (audit trail) */
+  reasoning?: string;
+
+  /** LLM's confidence that this is the right action (0.0–1.0) */
+  confidence: number;
+
+  /**
+   * Action-specific parameters.
+   * - type/setValue: { text: string }
+   * - select: { value: string } or { label: string }
+   * - scroll: { direction: "up"|"down"|"left"|"right" }
+   * - drag: { targetPosition: { x: number, y: number } }
+   * - sendKeys: { keys: string }
+   * - navigate: { url: string }
+   * - wait: { ms: number }
+   */
+  params?: Record<string, unknown>;
+
+  /**
+   * Separates the generic intent from specific data.
+   * Enables action plan caching: the query stays stable across runs,
+   * only the answer changes per user context.
+   *
+   * Example:
+   *   userDetailQuery: "What email should be entered?"
+   *   userDetailAnswer: "test@example.com"
+   */
+  userDetailQuery?: string;
+  userDetailAnswer?: string;
+}
+
+// =============================================================================
+// Action Plan
+// =============================================================================
+
+/**
+ * A complete action plan: an ordered sequence of UI actions
+ * produced by the agentic-phase LLM.
+ */
+export interface ActionPlan {
+  /** Ordered list of actions to execute */
+  actions: PlannedAction[];
+
+  /** High-level goal this plan achieves */
+  goal: string;
+
+  /**
+   * Minimum confidence threshold. Actions below this confidence
+   * are skipped (or trigger verification) rather than executed.
+   * Default: 0.5
+   */
+  confidenceThreshold?: number;
+
+  /** Whether to stop on first action failure (default: true) */
+  stopOnFailure?: boolean;
+}
+
+// =============================================================================
+// Action Plan Result
+// =============================================================================
+
+/** Result of executing a single planned action */
+export interface PlannedActionResult {
+  /** Index of the action in the plan */
+  index: number;
+
+  /** Whether the action succeeded */
+  success: boolean;
+
+  /** The action that was executed */
+  action: PlannedActionType;
+
+  /** Element ID that was resolved and acted upon */
+  resolvedElementId?: string;
+
+  /** Error message if the action failed */
+  error?: string;
+
+  /** Whether the action was skipped due to low confidence */
+  skippedLowConfidence?: boolean;
+
+  /** Duration in milliseconds */
+  durationMs: number;
+
+  /** Post-action element state (if available) */
+  elementState?: Record<string, unknown>;
+}
+
+/** Aggregated result of executing a full action plan */
+export interface ActionPlanResult {
+  /** Whether all executed actions succeeded */
+  success: boolean;
+
+  /** The goal from the action plan */
+  goal?: string;
+
+  /** Per-action results */
+  results: PlannedActionResult[];
+
+  /** Count of actions executed (excludes skipped) */
+  executedCount: number;
+
+  /** Count of actions skipped due to low confidence */
+  skippedCount: number;
+
+  /** Count of actions that failed */
+  failedCount: number;
+
+  /** Total duration in milliseconds */
+  totalDurationMs: number;
+
+  /** Whether this plan was stored in the cache for future reuse */
+  cached?: boolean;
+}
+
+/**
+ * Extended action plan request with caching fields.
+ * Used when calling the endpoint directly (not via workflow steps).
+ */
+export interface ActionPlanExecuteRequest extends ActionPlan {
+  /** Page URL for cache keying */
+  pageUrl?: string;
+  /** Element snapshot for cache fingerprinting (array of {id, type, role, label}) */
+  elementSnapshot?: Array<{ id?: string; type?: string; role?: string; label?: string }>;
+}

package/src/workflow/index.ts

@@ -0,0 +1 @@
+export * from "./_api";

package/src/workflow/skill.ts

@@ -0,0 +1,152 @@
+/**
+ * Skill Types
+ *
+ * A skill is a named, parameterized template that produces pre-configured
+ * workflow step(s) when instantiated. Skills sit between raw step types
+ * and full workflows:
+ *
+ *   Raw Step Types  (command, prompt, ui_bridge, workflow)  ← execution primitives
+ *        ↑ instantiates
+ *   Skills          ("Lint Project", "API Health Check")    ← named capability templates
+ *        ↑ composes into
+ *   Workflows       (multi-phase verification-agentic loops) ← orchestration
+ *
+ * Skills are purely a configuration-time abstraction — they produce steps,
+ * they do NOT add new runtime behavior.
+ */
+
+import type { WorkflowPhase } from "./index";
+
+// =============================================================================
+// Skill Categories
+// =============================================================================
+
+export type SkillCategory =
+  | "code-quality"
+  | "testing"
+  | "monitoring"
+  | "ai-task"
+  | "deployment"
+  | "composition"
+  | "custom";
+
+// =============================================================================
+// Skill Author
+// =============================================================================
+
+export interface SkillAuthor {
+  name: string;
+  email?: string;
+  url?: string;
+}
+
+// =============================================================================
+// Skill Parameters
+// =============================================================================
+
+export interface SkillParameterOption {
+  label: string;
+  value: string;
+}
+
+export interface SkillParameter {
+  name: string;
+  type: "string" | "number" | "boolean" | "select";
+  label: string;
+  description: string;
+  required: boolean;
+  default?: unknown;
+  options?: SkillParameterOption[];
+  placeholder?: string;
+  min?: number;
+  max?: number;
+  pattern?: string;
+  depends_on?: { param: string; value: unknown };
+}
+
+// =============================================================================
+// Skill Templates
+// =============================================================================
+
+export interface SingleStepTemplate {
+  kind: "single_step";
+  step: Record<string, unknown>;
+}
+
+export interface MultiStepTemplate {
+  kind: "multi_step";
+  steps: Record<string, unknown>[];
+}
+
+export interface CompositionTemplate {
+  kind: "composition";
+  skill_refs: SkillRef[];
+}
+
+export interface SkillRef {
+  skill_id: string;
+  parameter_overrides?: Record<string, unknown>;
+}
+
+export type SkillTemplate = SingleStepTemplate | MultiStepTemplate | CompositionTemplate;
+
+// =============================================================================
+// Skill Definition
+// =============================================================================
+
+export interface SkillDefinition {
+  id: string;
+  name: string;
+  slug: string;
+  description: string;
+  category: SkillCategory;
+  tags: string[];
+  icon: string;
+  color: string;
+  allowed_phases: WorkflowPhase[];
+  parameters: SkillParameter[];
+  template: SkillTemplate;
+  source: "builtin" | "user" | "community";
+  version?: string;
+  author?: SkillAuthor;
+  checksum?: string;
+  depends_on?: string[];
+  usage_count?: number;
+  approval_status?: "pending" | "approved" | "rejected";
+  forked_from?: string;
+}
+
+// =============================================================================
+// Skill Origin (attached to steps created from skills)
+// =============================================================================
+
+export interface SkillOrigin {
+  skill_id: string;
+  skill_slug: string;
+  parameter_values: Record<string, unknown>;
+}
+
+// =============================================================================
+// Export / Import
+// =============================================================================
+
+export interface SkillExportManifest {
+  version: string;
+  exported_at: string;
+  app_version: string;
+  content_type: "skills";
+  skill_count: number;
+  checksum?: string;  // SHA-256 of all skill content
+}
+
+export interface SkillExport {
+  manifest: SkillExportManifest;
+  skills: SkillDefinition[];
+}
+
+export interface SkillImportResult {
+  imported: number;
+  skipped: number;
+  overwritten: number;
+  errors: string[];
+}