@ancplua/qyl-api-schema 6.0.0 → 7.1.0

package/models/diagnostics.tsp

@@ -0,0 +1,204 @@
+import "./workflow.tsp";
+
+using Qyl.Api.Contracts.Workflow;
+
+namespace Qyl.Api.Contracts.Diagnostics;
+
+@doc("The versioned extension discriminator for a protected agent diagnostic snapshot.")
+enum AgentDiagnosticExtensionId {
+  snapshot: "qyl.agent.diagnostic.snapshot",
+}
+
+@doc("Wire-format version of an agent diagnostic snapshot. Version 1 is the only accepted format.")
+@minValue(1)
+@maxValue(1)
+scalar AgentDiagnosticFormatVersion extends int32;
+
+@doc("Stable machine identifier of one diagnostic snapshot. This identifier is a value and must never be promoted to a telemetry key.")
+@pattern("^[A-Za-z0-9_][A-Za-z0-9._:/\\[\\]-]{0,127}$")
+@minLength(1)
+@maxLength(128)
+scalar AgentDiagnosticSnapshotId extends string;
+
+@doc("Stable machine identifier of the probe that captured a diagnostic snapshot. This identifier is a value and must never be promoted to a telemetry key.")
+@pattern("^[A-Za-z0-9_][A-Za-z0-9._:/\\[\\]-]{0,127}$")
+@minLength(1)
+@maxLength(128)
+scalar AgentDiagnosticProbeId extends string;
+
+@doc("Stable machine identifier of one diagnostic check. This identifier is a value and must never be promoted to a telemetry key.")
+@pattern("^[A-Za-z0-9_][A-Za-z0-9._:/\\[\\]-]{0,127}$")
+@minLength(1)
+@maxLength(128)
+scalar AgentDiagnosticCheckId extends string;
+
+@doc("Stable machine name of one dynamically captured variable. Names are data values, never telemetry attribute keys, event names, or span names.")
+@pattern("^[A-Za-z0-9_][A-Za-z0-9._:/\\[\\]-]{0,127}$")
+@minLength(1)
+@maxLength(128)
+scalar AgentDiagnosticVariableName extends string;
+
+@doc("Execution boundary at which the state frame was captured.")
+enum AgentDiagnosticPhase {
+  input: "input",
+  output: "output",
+  error: "error",
+  checkpoint: "checkpoint",
+}
+
+@doc("Machine-computed aggregate result of a diagnostic snapshot. unknown reports one or more unknown check outcomes. not_evaluated is reserved for a snapshot whose checks array is empty.")
+enum AgentDiagnosticOutcome {
+  pass: "pass",
+  fail: "fail",
+  unknownResult: "unknown",
+  notEvaluated: "not_evaluated",
+}
+
+@doc("Machine-computed result of one diagnostic check. For exists, an absent or null actual variable produces fail. For every other operator, missing required operands produce unknown; incompatible operand types also produce unknown. not_evaluated is deliberately not a check outcome.")
+enum AgentDiagnosticCheckOutcome {
+  pass: "pass",
+  fail: "fail",
+  unknownResult: "unknown",
+}
+
+@doc("Declared JSON-level type of a diagnostic variable.")
+enum AgentDiagnosticValueType {
+  null: "null",
+  boolean: "boolean",
+  integer: "integer",
+  number: "number",
+  string: "string",
+  json: "json",
+}
+
+@doc("Data-handling classification assigned before a diagnostic variable is captured.")
+enum AgentDiagnosticClassification {
+  public: "public",
+  internal: "internal",
+  sensitive: "sensitive",
+  secret: "secret",
+}
+
+@doc("Closed operation evaluated by a diagnostic check. Checks are structural and never carry expression strings.")
+enum AgentDiagnosticOperator {
+  equal: "equal",
+  notEqual: "not_equal",
+  exists: "exists",
+  typeIs: "type_is",
+  contains: "contains",
+  lessThan: "less_than",
+  greaterThan: "greater_than",
+}
+
+@doc("Common identity and policy fields for one dynamic diagnostic variable.")
+model AgentDiagnosticVariableBase {
+  name: AgentDiagnosticVariableName;
+  type: AgentDiagnosticValueType;
+  classification: AgentDiagnosticClassification;
+}
+
+@doc("A variable whose typed JSON value is present in protected snapshot content. The value is required and must match type: null is JSON null; boolean is a JSON boolean; integer is a signed 64-bit JSON integer; number is a finite JSON number; string is a JSON string; json is a JSON object or array. The protected content boundary, not this model, controls access to all captured values.")
+model CapturedAgentDiagnosticVariable extends AgentDiagnosticVariableBase {
+  capture: "value";
+  value: unknown | null;
+}
+
+@doc("A variable observed by the probe whose value was replaced by policy. A value field is forbidden.")
+model RedactedAgentDiagnosticVariable extends AgentDiagnosticVariableBase {
+  capture: "redacted";
+}
+
+@doc("A variable whose value was unavailable or deliberately not captured. A value field is forbidden.")
+model OmittedAgentDiagnosticVariable extends AgentDiagnosticVariableBase {
+  capture: "omitted";
+}
+
+@doc("One dynamically named variable in a protected diagnostic snapshot. Capture is the discriminator and makes value presence unambiguous.")
+union AgentDiagnosticVariable {
+  value: CapturedAgentDiagnosticVariable,
+  redacted: RedactedAgentDiagnosticVariable,
+  omitted: OmittedAgentDiagnosticVariable,
+}
+
+@doc("One structural, machine-computed check result. actual and expected reference variable names only. For equal, not_equal, contains, less_than, and greater_than, expected is required and expected_type is omitted. For exists, both are omitted and an absent or null actual variable produces fail. For type_is, expected is omitted and expected_type is required. For operators other than exists, missing required operands produce unknown; incompatible operand types also produce unknown. not_evaluated is reserved for the snapshot aggregate when checks is empty and is not emitted for an individual check.")
+model AgentDiagnosticCheckResult {
+  @encodedName("application/json", "check_id")
+  checkId: AgentDiagnosticCheckId;
+
+  operator: AgentDiagnosticOperator;
+  actual: AgentDiagnosticVariableName;
+  expected?: AgentDiagnosticVariableName;
+
+  @encodedName("application/json", "expected_type")
+  expectedType?: AgentDiagnosticValueType;
+
+  outcome: AgentDiagnosticCheckOutcome;
+}
+
+@doc("Version 1 protected JSON state frame captured for an artificial-intelligence agent. extension_id and format_version are its schema identity. capture_nonce is fresh entropy and is not a stable identifier. Variables and checks are bounded, dynamic names remain values, and no human-oriented message or expression text is part of the contract. Overall outcome is not_evaluated only when checks is empty. For a non-empty checks array it is fail if any check fails, otherwise unknown if any check is unknown, otherwise pass.")
+model AgentDiagnosticSnapshot {
+  @encodedName("application/json", "extension_id")
+  extensionId: AgentDiagnosticExtensionId;
+
+  @encodedName("application/json", "format_version")
+  formatVersion: AgentDiagnosticFormatVersion;
+
+  @encodedName("application/json", "snapshot_id")
+  snapshotId: AgentDiagnosticSnapshotId;
+
+  @doc("Fresh 128-bit random nonce encoded as exactly 32 lowercase hexadecimal characters. It prevents equality inference across otherwise identical protected captures and must not be used as an identity key.")
+  @encodedName("application/json", "capture_nonce")
+  @pattern("^[0-9a-f]{32}$")
+  @minLength(32)
+  @maxLength(32)
+  captureNonce: string;
+
+  @encodedName("application/json", "probe_id")
+  probeId: AgentDiagnosticProbeId;
+
+  phase: AgentDiagnosticPhase;
+
+  @maxItems(64)
+  variables: AgentDiagnosticVariable[];
+
+  @maxItems(64)
+  checks: AgentDiagnosticCheckResult[];
+
+  outcome: AgentDiagnosticOutcome;
+}
+
+@doc("Value-free event-data projection for a protected agent diagnostic snapshot. Encode this shape in WorkflowEventAppend.data on the existing content_captured event kind. content_ref must also occur in that event's content_refs and identifies UTF-8 JSON conforming to AgentDiagnosticSnapshot. Counts are computed from the referenced snapshot; failed_check_count counts checks whose outcome is fail. No variable names, values, human messages, expressions, nonce, or classifications may appear in this summary.")
+model AgentDiagnosticSnapshotSummary {
+  @encodedName("application/json", "extension_id")
+  extensionId: AgentDiagnosticExtensionId;
+
+  @encodedName("application/json", "format_version")
+  formatVersion: AgentDiagnosticFormatVersion;
+
+  @encodedName("application/json", "snapshot_id")
+  snapshotId: AgentDiagnosticSnapshotId;
+
+  @encodedName("application/json", "probe_id")
+  probeId: AgentDiagnosticProbeId;
+
+  phase: AgentDiagnosticPhase;
+  outcome: AgentDiagnosticOutcome;
+
+  @encodedName("application/json", "variable_count")
+  @minValue(0)
+  @maxValue(64)
+  variableCount: int32;
+
+  @encodedName("application/json", "check_count")
+  @minValue(0)
+  @maxValue(64)
+  checkCount: int32;
+
+  @encodedName("application/json", "failed_check_count")
+  @minValue(0)
+  @maxValue(64)
+  failedCheckCount: int32;
+
+  @encodedName("application/json", "content_ref")
+  contentRef: WorkflowContentRef;
+}

package/models/mcp-tools.tsp

@@ -1,10 +1,12 @@
 import "../common/types.tsp";
 import "../otel/logs.tsp";
 import "../otel/span.tsp";
+import "./diagnostics.tsp";
 import "./session.tsp";
 import "./workflow.tsp";
 
 using Qyl.Api.Contracts.Common;
+using Qyl.Api.Contracts.Diagnostics;
 using Qyl.Api.Contracts.Domains.Observe.Session;
 using Qyl.Api.Contracts.OTel.Logs;
 using Qyl.Api.Contracts.OTel.Traces;
@@ -218,11 +220,82 @@ model FetchTelemetryOutput {
   mode: McpDataMode;
 }
 
+@doc("Input for get_active_workflow_run.")
+model GetActiveWorkflowRunInput {}
+
+@doc("Structured output for get_active_workflow_run.")
+model GetActiveWorkflowRunOutput {
+  active: boolean;
+
+  @encodedName("application/json", "live_controls_available")
+  liveControlsAvailable: boolean;
+
+  @encodedName("application/json", "run_id")
+  runId?: WorkflowRunId;
+
+  @encodedName("application/json", "thread_id")
+  threadId?: string;
+
+  @encodedName("application/json", "started_at")
+  startedAt?: utcDateTime;
+}
+
+@doc("One dynamically named JSON value submitted for protected diagnostic capture. Classification is applied before the frame leaves the observer bridge.")
+model RecordDiagnosticSnapshotVariableInput {
+  name: AgentDiagnosticVariableName;
+  classification: AgentDiagnosticClassification;
+  value: unknown | null;
+}
+
+@doc("One structural diagnostic check submitted for evaluation. equal, not_equal, contains, less_than, and greater_than require expected and forbid expected_type; type_is requires expected_type and forbids expected; exists forbids both.")
+model RecordDiagnosticSnapshotCheckInput {
+  @encodedName("application/json", "check_id")
+  checkId: AgentDiagnosticCheckId;
+
+  operator: AgentDiagnosticOperator;
+  actual: AgentDiagnosticVariableName;
+  expected?: AgentDiagnosticVariableName;
+
+  @encodedName("application/json", "expected_type")
+  expectedType?: AgentDiagnosticValueType;
+}
+
+@doc("Input for record_diagnostic_snapshot. Reuse the same snapshot_id and semantic payload when retrying; changing the payload under an existing snapshot_id is a conflict.")
+model RecordDiagnosticSnapshotInput {
+  @encodedName("application/json", "snapshot_id")
+  snapshotId: AgentDiagnosticSnapshotId;
+
+  @encodedName("application/json", "probe_id")
+  probeId: AgentDiagnosticProbeId;
+
+  phase: AgentDiagnosticPhase;
+
+  @maxItems(64)
+  variables: RecordDiagnosticSnapshotVariableInput[];
+
+  @maxItems(64)
+  checks?: RecordDiagnosticSnapshotCheckInput[] = #[];
+}
+
+@doc("Structured output for record_diagnostic_snapshot.")
+model RecordDiagnosticSnapshotOutput {
+  recorded: boolean;
+  code: string;
+
+  @encodedName("application/json", "snapshot_id")
+  snapshotId: AgentDiagnosticSnapshotId;
+
+  @encodedName("application/json", "event_id")
+  eventId?: WorkflowEventId;
+
+  field?: string;
+}
+
 @doc("Input for list_workflow_runs.")
 model ListWorkflowRunsInput {
   status?: WorkflowRunStatus;
 
-  cursor?: string;
+  cursor?: WorkflowRunCursor;
 
   @minValue(1)
   @maxValue(100)
@@ -234,7 +307,7 @@ model ListWorkflowRunsOutput {
   runs: WorkflowRun[];
 
   @encodedName("application/json", "next_cursor")
-  nextCursor?: string;
+  nextCursor?: WorkflowRunCursor;
 
   @encodedName("application/json", "has_more")
   hasMore: boolean;
@@ -247,16 +320,18 @@ model GetWorkflowGraphInput {
   @encodedName("application/json", "run_id")
   runId: WorkflowRunId;
 
+  @doc("Opaque node continuation. Reuse it unchanged from the preceding snapshot's next_node_cursor; do not parse, construct, or modify it.")
   @encodedName("application/json", "node_cursor")
-  nodeCursor?: string;
+  nodeCursor?: WorkflowNodeCursor;
 
   @encodedName("application/json", "node_limit")
   @minValue(1)
   @maxValue(1000)
   nodeLimit?: int32 = 250;
 
+  @doc("Opaque edge continuation. Reuse it unchanged from the preceding snapshot's next_edge_cursor; do not parse, construct, or modify it.")
   @encodedName("application/json", "edge_cursor")
-  edgeCursor?: string;
+  edgeCursor?: WorkflowEdgeCursor;
 
   @encodedName("application/json", "edge_limit")
   @minValue(1)
@@ -275,16 +350,18 @@ model DisplayWorkflowGraphInput {
   @encodedName("application/json", "run_id")
   runId?: WorkflowRunId;
 
+  @doc("Opaque node continuation. Reuse it unchanged from the preceding snapshot's next_node_cursor; do not parse, construct, or modify it.")
   @encodedName("application/json", "node_cursor")
-  nodeCursor?: string;
+  nodeCursor?: WorkflowNodeCursor;
 
   @encodedName("application/json", "node_limit")
   @minValue(1)
   @maxValue(1000)
   nodeLimit?: int32 = 250;
 
+  @doc("Opaque edge continuation. Reuse it unchanged from the preceding snapshot's next_edge_cursor; do not parse, construct, or modify it.")
   @encodedName("application/json", "edge_cursor")
-  edgeCursor?: string;
+  edgeCursor?: WorkflowEdgeCursor;
 
   @encodedName("application/json", "edge_limit")
   @minValue(1)
@@ -308,7 +385,7 @@ model FetchWorkflowGraphUpdatesInput {
   runId: WorkflowRunId;
 
   @encodedName("application/json", "after_sequence")
-  afterSequence: WorkflowSequence;
+  afterSequence: WorkflowJournalPosition;
 
   @minValue(1)
   @maxValue(1000)
@@ -319,16 +396,18 @@ model FetchWorkflowGraphUpdatesInput {
   @maxValue(30000)
   waitMs?: int32 = 20000;
 
+  @doc("Opaque node continuation. Reuse it unchanged from the preceding snapshot's next_node_cursor; do not parse, construct, or modify it.")
   @encodedName("application/json", "node_cursor")
-  nodeCursor?: string;
+  nodeCursor?: WorkflowNodeCursor;
 
   @encodedName("application/json", "node_limit")
   @minValue(1)
   @maxValue(1000)
   nodeLimit?: int32 = 250;
 
+  @doc("Opaque edge continuation. Reuse it unchanged from the preceding snapshot's next_edge_cursor; do not parse, construct, or modify it.")
   @encodedName("application/json", "edge_cursor")
-  edgeCursor?: string;
+  edgeCursor?: WorkflowEdgeCursor;
 
   @encodedName("application/json", "edge_limit")
   @minValue(1)
@@ -348,6 +427,30 @@ model FetchWorkflowGraphUpdatesOutput {
   mode: McpDataMode;
 }
 
+@doc("Input for inspect_workflow_events.")
+model InspectWorkflowEventsInput {
+  @encodedName("application/json", "run_id")
+  runId: WorkflowRunId;
+
+  @encodedName("application/json", "after_sequence")
+  afterSequence: WorkflowJournalPosition;
+
+  @minValue(1)
+  @maxValue(1000)
+  limit?: int32 = 250;
+
+  @doc("Optional captured payload to retrieve lazily for the selected run.")
+  @encodedName("application/json", "content_ref")
+  contentRef?: WorkflowContentRef;
+}
+
+@doc("Structured output for inspect_workflow_events.")
+model InspectWorkflowEventsOutput {
+  page: WorkflowEventPage;
+  content?: WorkflowContent;
+  mode: McpDataMode;
+}
+
 @doc("Input for control_workflow_run.")
 model ControlWorkflowRunInput {
   @encodedName("application/json", "run_id")

package/models/workflow.tsp

@@ -9,6 +9,17 @@ namespace Qyl.Api.Contracts.Workflow;
 @maxLength(128)
 scalar WorkflowRunId extends string;
 
+@doc("Opaque incarnation identifier for one workflow run's projected state.")
+@pattern("^[0-9a-f]{12}4[0-9a-f]{3}[89ab][0-9a-f]{15}$")
+@minLength(32)
+@maxLength(32)
+scalar WorkflowGeneration extends string;
+
+@doc("Opaque workflow-run list continuation scoped to the project and status filter. Reuse it unchanged; clients must not parse or construct it.")
+@minLength(1)
+@maxLength(512)
+scalar WorkflowRunCursor extends string;
+
 @doc("Stable identifier of one workflow attempt.")
 @minLength(1)
 @maxLength(128)
@@ -34,11 +45,26 @@ scalar WorkflowEventId extends string;
 @maxLength(128)
 scalar WorkflowCommandId extends string;
 
-@doc("Stable identifier of one graph node.")
+@doc("Stable identifier of one graph node. Canonical tuples structurally distinguish run scope from attempt scope, escape colon as \\c and backslash as \\\\, and never infer scope from a literal component value. A canonical identifier over 192 Unicode scalar values is replaced by its kind, a tilde, and the full lowercase 64-hex SHA-256 of the length-prefixed canonical tuple.")
 @minLength(1)
 @maxLength(192)
 scalar WorkflowNodeId extends string;
 
+@doc("Stable identifier of one graph edge. Endpoint tuples preserve the nodes' structural run-versus-attempt scope and ordinal component boundaries, escape colon as \\c and backslash as \\\\, and never infer scope from a literal component value. A canonical identifier over 192 Unicode scalar values is replaced by its edge kind, a tilde, and the full lowercase 64-hex SHA-256 of the length-prefixed canonical tuple.")
+@minLength(1)
+@maxLength(192)
+scalar WorkflowEdgeId extends string;
+
+@doc("Opaque node-page continuation scoped to one workflow run and generation. Reuse it unchanged; clients must not parse or construct it.")
+@minLength(1)
+@maxLength(1536)
+scalar WorkflowNodeCursor extends string;
+
+@doc("Opaque edge-page continuation scoped to one workflow run and generation. Reuse it unchanged; clients must not parse or construct it.")
+@minLength(1)
+@maxLength(1536)
+scalar WorkflowEdgeCursor extends string;
+
 @doc("Content-addressed reference to a captured workflow payload.")
 @pattern("^sha256:[a-f0-9]{64}$")
 @minLength(71)
@@ -50,6 +76,11 @@ scalar WorkflowContentRef extends string;
 @encode(string)
 scalar WorkflowSequence extends uint64;
 
+@doc("Collector-assigned position in the authoritative workflow journal, encoded without JavaScript precision loss.")
+@minValue(0)
+@encode(string)
+scalar WorkflowJournalPosition extends uint64;
+
 @doc("Current lifecycle of a workflow run.")
 enum WorkflowRunStatus {
   active: "active",
@@ -165,11 +196,60 @@ enum WorkflowContentEncoding {
   base64: "base64",
 }
 
+@doc("A valid committed projection that can be served to readers.")
+model CommittedWorkflowProjectionStatus {
+  state: "committed";
+  generation: WorkflowGeneration;
+
+  @encodedName("application/json", "journal_position")
+  journalPosition: WorkflowJournalPosition;
+}
+
+@doc("The requested generation is being reconstructed from its authoritative journal.")
+model RebuildingWorkflowProjectionStatus {
+  state: "rebuilding";
+  generation: WorkflowGeneration;
+
+  @encodedName("application/json", "target_journal_position")
+  targetJournalPosition: WorkflowJournalPosition;
+
+  @encodedName("application/json", "retry_after_ms")
+  @minValue(1)
+  retryAfterMs: int32;
+}
+
+@doc("Projection work is temporarily unavailable after a retryable storage failure.")
+model UnavailableWorkflowProjectionStatus {
+  state: "unavailable";
+  generation?: WorkflowGeneration;
+
+  @encodedName("application/json", "retry_after_ms")
+  @minValue(1)
+  retryAfterMs: int32;
+}
+
+@doc("Derived projection state is corrupt or incompatible and cannot currently be served.")
+model CorruptWorkflowProjectionStatus {
+  state: "corrupt";
+  generation?: WorkflowGeneration;
+  reason: "corrupt_derived_state" | "incompatible_derived_state";
+}
+
+@doc("Closed public availability state for one workflow projection. Storage paths, hashes, fingerprints, and database errors remain private.")
+union WorkflowProjectionStatus {
+  committed: CommittedWorkflowProjectionStatus,
+  rebuilding: RebuildingWorkflowProjectionStatus,
+  unavailable: UnavailableWorkflowProjectionStatus,
+  corrupt: CorruptWorkflowProjectionStatus,
+}
+
 @doc("One immutable workflow run.")
 model WorkflowRun {
   @encodedName("application/json", "run_id")
   runId: WorkflowRunId;
 
+  generation: WorkflowGeneration;
+
   @encodedName("application/json", "thread_id")
   threadId?: string;
 
@@ -183,7 +263,7 @@ model WorkflowRun {
   endedAt?: utcDateTime;
 
   @encodedName("application/json", "latest_journal_sequence")
-  latestJournalSequence: WorkflowSequence;
+  latestJournalSequence: WorkflowJournalPosition;
 
   @encodedName("application/json", "active_attempt_id")
   activeAttemptId?: WorkflowAttemptId;
@@ -212,7 +292,7 @@ model WorkflowRunPage {
   items: WorkflowRun[];
 
   @encodedName("application/json", "next_cursor")
-  nextCursor?: string;
+  nextCursor?: WorkflowRunCursor;
 
   @encodedName("application/json", "has_more")
   hasMore: boolean;
@@ -301,10 +381,10 @@ model WorkflowEventBatchAppendResponse {
   acknowledgedSourceSequence: WorkflowSequence;
 
   @encodedName("application/json", "first_journal_sequence")
-  firstJournalSequence?: WorkflowSequence;
+  firstJournalSequence?: WorkflowJournalPosition;
 
   @encodedName("application/json", "last_journal_sequence")
-  lastJournalSequence?: WorkflowSequence;
+  lastJournalSequence?: WorkflowJournalPosition;
 }
 
 @doc("One immutable event after collector journal sequence assignment.")
@@ -316,7 +396,7 @@ model WorkflowJournalEvent extends WorkflowEventAppend {
   clientId: string;
 
   @encodedName("application/json", "journal_sequence")
-  journalSequence: WorkflowSequence;
+  journalSequence: WorkflowJournalPosition;
 }
 
 @doc("A bounded page of workflow journal events.")
@@ -324,10 +404,10 @@ model WorkflowEventPage {
   events: WorkflowJournalEvent[];
 
   @encodedName("application/json", "next_sequence")
-  nextSequence: WorkflowSequence;
+  nextSequence: WorkflowJournalPosition;
 
   @encodedName("application/json", "high_water_mark")
-  highWaterMark: WorkflowSequence;
+  highWaterMark: WorkflowJournalPosition;
 
   @encodedName("application/json", "cursor_gap")
   cursorGap: boolean;
@@ -390,10 +470,10 @@ model WorkflowGraphNode {
   attributes?: Record<unknown>;
 }
 
-@doc("One typed edge in the deterministic workflow graph projection.")
+@doc("One typed edge in the deterministic workflow graph projection. Data, Control, and Gate edges are causal dependencies. Temporal edges describe observed order, Resource edges describe resource use, and Conflict edges describe contention; Temporal, Resource, and Conflict edges are excluded from critical-path causality.")
 model WorkflowGraphEdge {
   @encodedName("application/json", "edge_id")
-  edgeId: string;
+  edgeId: WorkflowEdgeId;
 
   @encodedName("application/json", "source_node_id")
   sourceNodeId: WorkflowNodeId;
@@ -405,7 +485,7 @@ model WorkflowGraphEdge {
   provenance: WorkflowEdgeProvenance;
 }
 
-@doc("Work and critical-path statistics for a workflow graph.")
+@doc("Work and critical-path statistics for a workflow graph. Every ToolCall, Wait, Gate, and duration-bearing Message or Item contributes an independently weighted interval even when it has no Agent owner. An Agent contributes its own-work fragments: its interval minus the union of precisely owned child intervals clipped to the Agent interval. Precisely owned children are Control-linked Agent and ToolCall nodes, Temporal-linked Wait nodes, Gate-linked Gate nodes, and Data-linked duration-bearing Message or Item nodes. Peak concurrency sweeps every positive independently weighted or Agent own-work fragment. Critical-path analysis uses only Data, Control, and Gate edges, condenses each causal strongly connected component, charges every component member exactly once, and expands selected component members in ordinal node-id order.")
 model WorkflowGraphStatistics {
   @encodedName("application/json", "t1_ms")
   t1Ms: DurationMs;
@@ -434,18 +514,23 @@ model WorkflowGraphStatistics {
 @doc("Deterministic graph projection at one journal cursor.")
 model WorkflowGraphSnapshot {
   run: WorkflowRun;
+
+  @encodedName("application/json", "projection_status")
+  projectionStatus: WorkflowProjectionStatus;
   nodes: WorkflowGraphNode[];
   edges: WorkflowGraphEdge[];
   statistics: WorkflowGraphStatistics;
 
   @encodedName("application/json", "journal_sequence")
-  journalSequence: WorkflowSequence;
+  journalSequence: WorkflowJournalPosition;
 
   @encodedName("application/json", "next_node_cursor")
-  nextNodeCursor?: string;
+  @doc("Opaque node continuation for the next page. Reuse it unchanged as node_cursor on the next graph request; do not parse, construct, or modify it.")
+  nextNodeCursor?: WorkflowNodeCursor;
 
   @encodedName("application/json", "next_edge_cursor")
-  nextEdgeCursor?: string;
+  @doc("Opaque edge continuation for the next page. Reuse it unchanged as edge_cursor on the next graph request; do not parse, construct, or modify it.")
+  nextEdgeCursor?: WorkflowEdgeCursor;
 
   @encodedName("application/json", "has_more_nodes")
   hasMoreNodes: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancplua/qyl-api-schema",
-  "version": "6.0.0",
+  "version": "7.1.0",
   "description": "TypeSpec source of truth for qyl API contracts. Emits OpenAPI, JSON Schema, Qyl.Api.Contracts DTOs, and TypeScript contract types; not an OpenTelemetry package, storage schema, or server implementation.",
   "license": "Apache-2.0",
   "repository": {
@@ -62,6 +62,7 @@
     "models/runner.tsp",
     "models/workbench.tsp",
     "models/workflow.tsp",
+    "models/diagnostics.tsp",
     "models/mcp-tools.tsp",
     "models/session.tsp",
     "otel/enums.tsp",
@@ -87,10 +88,11 @@
     "build:emitters": "tsc -p emitters/csharp && tsc -p emitters/ts-types && tsc -p emitters/qyl-lint",
     "build:ts-runtime": "tsc -p tsconfig.contracts.json",
     "build:json-schema": "node scripts/openapi-to-json-schema.mjs",
+    "emit:mcp-tool-schemas": "node scripts/emit-mcp-tool-schemas.mjs",
     "emit:contract-revision": "node scripts/emit-contract-revision.mjs",
     "prepare": "npm run build:emitters",
     "prepack": "npm run compile",
-    "compile": "npm run clean:generated && npm run build:emitters && tsp compile main.tsp && npm run emit:contract-revision && npm run build:json-schema && npm run build:ts-runtime",
+    "compile": "npm run clean:generated && npm run build:emitters && tsp compile main.tsp && npm run emit:contract-revision && npm run build:json-schema && npm run emit:mcp-tool-schemas && npm run build:ts-runtime",
     "format": "tsp format **/*.tsp",
     "lint": "npm run build:emitters && tsp compile main.tsp --no-emit --warn-as-error",
     "lint:public": "npm run build:emitters && tsp compile index.tsp --no-emit --warn-as-error",
@@ -100,11 +102,11 @@
   },
   "peerDependencies": {
     "@typespec/compiler": "^1.13.0 || >=1.13.0-dev.0",
-    "@typespec/events": "^0.83.0 || ^0.84.0",
+    "@typespec/events": "^0.83.0 || ^0.84.0 || ^0.85.0",
     "@typespec/http": "^1.13.0",
     "@typespec/openapi": "^1.13.0",
     "@typespec/openapi3": "^1.13.0",
-    "@typespec/sse": ">=0.83.0 <0.85.0"
+    "@typespec/sse": ">=0.83.0 <0.86.0"
   },
   "peerDependenciesMeta": {
     "@typespec/compiler": {