@ancplua/qyl-api-schema 3.0.0 → 5.0.0

package/generated/ts-runtime/api.d.ts

@@ -34,6 +34,30 @@ export type WorkbenchSuiteId = string & {
 export type WorkbenchEvaluationExportId = string & {
     readonly __brand: "WorkbenchEvaluationExportId";
 };
+export type WorkflowRunId = string & {
+    readonly __brand: "WorkflowRunId";
+};
+export type WorkflowAttemptId = string & {
+    readonly __brand: "WorkflowAttemptId";
+};
+export type WorkflowContentRef = string & {
+    readonly __brand: "WorkflowContentRef";
+};
+export type WorkflowEventId = string & {
+    readonly __brand: "WorkflowEventId";
+};
+export type WorkflowAgentId = string & {
+    readonly __brand: "WorkflowAgentId";
+};
+export type WorkflowToolCallId = string & {
+    readonly __brand: "WorkflowToolCallId";
+};
+export type WorkflowNodeId = string & {
+    readonly __brand: "WorkflowNodeId";
+};
+export type WorkflowCommandId = string & {
+    readonly __brand: "WorkflowCommandId";
+};
 export declare const ProblemDetailsMediaType: "application/problem+json";
 export type ProblemDetailsMediaType = typeof ProblemDetailsMediaType;
 export declare const SortOrderValues: {
@@ -351,11 +375,122 @@ export declare const WorkbenchTransportKindValues: {
     readonly builtin: "builtin";
 };
 export type WorkbenchTransportKind = typeof WorkbenchTransportKindValues[keyof typeof WorkbenchTransportKindValues];
+export declare const WorkflowRunStatusValues: {
+    readonly active: "active";
+    readonly completed: "completed";
+    readonly failed: "failed";
+    readonly interrupted: "interrupted";
+};
+export type WorkflowRunStatus = typeof WorkflowRunStatusValues[keyof typeof WorkflowRunStatusValues];
+export declare const WorkflowContentEncodingValues: {
+    readonly utf8: "utf8";
+    readonly base64: "base64";
+};
+export type WorkflowContentEncoding = typeof WorkflowContentEncodingValues[keyof typeof WorkflowContentEncodingValues];
+export declare const WorkflowJournalEventKindValues: {
+    readonly runCreated: "run_created";
+    readonly runCompleted: "run_completed";
+    readonly threadStarted: "thread_started";
+    readonly threadResumed: "thread_resumed";
+    readonly turnStarted: "turn_started";
+    readonly turnCompleted: "turn_completed";
+    readonly turnInterrupted: "turn_interrupted";
+    readonly attemptStarted: "attempt_started";
+    readonly attemptCompleted: "attempt_completed";
+    readonly agentSpawned: "agent_spawned";
+    readonly agentStarted: "agent_started";
+    readonly agentCompleted: "agent_completed";
+    readonly messageSent: "message_sent";
+    readonly messageReceived: "message_received";
+    readonly waitStarted: "wait_started";
+    readonly waitCompleted: "wait_completed";
+    readonly joined: "joined";
+    readonly itemStarted: "item_started";
+    readonly itemCompleted: "item_completed";
+    readonly toolStarted: "tool_started";
+    readonly toolCompleted: "tool_completed";
+    readonly approvalRequested: "approval_requested";
+    readonly approvalResolved: "approval_resolved";
+    readonly contentCaptured: "content_captured";
+    readonly fileWritten: "file_written";
+    readonly controlRequested: "control_requested";
+    readonly controlAccepted: "control_accepted";
+    readonly controlApplied: "control_applied";
+    readonly controlRejected: "control_rejected";
+    readonly controlFailed: "control_failed";
+};
+export type WorkflowJournalEventKind = typeof WorkflowJournalEventKindValues[keyof typeof WorkflowJournalEventKindValues];
+export declare const WorkflowNodeKindValues: {
+    readonly run: "run";
+    readonly attempt: "attempt";
+    readonly turn: "turn";
+    readonly agent: "agent";
+    readonly toolCall: "tool_call";
+    readonly message: "message";
+    readonly wait: "wait";
+    readonly gate: "gate";
+    readonly resource: "resource";
+};
+export type WorkflowNodeKind = typeof WorkflowNodeKindValues[keyof typeof WorkflowNodeKindValues];
+export declare const WorkflowEdgeKindValues: {
+    readonly data: "data";
+    readonly control: "control";
+    readonly conflict: "conflict";
+    readonly resource: "resource";
+    readonly gate: "gate";
+    readonly temporal: "temporal";
+};
+export type WorkflowEdgeKind = typeof WorkflowEdgeKindValues[keyof typeof WorkflowEdgeKindValues];
+export declare const WorkflowControlActionValues: {
+    readonly steer: "steer";
+    readonly interrupt: "interrupt";
+    readonly resume: "resume";
+};
+export type WorkflowControlAction = typeof WorkflowControlActionValues[keyof typeof WorkflowControlActionValues];
+export declare const WorkflowControlStatusValues: {
+    readonly requested: "requested";
+    readonly accepted: "accepted";
+    readonly applied: "applied";
+    readonly rejected: "rejected";
+    readonly failed: "failed";
+};
+export type WorkflowControlStatus = typeof WorkflowControlStatusValues[keyof typeof WorkflowControlStatusValues];
+export declare const WorkflowAttemptStatusValues: {
+    readonly pending: "pending";
+    readonly running: "running";
+    readonly succeeded: "succeeded";
+    readonly failed: "failed";
+    readonly interrupted: "interrupted";
+};
+export type WorkflowAttemptStatus = typeof WorkflowAttemptStatusValues[keyof typeof WorkflowAttemptStatusValues];
+export declare const WorkflowAgentStatusValues: {
+    readonly pending: "pending";
+    readonly running: "running";
+    readonly waiting: "waiting";
+    readonly succeeded: "succeeded";
+    readonly failed: "failed";
+    readonly interrupted: "interrupted";
+};
+export type WorkflowAgentStatus = typeof WorkflowAgentStatusValues[keyof typeof WorkflowAgentStatusValues];
+export declare const WorkflowToolCallStatusValues: {
+    readonly requested: "requested";
+    readonly running: "running";
+    readonly succeeded: "succeeded";
+    readonly failed: "failed";
+    readonly rejected: "rejected";
+};
+export type WorkflowToolCallStatus = typeof WorkflowToolCallStatusValues[keyof typeof WorkflowToolCallStatusValues];
 export declare const McpDataModeValues: {
     readonly live: "live";
     readonly demo: "demo";
 };
 export type McpDataMode = typeof McpDataModeValues[keyof typeof McpDataModeValues];
+export declare const CiPhaseStatusValues: {
+    readonly ok: "ok";
+    readonly error: "error";
+    readonly unset: "unset";
+};
+export type CiPhaseStatus = typeof CiPhaseStatusValues[keyof typeof CiPhaseStatusValues];
 export declare const FetchTelemetryViewValues: {
     readonly traces: "traces";
     readonly trace: "trace";
@@ -374,6 +509,8 @@ export type WorkbenchTestAssertion = WorkbenchStatusAssertion | WorkbenchExactAs
 export type WorkbenchEvaluationExportPayload = WorkbenchEvaluationJsonExportPayload | WorkbenchEvaluationReportExportPayload;
 export type WorkbenchProtocolEvents = WorkbenchProtocolEvent;
 export type WorkbenchExecutionUpdateEvents = WorkbenchExecutionRecord;
+export type WorkflowEdgeProvenance = RecordedWorkflowEdgeProvenance | DerivedWorkflowEdgeProvenance;
+export type WorkflowStreamEvents = WorkflowJournalEvent | WorkflowHeartbeatEvent | WorkflowCursorGapEvent;
 export type LogEvents = LogStreamEvent | HeartbeatEvent;
 export interface AttributeBytesValue {
     "type": "bytes";
@@ -703,6 +840,7 @@ export interface HealthReport {
     "status": HealthStatus;
     "total_duration_ms": number;
     "entries": Record<string, HealthCheckEntry>;
+    "contract_revision": string;
 }
 export interface RunnerResourceState {
     "name": string;
@@ -1217,6 +1355,169 @@ export interface WorkbenchEvaluationExportArtifact {
 export interface WorkbenchEvaluationExportAccepted {
     "export": WorkbenchEvaluationExport;
 }
+export interface WorkflowRun {
+    "run_id": WorkflowRunId;
+    "thread_id"?: string;
+    "title"?: string;
+    "status": WorkflowRunStatus;
+    "started_at": string;
+    "ended_at"?: string;
+    "latest_journal_sequence": string;
+    "active_attempt_id"?: WorkflowAttemptId;
+    "metadata"?: Record<string, unknown>;
+}
+export interface WorkflowRunCreateRequest {
+    "run_id": WorkflowRunId;
+    "thread_id"?: string;
+    "title"?: string;
+    "started_at": string;
+    "metadata"?: Record<string, unknown>;
+}
+export interface WorkflowRunPage {
+    "items": WorkflowRun[];
+    "next_cursor"?: string;
+    "has_more": boolean;
+}
+export interface WorkflowContentChunk {
+    "content_ref": WorkflowContentRef;
+    "content_type": string;
+    "encoding": WorkflowContentEncoding;
+    "content": string;
+}
+export interface WorkflowEventAppend {
+    "event_id": WorkflowEventId;
+    "source_sequence": string;
+    "timestamp": string;
+    "kind": WorkflowJournalEventKind;
+    "thread_id"?: string;
+    "turn_id"?: string;
+    "attempt_id"?: WorkflowAttemptId;
+    "agent_id"?: WorkflowAgentId;
+    "parent_agent_id"?: WorkflowAgentId;
+    "receiver_agent_id"?: WorkflowAgentId;
+    "tool_call_id"?: WorkflowToolCallId;
+    "content_refs"?: WorkflowContentRef[];
+    "data"?: Record<string, unknown>;
+}
+export interface WorkflowEventBatchAppendRequest {
+    "client_id": string;
+    "events": WorkflowEventAppend[];
+    "content"?: WorkflowContentChunk[];
+}
+export interface WorkflowEventBatchAppendResponse {
+    "accepted_count": number;
+    "duplicate_count": number;
+    "acknowledged_source_sequence": string;
+    "first_journal_sequence"?: string;
+    "last_journal_sequence"?: string;
+}
+export interface WorkflowJournalEvent extends WorkflowEventAppend {
+    "run_id": WorkflowRunId;
+    "client_id": string;
+    "journal_sequence": string;
+}
+export interface WorkflowEventPage {
+    "events": WorkflowJournalEvent[];
+    "next_sequence": string;
+    "high_water_mark": string;
+    "cursor_gap": boolean;
+}
+export interface RecordedWorkflowEdgeProvenance {
+    "type": "recorded";
+    "event_ids": WorkflowEventId[];
+}
+export interface DerivedWorkflowEdgeProvenance {
+    "type": "derived";
+    "event_ids": WorkflowEventId[];
+    "evidence": string;
+    "confidence": number;
+}
+export interface WorkflowGraphNode {
+    "node_id": WorkflowNodeId;
+    "kind": WorkflowNodeKind;
+    "label": string;
+    "status": string;
+    "attempt_id"?: WorkflowAttemptId;
+    "agent_id"?: WorkflowAgentId;
+    "parent_node_id"?: WorkflowNodeId;
+    "started_at"?: string;
+    "ended_at"?: string;
+    "duration_ms"?: number;
+    "content_refs"?: WorkflowContentRef[];
+    "attributes"?: Record<string, unknown>;
+}
+export interface WorkflowGraphEdge {
+    "edge_id": string;
+    "source_node_id": WorkflowNodeId;
+    "target_node_id": WorkflowNodeId;
+    "kind": WorkflowEdgeKind;
+    "provenance": WorkflowEdgeProvenance;
+}
+export interface WorkflowGraphStatistics {
+    "t1_ms": number;
+    "t_infinity_ms": number;
+    "wall_time_ms": number;
+    "peak_concurrency": number;
+    "worker_count": number;
+    "parallel_lower_bound_ms": number;
+    "critical_path_node_ids": WorkflowNodeId[];
+}
+export interface WorkflowGraphSnapshot {
+    "run": WorkflowRun;
+    "nodes": WorkflowGraphNode[];
+    "edges": WorkflowGraphEdge[];
+    "statistics": WorkflowGraphStatistics;
+    "journal_sequence": string;
+    "next_node_cursor"?: string;
+    "next_edge_cursor"?: string;
+    "has_more_nodes": boolean;
+    "has_more_edges": boolean;
+    "total_node_count": number;
+    "total_edge_count": number;
+}
+export interface WorkflowContent {
+    "content_ref": WorkflowContentRef;
+    "content_type": string;
+    "encoding": WorkflowContentEncoding;
+    "content": string;
+    "size_bytes": number;
+}
+export interface WorkflowControlRequest {
+    "action": WorkflowControlAction;
+    "idempotency_key": string;
+    "input"?: string;
+}
+export interface WorkflowControlCommand {
+    "command_id": WorkflowCommandId;
+    "run_id": WorkflowRunId;
+    "action": WorkflowControlAction;
+    "status": WorkflowControlStatus;
+    "idempotency_key": string;
+    "input"?: string;
+    "requested_at": string;
+    "updated_at": string;
+    "command_sequence": string;
+    "error"?: string;
+}
+export interface WorkflowControlCommandPage {
+    "commands": WorkflowControlCommand[];
+    "next_sequence": string;
+}
+export interface WorkflowControlStatusUpdateRequest {
+    "status": WorkflowControlStatus;
+    "error"?: string;
+}
+export interface WorkflowHeartbeatEvent {
+    "type": "heartbeat";
+    "high_water_mark": string;
+    "timestamp": string;
+}
+export interface WorkflowCursorGapEvent {
+    "type": "cursor_gap";
+    "oldest_available_sequence": string;
+    "high_water_mark": string;
+    "timestamp": string;
+}
 export interface DisplayTracesInput {
     "trace_id"?: TraceId;
     "session_id"?: SessionId;
@@ -1305,6 +1606,31 @@ export interface SearchLogsOutput {
     "logs": LogRecord[];
     "mode": McpDataMode;
 }
+export interface CiLogInput {
+    "run_id"?: SessionId;
+    "limit"?: number;
+}
+export interface CiRunSummary {
+    "run_id": SessionId;
+    "state": SessionState;
+    "start_time": string;
+    "duration_ms"?: number;
+    "error_count": number;
+    "services": string[];
+}
+export interface CiPhase {
+    "leg": string;
+    "phase": string;
+    "status": CiPhaseStatus;
+    "duration_ms": number;
+    "message"?: string;
+}
+export interface CiLogOutput {
+    "runs"?: CiRunSummary[];
+    "run_id"?: SessionId;
+    "phases"?: CiPhase[];
+    "mode": McpDataMode;
+}
 export interface FetchTelemetryInput {
     "view": FetchTelemetryView;
     "trace_id"?: TraceId;
@@ -1321,6 +1647,66 @@ export interface FetchTelemetryOutput {
     "stats"?: McpDashboardStats;
     "mode": McpDataMode;
 }
+export interface ListWorkflowRunsInput {
+    "status"?: WorkflowRunStatus;
+    "cursor"?: string;
+    "limit"?: number;
+}
+export interface ListWorkflowRunsOutput {
+    "runs": WorkflowRun[];
+    "next_cursor"?: string;
+    "has_more": boolean;
+    "mode": McpDataMode;
+}
+export interface GetWorkflowGraphInput {
+    "run_id": WorkflowRunId;
+    "node_cursor"?: string;
+    "node_limit"?: number;
+    "edge_cursor"?: string;
+    "edge_limit"?: number;
+}
+export interface GetWorkflowGraphOutput {
+    "graph": WorkflowGraphSnapshot;
+    "mode": McpDataMode;
+}
+export interface DisplayWorkflowGraphInput {
+    "run_id"?: WorkflowRunId;
+    "node_cursor"?: string;
+    "node_limit"?: number;
+    "edge_cursor"?: string;
+    "edge_limit"?: number;
+}
+export interface DisplayWorkflowGraphOutput {
+    "graph": WorkflowGraphSnapshot;
+    "live_controls_available": boolean;
+    "mode": McpDataMode;
+}
+export interface FetchWorkflowGraphUpdatesInput {
+    "run_id": WorkflowRunId;
+    "after_sequence": string;
+    "limit"?: number;
+    "wait_ms"?: number;
+    "node_cursor"?: string;
+    "node_limit"?: number;
+    "edge_cursor"?: string;
+    "edge_limit"?: number;
+    "content_ref"?: WorkflowContentRef;
+}
+export interface FetchWorkflowGraphUpdatesOutput {
+    "page": WorkflowEventPage;
+    "graph"?: WorkflowGraphSnapshot;
+    "content"?: WorkflowContent;
+    "mode": McpDataMode;
+}
+export interface ControlWorkflowRunInput {
+    "run_id": WorkflowRunId;
+    "action": WorkflowControlAction;
+    "idempotency_key": string;
+    "input"?: string;
+}
+export interface ControlWorkflowRunOutput {
+    "command": WorkflowControlCommand;
+}
 export interface LogStreamEvent {
     "type": "log";
     "data": LogRecord;
@@ -1354,3 +1740,5 @@ export interface CursorPageSessionEntity {
     "prev_cursor"?: string;
     "has_more": boolean;
 }
+/** Revision of the API contract these types were emitted from; compare against HealthReport.contract_revision. */
+export declare const CONTRACT_REVISION: string;

package/generated/ts-runtime/api.js

@@ -280,13 +280,116 @@ export const WorkbenchTransportKindValues = {
     "streamableHttp": "streamable_http",
     "builtin": "builtin",
 };
+export const WorkflowRunStatusValues = {
+    "active": "active",
+    "completed": "completed",
+    "failed": "failed",
+    "interrupted": "interrupted",
+};
+export const WorkflowContentEncodingValues = {
+    "utf8": "utf8",
+    "base64": "base64",
+};
+export const WorkflowJournalEventKindValues = {
+    "runCreated": "run_created",
+    "runCompleted": "run_completed",
+    "threadStarted": "thread_started",
+    "threadResumed": "thread_resumed",
+    "turnStarted": "turn_started",
+    "turnCompleted": "turn_completed",
+    "turnInterrupted": "turn_interrupted",
+    "attemptStarted": "attempt_started",
+    "attemptCompleted": "attempt_completed",
+    "agentSpawned": "agent_spawned",
+    "agentStarted": "agent_started",
+    "agentCompleted": "agent_completed",
+    "messageSent": "message_sent",
+    "messageReceived": "message_received",
+    "waitStarted": "wait_started",
+    "waitCompleted": "wait_completed",
+    "joined": "joined",
+    "itemStarted": "item_started",
+    "itemCompleted": "item_completed",
+    "toolStarted": "tool_started",
+    "toolCompleted": "tool_completed",
+    "approvalRequested": "approval_requested",
+    "approvalResolved": "approval_resolved",
+    "contentCaptured": "content_captured",
+    "fileWritten": "file_written",
+    "controlRequested": "control_requested",
+    "controlAccepted": "control_accepted",
+    "controlApplied": "control_applied",
+    "controlRejected": "control_rejected",
+    "controlFailed": "control_failed",
+};
+export const WorkflowNodeKindValues = {
+    "run": "run",
+    "attempt": "attempt",
+    "turn": "turn",
+    "agent": "agent",
+    "toolCall": "tool_call",
+    "message": "message",
+    "wait": "wait",
+    "gate": "gate",
+    "resource": "resource",
+};
+export const WorkflowEdgeKindValues = {
+    "data": "data",
+    "control": "control",
+    "conflict": "conflict",
+    "resource": "resource",
+    "gate": "gate",
+    "temporal": "temporal",
+};
+export const WorkflowControlActionValues = {
+    "steer": "steer",
+    "interrupt": "interrupt",
+    "resume": "resume",
+};
+export const WorkflowControlStatusValues = {
+    "requested": "requested",
+    "accepted": "accepted",
+    "applied": "applied",
+    "rejected": "rejected",
+    "failed": "failed",
+};
+export const WorkflowAttemptStatusValues = {
+    "pending": "pending",
+    "running": "running",
+    "succeeded": "succeeded",
+    "failed": "failed",
+    "interrupted": "interrupted",
+};
+export const WorkflowAgentStatusValues = {
+    "pending": "pending",
+    "running": "running",
+    "waiting": "waiting",
+    "succeeded": "succeeded",
+    "failed": "failed",
+    "interrupted": "interrupted",
+};
+export const WorkflowToolCallStatusValues = {
+    "requested": "requested",
+    "running": "running",
+    "succeeded": "succeeded",
+    "failed": "failed",
+    "rejected": "rejected",
+};
 export const McpDataModeValues = {
     "live": "live",
     "demo": "demo",
 };
+export const CiPhaseStatusValues = {
+    "ok": "ok",
+    "error": "error",
+    "unset": "unset",
+};
 export const FetchTelemetryViewValues = {
     "traces": "traces",
     "trace": "trace",
     "logs": "logs",
     "mcpStats": "mcp_stats",
 };
+// --- contract revision (scripts/emit-contract-revision.mjs) ---
+/** Revision of the API contract these types were emitted from; compare against HealthReport.contract_revision. */
+export const CONTRACT_REVISION = "sha256:c4b86d761cbd7299";

package/index.tsp

@@ -21,9 +21,11 @@ import "./models/session.tsp";
 import "./models/health.tsp";
 import "./models/runner.tsp";
 import "./models/workbench.tsp";
+import "./models/workflow.tsp";
 import "./models/mcp-tools.tsp";
 
 import "./api/routes.tsp";
 import "./api/streaming.tsp";
 import "./api/runner.tsp";
 import "./api/workbench.tsp";
+import "./api/workflow.tsp";

package/models/health.tsp

@@ -1,3 +1,7 @@
+import "../common/types.tsp";
+
+using Qyl.Api.Contracts.Common;
+
 namespace Qyl.Api.Contracts.Health;
 
 @doc("Health state reported by a qyl-managed process.")
@@ -21,4 +25,12 @@ model HealthReport {
   @encodedName("application/json", "total_duration_ms")
   totalDurationMs: float64;
   entries: Record<HealthCheckEntry>;
+
+  // The meta surface of the contract loop: first-party clients compare this to
+  // the revision baked into their own generated artifacts and refuse to run on
+  // a mismatch, so a redeployed collector cannot silently serve a contract its
+  // clients were not generated from.
+  @doc("Revision of the API contract this process serves, for the client-side startup handshake.")
+  @encodedName("application/json", "contract_revision")
+  contractRevision: ContractRevision;
 }