@qontinui/shared-types 0.11.0 → 0.12.1

package/src/generated/HelperTask.d.ts

@@ -20,6 +20,9 @@ import type { HelperVerdict } from "./HelperVerdict";
  * verdict and routes it back through [`source`](HelperTask::source).
  */
 export interface HelperTask {
+  /**
+   * The set of allowed answers and preset reason codes offered to the helper.
+   */
   answerSchema: HelperAnswerSchema;
   /**
    * Application the task pertains to.
@@ -38,7 +41,13 @@ export interface HelperTask {
    * Task ID (UUID v4 string).
    */
   id: string;
+  /**
+   * Which kind of judgment is being asked for.
+   */
   kind: HelperTaskKind;
+  /**
+   * Kind-specific content (screenshot URL, compare URLs, steps, …).
+   */
   payload: HelperTaskPayload;
   /**
    * Human-readable question shown to the helper (e.g. "Does this login
@@ -49,7 +58,14 @@ export interface HelperTask {
    * Number of helper answers required before the task is `Answered`.
    */
   requiredVotes: number;
+  /**
+   * Provenance linking the task back to its originating finding / page /
+   * spec-check.
+   */
   source: HelperTaskSource;
+  /**
+   * Current lifecycle status.
+   */
   status: HelperTaskStatus;
   /**
    * Tenant that owns the task (coord tenant id).

package/src/generated/HistoricalActionResult.d.ts

@@ -16,6 +16,9 @@ export interface HistoricalActionResult {
    * Human-readable action name.
    */
   actionName: string;
+  /**
+   * Kind of action.
+   */
   actionType: ExecutionActionType;
   /**
    * Duration in milliseconds.
@@ -49,6 +52,9 @@ export interface HistoricalActionResult {
    * URL to an associated screenshot, if any.
    */
   screenshotUrl?: string | null;
+  /**
+   * Outcome.
+   */
   status: ActionStatus;
   /**
    * Target state.

package/src/generated/IrPageSpec.d.ts

@@ -19,6 +19,48 @@ import type { IrTransitionAction } from "./IrTransitionAction";
 import type { IrWaitSpec } from "./IrWaitSpec";
 import type { ProposalStatus } from "./ProposalStatus";
 
+/**
+ * API assertion: either a value-level assertion (status_code, json_path, etc.)
+ * or a schema-conformance assertion (conforms_to — Phase 2 placeholder).
+ */
+export type IrApiAssertion =
+  | {
+      expected: unknown;
+      operator?: string | null;
+      type: "status_code";
+      [k: string]: unknown;
+    }
+  | {
+      expected: unknown;
+      json_path: string;
+      operator?: string | null;
+      type: "json_path";
+      [k: string]: unknown;
+    }
+  | {
+      expected: unknown;
+      header_name: string;
+      operator?: string | null;
+      type: "header";
+      [k: string]: unknown;
+    }
+  | {
+      expected: unknown;
+      type: "body_contains";
+      [k: string]: unknown;
+    }
+  | {
+      expected: unknown;
+      operator?: string | null;
+      type: "response_time";
+      [k: string]: unknown;
+    }
+  | {
+      schema: string;
+      type: "conforms_to";
+      [k: string]: unknown;
+    };
+
 /**
  * Top-level IR page specification (formerly `IrDocument`).
  *
@@ -55,3 +97,23 @@ export interface IrPageSpec {
   version: string;
   [k: string]: unknown;
 }
+/**
+ * A single API-contract check: issue a request, validate the response.
+ */
+export interface IrApiCheck {
+  assertions: IrApiAssertion[];
+  description?: string | null;
+  effect: string;
+  id: string;
+  request: IrApiRequest;
+  [k: string]: unknown;
+}
+export interface IrApiRequest {
+  body?: unknown;
+  headers?: {
+    [k: string]: string;
+  } | null;
+  method: string;
+  path: string;
+  [k: string]: unknown;
+}

package/src/generated/IterationResult.d.ts

@@ -25,6 +25,9 @@ export interface IterationResult {
    * Diagnostic-phase result (if the diagnose phase is configured).
    */
   diagnosticResult?: DiagnosticResult | null;
+  /**
+   * Exit-check outcome for this iteration.
+   */
   exitCheck: ExitCheckResult;
   /**
    * Number of fixes proposed during reflection.

package/src/generated/LoopInstanceStatus.d.ts

@@ -24,5 +24,8 @@ export interface LoopInstanceStatus {
    * Unique identifier for this loop.
    */
   loopId: string;
+  /**
+   * The per-loop status snapshot.
+   */
   status: OrchestrationLoopStatus;
 }

package/src/generated/McpServerConfig.d.ts

@@ -69,6 +69,9 @@ export interface McpServerConfig {
    * ISO 8601 timestamp of when `cached_tools` was populated.
    */
   toolsCachedAt?: string | null;
+  /**
+   * Which transport this server uses.
+   */
   transport: McpTransport;
   /**
    * ISO 8601 last-update timestamp.

package/src/generated/McpToolInfo.d.ts

@@ -15,6 +15,9 @@ export interface McpToolInfo {
    * Tool description shown to users.
    */
   description?: string | null;
+  /**
+   * Input-argument schema. Wire field is `"inputSchema"` per MCP spec.
+   */
   inputSchema: McpToolInputSchema;
   /**
    * Tool name (the argument passed back on `tools/call`).

package/src/generated/Monitor.d.ts

@@ -28,6 +28,9 @@ export interface Monitor {
    * Display name (e.g., "DELL U2720Q").
    */
   name?: string | null;
+  /**
+   * Spatial position based on X coordinate (for UI display).
+   */
   position: MonitorPosition;
   /**
    * DPI scale factor (1.0 = 100%, 1.5 = 150%, 2.0 = 200%).

package/src/generated/MultiLoopEntry.d.ts

@@ -20,6 +20,9 @@ import type { SummarizationConfig } from "./SummarizationConfig";
  * A single entry in a multi-loop configuration.
  */
 export interface MultiLoopEntry {
+  /**
+   * The loop configuration.
+   */
   config: OrchestrationLoopConfig;
   /**
    * Human label (e.g., `"Pages 1–10"` or an app section name).

package/src/generated/NewConstraintProposal.d.ts

@@ -16,5 +16,8 @@ import type { ConstraintSeverity } from "./ConstraintSeverity";
  * enum's internal tag.
  */
 export interface NewConstraintProposal {
+  /**
+   * The proposed constraint definition.
+   */
   constraint: Constraint;
 }

package/src/generated/OrchestrationLoopStatus.d.ts

@@ -35,6 +35,9 @@ export interface OrchestrationLoopStatus {
    * Iteration cap for this run. `None` renders as `"∞"`/unlimited in the UI.
    */
   maxIterations?: number | null;
+  /**
+   * Current phase.
+   */
   phase: LoopPhase;
   /**
    * Whether the loop is currently running.

package/src/generated/OutputLine.d.ts

@@ -15,6 +15,9 @@ export interface OutputLine {
    * The line content
    */
   line: string;
+  /**
+   * Which stream this came from
+   */
   stream: OutputStream;
   /**
    * ISO 8601 timestamp

package/src/generated/PolicyConjunct.d.ts

@@ -17,6 +17,13 @@ export interface PolicyConjunct {
    * Human-readable name used in `ConjunctEvaluation.name`.
    */
   name: string;
+  /**
+   * The conjunct rule.
+   */
   rule: ConjunctRule;
+  /**
+   * Filter narrowing which assertions / states this conjunct applies
+   * to.
+   */
   scope: AssertionScope;
 }

package/src/generated/PolicyEvaluation.d.ts

@@ -18,5 +18,9 @@ export interface PolicyEvaluation {
    * order.
    */
   conjunctResults: ConjunctEvaluation[];
-  overallStatus: PolicyStatus1;
+  /**
+   * Aggregate of all conjunct statuses — fails if any conjunct fails;
+   * indeterminate if any conjunct is indeterminate and none failed.
+   */
+  overallStatus: PolicyStatus;
 }

package/src/generated/ProcessStatusLite.d.ts

@@ -34,5 +34,8 @@ export interface ProcessStatusLite {
    * process declares no health port.
    */
   portHealthy?: boolean | null;
+  /**
+   * Lifecycle state as reported by the process manager.
+   */
   state: ProcessState;
 }

package/src/generated/Profile.d.ts

@@ -14,7 +14,13 @@ import type { EnforcementProfile } from "./EnforcementProfile";
  * The top-level Priorities Profile.
  */
 export interface Profile {
+  /**
+   * Architectural shape + testing bar.
+   */
   architecture: ArchitectureProfile;
+  /**
+   * Target backend stack.
+   */
   backend: BackendProfile;
   /**
    * Naming / mapping conventions, as free-form `key -> value` pairs (e.g.

package/src/generated/ProjectSnapshot.d.ts

@@ -44,6 +44,9 @@ export interface ProjectSnapshot {
    * Managed processes whose `cwd` is under the project root.
    */
   processes: ProcessStatusLite[];
+  /**
+   * The registry entry this snapshot describes.
+   */
   project: SavedProject;
   /**
    * Questions waiting on the user, from `deferred_questions`.

package/src/generated/PromptStep.d.ts

@@ -57,6 +57,9 @@ export interface PromptStep {
    * Display name for the step.
    */
   name: string;
+  /**
+   * Phase in which the step appears.
+   */
   phase: PromptStepPhase;
   /**
    * Saved prompt ID (when the body is a reference).

package/src/generated/RecommendedState.d.ts

@@ -11,6 +11,9 @@ import type { SpecCheckConfidence } from "./SpecCheckConfidence";
  * The single state the matcher recommends the caller treat as "current".
  */
 export interface RecommendedState {
+  /**
+   * Matcher confidence in the recommendation.
+   */
   confidence: SpecCheckConfidence;
   /**
    * Free-form explanation (e.g. "highest match rate among all states").

package/src/generated/ResolvedInitialStates.d.ts

@@ -13,6 +13,9 @@ import type { InitialStatesSource } from "./InitialStatesSource";
  * resolution came from.
  */
 export interface ResolvedInitialStates {
+  /**
+   * Where the resolution came from.
+   */
   source: InitialStatesSource;
   /**
    * Resolved initial state IDs.

package/src/generated/ResolvedInitialStatesResult.d.ts

@@ -20,6 +20,9 @@ export interface ResolvedInitialStatesResult {
    * Error message when resolution failed.
    */
   error?: string | null;
+  /**
+   * Where the resolution came from.
+   */
   source: InitialStatesSource;
   /**
    * Resolved initial state IDs.

package/src/generated/Runner.d.ts

@@ -28,6 +28,10 @@ export interface Runner {
    * ISO 8601 timestamp when the runner was first registered.
    */
   createdAt: string;
+  /**
+   * Computed health state derived from `ws_connected` and
+   * `last_heartbeat`. Authoritative for UI display.
+   */
   derivedStatus: RunnerStatus;
   /**
    * Reported hostname of the machine the runner is running on.

package/src/generated/ScheduledTask.d.ts

@@ -91,6 +91,9 @@ export interface ScheduledTask {
    * Next scheduled run time (ISO 8601), computed by the runner.
    */
   nextRun?: string | null;
+  /**
+   * Schedule configuration.
+   */
   schedule: ScheduleExpression;
   /**
    * Skip future runs once the task has succeeded at least once.
@@ -100,5 +103,8 @@ export interface ScheduledTask {
    * Free-form description of success criteria, for human reference.
    */
   successCriteria?: string | null;
+  /**
+   * Task type and its per-type configuration.
+   */
   task: ScheduledTaskType;
 }

package/src/generated/ScreenshotAnnotation.d.ts

@@ -23,6 +23,9 @@ export interface ScreenshotAnnotation {
    * Free-form label for the annotation.
    */
   label?: string | null;
+  /**
+   * Shape of the annotation.
+   */
   type: ScreenshotAnnotationShape;
   /**
    * Annotation width in pixels.

package/src/generated/SessionLite.d.ts

@@ -31,6 +31,9 @@ export interface SessionLite {
    * Session name — `task_runs.task_name` or the terminal's title.
    */
   name?: string | null;
+  /**
+   * Where this row came from.
+   */
   source: SessionSource;
   /**
    * `task_runs.status` ("running", "completed", …) for AI sessions;

package/src/generated/SpecApiEvent.d.ts

@@ -88,3 +88,29 @@ export type SpecApiEvent =
       type: "flywheel-proposal-demoted";
       [k: string]: unknown;
     };
+
+/**
+ * Existing `POST /spec/author` change-broadcast payload. Pre-dates the
+ * Plan 06 `SpecApiEvent` sum-type but keeps the same shape so external
+ * SSE subscribers (the runner's `use-discovered-specs.ts`) keep working.
+ */
+export interface SpecChanged {
+  /**
+   * Owning app id (multi-tenant Spec API). Subscribers filter on this
+   * to receive only their app's events. `#[serde(default)]` allows
+   * legacy emitters (pre-multi-app) to omit the field; downstream
+   * per-app routing treats empty as `qontinui-runner` for back-compat.
+   */
+  appId: string;
+  /**
+   * Epoch milliseconds the event was emitted at.
+   */
+  atMs: number;
+  /**
+   * "ir-and-projection" today; future kinds may include
+   * "projection-only" if a regen runs without an IR write.
+   */
+  kind: string;
+  pageId: string;
+  [k: string]: unknown;
+}

package/src/generated/SpecCheckResult.d.ts

@@ -29,6 +29,9 @@ import type { StateMatchResult } from "./StateMatchResult";
  * deserialize as `0`.
  */
 export interface SpecCheckResult {
+  /**
+   * App / route / bridge-version fingerprint at snapshot time. §5.8 G3.
+   */
   bridgeFingerprint: BridgeFingerprint;
   /**
    * Red/Yellow/Green classification of the overall match rate.
@@ -77,6 +80,9 @@ export interface SpecCheckResult {
    * One result per `IrState` in the spec.
    */
   stateResults: StateMatchResult[];
+  /**
+   * Aggregate summary across all evaluated states.
+   */
   summary: SpecCheckSummary;
   thresholdsUsed: ThresholdConfig;
   /**
@@ -84,3 +90,19 @@ export interface SpecCheckResult {
    */
   warnings?: string[];
 }
+/**
+ * The threshold configuration that was active at evaluation time.
+ * Immutable snapshot for audit purposes — allows historical results
+ * to be cross-checked against their contemporaneous thresholds.
+ */
+export interface ThresholdConfig {
+  /**
+   * Red threshold (0.0–1.0). Match rate < this → Red.
+   */
+  redThreshold: number;
+  /**
+   * Yellow threshold (0.0–1.0). Match rate >= this → Green.
+   * Must be > `red_threshold`.
+   */
+  yellowThreshold: number;
+}

package/src/generated/SpecCheckStepConfig.d.ts

@@ -34,5 +34,8 @@ export interface SpecCheckStepConfig {
    * Page to evaluate.
    */
   pageId: string;
+  /**
+   * Policy that determines pass / fail.
+   */
   policy: SpecCheckPolicy;
 }

package/src/generated/SpecCheckSummary.d.ts

@@ -14,6 +14,9 @@ import type { SpecCheckConfidence } from "./SpecCheckConfidence";
  * Aggregate summary across all evaluated states.
  */
 export interface SpecCheckSummary {
+  /**
+   * Top-level pass / partial / no-match verdict.
+   */
   matchOutcome: MatchOutcome;
   /**
    * Mean of per-state match rates, weighted equally.
@@ -33,5 +36,8 @@ export interface SpecCheckSummary {
    * as "current". `None` when the matcher has no preference.
    */
   recommendedState?: RecommendedState | null;
+  /**
+   * Counts of assertion failures bucketed by severity.
+   */
   severityCounts: AssertionSeverityCounts;
 }

package/src/generated/StateDiscoveryResult.d.ts

@@ -76,6 +76,9 @@ export interface StateDiscoveryResult {
    * ID of the source session (extraction, recording, …).
    */
   sourceSessionId?: string | null;
+  /**
+   * How this state machine was discovered.
+   */
   sourceType: DiscoverySourceType;
   /**
    * Number of states (statistic).

package/src/generated/StateDiscoveryResultCreate.d.ts

@@ -53,6 +53,9 @@ export interface StateDiscoveryResultCreate {
    * ID of the source session.
    */
   sourceSessionId?: string | null;
+  /**
+   * Discovery source.
+   */
   sourceType: DiscoverySourceType;
   /**
    * Discovered states.

package/src/generated/StateDiscoveryResultSummary.d.ts

@@ -45,6 +45,9 @@ export interface StateDiscoveryResultSummary {
    * ID of the project.
    */
   projectId: string;
+  /**
+   * Discovery source.
+   */
   sourceType: DiscoverySourceType;
   /**
    * Number of states.

package/src/generated/StateMachineImport.d.ts

@@ -21,5 +21,8 @@ export interface StateMachineImport {
    * Override name (uses export name when omitted).
    */
   name?: string | null;
+  /**
+   * The state machine to import.
+   */
   stateMachine: StateMachineExport;
 }

package/src/generated/SuccessCriterion.d.ts

@@ -38,6 +38,9 @@ export interface SuccessCriterion {
    * Whether this criterion must pass for task completion.
    */
   required: boolean;
+  /**
+   * Type of verification required. Serialized as `"type"` on the wire.
+   */
   type: CriterionType;
   /**
    * Configuration blob for the verification method (command args, log

package/src/generated/TaskCompletionResult.d.ts

@@ -29,6 +29,9 @@ export type TaskCompletionResult =
        */
       iterations: number;
       status: "success";
+      /**
+       * Final verification results.
+       */
       verification_results: IterationVerificationResults;
       [k: string]: unknown;
     }
@@ -44,7 +47,7 @@ export type TaskCompletionResult =
       /**
        * Last verification results (if any).
        */
-      last_results?: IterationVerificationResults1 | null;
+      last_results?: IterationVerificationResults | null;
       /**
        * Human-readable reason for the failure.
        */
@@ -80,7 +83,7 @@ export type TaskCompletionResult =
       /**
        * Last verification results (if any).
        */
-      last_results?: IterationVerificationResults1 | null;
+      last_results?: IterationVerificationResults | null;
       /**
        * The max-iteration limit that triggered the pause.
        */

package/src/generated/TaskExecutionRecord.d.ts

@@ -49,6 +49,9 @@ export interface TaskExecutionRecord {
    * ISO 8601 timestamp when execution started.
    */
   startedAt: string;
+  /**
+   * Current status of this execution.
+   */
   status: ScheduledTaskStatus;
   /**
    * Whether the task succeeded, read from the session checkpoint.

package/src/generated/TaskRun.d.ts

@@ -63,6 +63,9 @@ export interface TaskRun {
    * Number of AI sessions that have been run.
    */
   sessionsCount: number;
+  /**
+   * Current lifecycle status.
+   */
   status: TaskRunStatus;
   /**
    * AI-generated summary of the task run.
@@ -76,6 +79,9 @@ export interface TaskRun {
    * Display name of the task.
    */
   taskName: string;
+  /**
+   * Kind of task (one-off, automation, or scheduled).
+   */
   taskType: TaskType;
   /**
    * ISO 8601 timestamp when the task record was last updated.

package/src/generated/TaskRunBackend.d.ts

@@ -74,6 +74,9 @@ export interface TaskRunBackend {
    * Number of AI sessions that have been run.
    */
   sessionsCount: number;
+  /**
+   * Current lifecycle status.
+   */
   status: TaskRunStatus;
   /**
    * Display name.

package/src/generated/TaskRunBackendDetail.d.ts

@@ -45,6 +45,9 @@ export interface TaskRunBackendDetail {
    * Error message if the task failed.
    */
   errorMessage: string | null;
+  /**
+   * Aggregated counts of findings.
+   */
   findingSummary: TaskRunFindingSummary;
   /**
    * Findings surfaced during this task run.
@@ -86,6 +89,9 @@ export interface TaskRunBackendDetail {
    * Number of AI sessions that have been run.
    */
   sessionsCount: number;
+  /**
+   * Current lifecycle status.
+   */
   status: TaskRunStatus;
   /**
    * Display name.

package/src/generated/TaskRunFinding.d.ts

@@ -17,7 +17,13 @@ import type { TaskRunFindingStatus } from "./TaskRunFindingStatus";
  * possibly `null`), so they use `serde(default)` without `skip_serializing_if`.
  */
 export interface TaskRunFinding {
+  /**
+   * How the finding should be acted upon.
+   */
   actionType: TaskRunFindingActionType;
+  /**
+   * Category (bug, security, performance, etc.).
+   */
   category: TaskRunFindingCategory;
   /**
    * Snippet of code illustrating the issue.
@@ -75,11 +81,17 @@ export interface TaskRunFinding {
    * Session number in which the finding was resolved.
    */
   resolvedInSession: number | null;
+  /**
+   * Severity of the finding.
+   */
   severity: TaskRunFindingSeverity;
   /**
    * Hash used to deduplicate findings across runs.
    */
   signatureHash: string | null;
+  /**
+   * Current lifecycle status.
+   */
   status: TaskRunFindingStatus;
   /**
    * Parent task run ID.