@ancplua/qyl-api-schema 4.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,6 +375,111 @@ 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";
@@ -380,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";
@@ -1224,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;
@@ -1353,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;

package/generated/ts-runtime/api.js

@@ -280,6 +280,101 @@ 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",
@@ -297,4 +392,4 @@ export const FetchTelemetryViewValues = {
 };
 // --- 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:9ba787d0bd3269a9";
+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/mcp-tools.tsp

@@ -2,11 +2,13 @@ import "../common/types.tsp";
 import "../otel/logs.tsp";
 import "../otel/span.tsp";
 import "./session.tsp";
+import "./workflow.tsp";
 
 using Qyl.Api.Contracts.Common;
 using Qyl.Api.Contracts.Domains.Observe.Session;
 using Qyl.Api.Contracts.OTel.Logs;
 using Qyl.Api.Contracts.OTel.Traces;
+using Qyl.Api.Contracts.Workflow;
 
 namespace Qyl.Api.Contracts.Mcp.Tools;
 
@@ -216,6 +218,157 @@ model FetchTelemetryOutput {
   mode: McpDataMode;
 }
 
+@doc("Input for list_workflow_runs.")
+model ListWorkflowRunsInput {
+  status?: WorkflowRunStatus;
+
+  cursor?: string;
+
+  @minValue(1)
+  @maxValue(100)
+  limit?: int32 = 20;
+}
+
+@doc("Structured output for list_workflow_runs.")
+model ListWorkflowRunsOutput {
+  runs: WorkflowRun[];
+
+  @encodedName("application/json", "next_cursor")
+  nextCursor?: string;
+
+  @encodedName("application/json", "has_more")
+  hasMore: boolean;
+
+  mode: McpDataMode;
+}
+
+@doc("Input for get_workflow_graph.")
+model GetWorkflowGraphInput {
+  @encodedName("application/json", "run_id")
+  runId: WorkflowRunId;
+
+  @encodedName("application/json", "node_cursor")
+  nodeCursor?: string;
+
+  @encodedName("application/json", "node_limit")
+  @minValue(1)
+  @maxValue(1000)
+  nodeLimit?: int32 = 250;
+
+  @encodedName("application/json", "edge_cursor")
+  edgeCursor?: string;
+
+  @encodedName("application/json", "edge_limit")
+  @minValue(1)
+  @maxValue(2000)
+  edgeLimit?: int32 = 500;
+}
+
+@doc("Structured output for get_workflow_graph.")
+model GetWorkflowGraphOutput {
+  graph: WorkflowGraphSnapshot;
+  mode: McpDataMode;
+}
+
+@doc("Input for display_workflow_graph. Omit run_id to select the most recent run.")
+model DisplayWorkflowGraphInput {
+  @encodedName("application/json", "run_id")
+  runId?: WorkflowRunId;
+
+  @encodedName("application/json", "node_cursor")
+  nodeCursor?: string;
+
+  @encodedName("application/json", "node_limit")
+  @minValue(1)
+  @maxValue(1000)
+  nodeLimit?: int32 = 250;
+
+  @encodedName("application/json", "edge_cursor")
+  edgeCursor?: string;
+
+  @encodedName("application/json", "edge_limit")
+  @minValue(1)
+  @maxValue(2000)
+  edgeLimit?: int32 = 500;
+}
+
+@doc("Structured output for display_workflow_graph.")
+model DisplayWorkflowGraphOutput {
+  graph: WorkflowGraphSnapshot;
+
+  @encodedName("application/json", "live_controls_available")
+  liveControlsAvailable: boolean;
+
+  mode: McpDataMode;
+}
+
+@doc("Input for the app-only fetch_workflow_graph_updates tool.")
+model FetchWorkflowGraphUpdatesInput {
+  @encodedName("application/json", "run_id")
+  runId: WorkflowRunId;
+
+  @encodedName("application/json", "after_sequence")
+  afterSequence: WorkflowSequence;
+
+  @minValue(1)
+  @maxValue(1000)
+  limit?: int32 = 250;
+
+  @encodedName("application/json", "wait_ms")
+  @minValue(0)
+  @maxValue(30000)
+  waitMs?: int32 = 20000;
+
+  @encodedName("application/json", "node_cursor")
+  nodeCursor?: string;
+
+  @encodedName("application/json", "node_limit")
+  @minValue(1)
+  @maxValue(1000)
+  nodeLimit?: int32 = 250;
+
+  @encodedName("application/json", "edge_cursor")
+  edgeCursor?: string;
+
+  @encodedName("application/json", "edge_limit")
+  @minValue(1)
+  @maxValue(2000)
+  edgeLimit?: int32 = 500;
+
+  @doc("Optional captured payload to retrieve lazily for the selected run.")
+  @encodedName("application/json", "content_ref")
+  contentRef?: WorkflowContentRef;
+}
+
+@doc("Structured output for the app-only fetch_workflow_graph_updates tool.")
+model FetchWorkflowGraphUpdatesOutput {
+  page: WorkflowEventPage;
+  graph?: WorkflowGraphSnapshot;
+  content?: WorkflowContent;
+  mode: McpDataMode;
+}
+
+@doc("Input for control_workflow_run.")
+model ControlWorkflowRunInput {
+  @encodedName("application/json", "run_id")
+  runId: WorkflowRunId;
+
+  action: WorkflowControlAction;
+
+  @encodedName("application/json", "idempotency_key")
+  @minLength(1)
+  @maxLength(160)
+  idempotencyKey: string;
+
+  @maxLength(32768)
+  input?: string;
+}
+
+@doc("Structured output for control_workflow_run.")
+model ControlWorkflowRunOutput {
+  command: WorkflowControlCommand;
+}
+
 @doc("Aggregate MCP traffic statistics shown by qyl.mcp.")
 model McpDashboardStats {
   window: McpDashboardWindow;