@ancplua/qyl-api-schema 7.4.0 → 9.0.0

package/api/workflow.tsp

@@ -1,307 +0,0 @@
-import "@typespec/events";
-import "@typespec/http";
-import "@typespec/sse";
-
-import "../common/errors.tsp";
-import "../models/workflow.tsp";
-import "./routes.tsp";
-
-using TypeSpec.Events;
-using TypeSpec.Http;
-using TypeSpec.SSE;
-
-using Qyl.Api.Contracts.Common.Errors;
-using Qyl.Api.Contracts.Workflow;
-
-namespace Qyl.Api.Contracts.Workflow;
-
-@doc("Keep-alive emitted while a workflow event stream has no new event.")
-model WorkflowHeartbeatEvent {
-  type: "heartbeat";
-
-  @encodedName("application/json", "high_water_mark")
-  highWaterMark: WorkflowJournalPosition;
-
-  timestamp: utcDateTime;
-}
-
-@doc("Signals that the requested cursor predates retained workflow history.")
-model WorkflowCursorGapEvent {
-  type: "cursor_gap";
-
-  @encodedName("application/json", "oldest_available_sequence")
-  oldestAvailableSequence: WorkflowJournalPosition;
-
-  @encodedName("application/json", "high_water_mark")
-  highWaterMark: WorkflowJournalPosition;
-
-  timestamp: utcDateTime;
-}
-
-@events
-union WorkflowStreamEvents {
-  event: WorkflowJournalEvent,
-  heartbeat: WorkflowHeartbeatEvent,
-  cursorGap: WorkflowCursorGapEvent,
-}
-
-@doc("Which opaque graph cursor was rejected.")
-enum WorkflowCursorKind {
-  node: "node",
-  edge: "edge",
-}
-
-@doc("Why an opaque graph cursor cannot be reused for this request.")
-enum WorkflowCursorFailureReason {
-  invalid: "invalid",
-  wrongRun: "wrong_run",
-  wrongGeneration: "wrong_generation",
-  stale: "stale",
-}
-
-@doc("Opaque graph cursor is malformed, belongs to another run, or targets a stale generation.")
-@error
-model WorkflowCursorError extends ProblemDetails {
-  @statusCode _: 409;
-  title: "Invalid Workflow Cursor";
-
-  @encodedName("application/json", "cursor_kind")
-  cursorKind: WorkflowCursorKind;
-
-  reason: WorkflowCursorFailureReason;
-
-  @encodedName("application/json", "current_generation")
-  currentGeneration?: WorkflowGeneration;
-}
-
-@doc("Workflow run was durably deleted and can no longer accept events or publish projections.")
-@error
-model WorkflowRunDeletedError extends ProblemDetails {
-  @statusCode _: 410;
-  title: "Workflow Run Deleted";
-
-  @encodedName("application/json", "run_id")
-  runId: WorkflowRunId;
-}
-
-@doc("Workflow projection is rebuilding or temporarily unavailable after a retryable storage failure.")
-@error
-model WorkflowProjectionUnavailableError extends ProblemDetails {
-  @statusCode _: 503;
-  title: "Workflow Projection Unavailable";
-
-  @header("Retry-After")
-  @encodedName("application/json", "retry_after")
-  retryAfter: int32;
-
-  @encodedName("application/json", "projection_status")
-  projectionStatus: WorkflowProjectionStatus;
-}
-
-@doc("Workflow projection is non-retryably corrupt or incompatible. Internal storage details are intentionally omitted.")
-@error
-model WorkflowProjectionCorruptError extends ProblemDetails {
-  @statusCode _: 500;
-  title: "Workflow Projection Corrupt";
-  @encodedName("application/json", "projection_status")
-  projectionStatus: WorkflowProjectionStatus;
-}
-
-@route("/api/v1/workflow-runs")
-@tag("Workflow runs")
-@useAuth(Qyl.Api.Contracts.QylApiKeyHeaderAuth)
-interface WorkflowRunsApi {
-  @post
-  create(
-    ...Qyl.Api.Contracts.ProjectScopeHeader,
-    @body request: WorkflowRunCreateRequest,
-  ):
-    | WorkflowRun
-    | ValidationError
-    | UnauthorizedError
-    | ConflictError
-    | WorkflowRunDeletedError
-    | ServiceUnavailableError
-    | InternalServerError;
-
-  @get
-  list(
-    ...Qyl.Api.Contracts.ProjectScopeHeader,
-    @query status?: WorkflowRunStatus,
-    @query
-    @minValue(1)
-    @maxValue(200)
-    limit?: int32 = 50,
-    @doc("Opaque continuation scoped to the project and status filter. Reuse it unchanged from next_cursor; do not parse, construct, or modify it.")
-    @query cursor?: WorkflowRunCursor,
-  ):
-    | WorkflowRunPage
-    | ValidationError
-    | UnauthorizedError
-    | ServiceUnavailableError
-    | InternalServerError;
-
-  @get
-  @route("/{run_id}")
-  get(
-    ...Qyl.Api.Contracts.ProjectScopeHeader,
-    @path("run_id") runId: WorkflowRunId,
-  ):
-    | WorkflowRun
-    | UnauthorizedError
-    | NotFoundError
-    | WorkflowRunDeletedError
-    | ServiceUnavailableError
-    | InternalServerError;
-
-  @post
-  @route("/{run_id}/events")
-  appendEvents(
-    ...Qyl.Api.Contracts.ProjectScopeHeader,
-    @path("run_id") runId: WorkflowRunId,
-    @body request: WorkflowEventBatchAppendRequest,
-  ):
-    | WorkflowEventBatchAppendResponse
-    | ValidationError
-    | UnauthorizedError
-    | NotFoundError
-    | WorkflowRunDeletedError
-    | ConflictError
-    | ServiceUnavailableError
-    | InternalServerError;
-
-  @get
-  @route("/{run_id}/events")
-  readEvents(
-    ...Qyl.Api.Contracts.ProjectScopeHeader,
-    @path("run_id") runId: WorkflowRunId,
-    @query("after_sequence") afterSequence?: WorkflowJournalPosition,
-    @query
-    @minValue(1)
-    @maxValue(1000)
-    limit?: int32 = 250,
-    @query("wait_ms")
-    @minValue(0)
-    @maxValue(30000)
-    waitMs?: int32 = 0,
-  ):
-    | WorkflowEventPage
-    | ValidationError
-    | UnauthorizedError
-    | NotFoundError
-    | WorkflowRunDeletedError
-    | ServiceUnavailableError
-    | InternalServerError;
-
-  @get
-  @route("/{run_id}/graph")
-  getGraph(
-    ...Qyl.Api.Contracts.ProjectScopeHeader,
-    @path("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.")
-    @query("node_cursor") nodeCursor?: WorkflowNodeCursor,
-    @query("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.")
-    @query("edge_cursor") edgeCursor?: WorkflowEdgeCursor,
-    @query("edge_limit")
-    @minValue(1)
-    @maxValue(2000)
-    edgeLimit?: int32 = 500,
-  ):
-    | WorkflowGraphSnapshot
-    | ValidationError
-    | UnauthorizedError
-    | NotFoundError
-    | WorkflowRunDeletedError
-    | WorkflowCursorError
-    | WorkflowProjectionUnavailableError
-    | WorkflowProjectionCorruptError;
-
-  @get
-  @route("/{run_id}/content/{content_ref}")
-  getContent(
-    ...Qyl.Api.Contracts.ProjectScopeHeader,
-    @path("run_id") runId: WorkflowRunId,
-    @path("content_ref") contentRef: WorkflowContentRef,
-  ):
-    | WorkflowContent
-    | UnauthorizedError
-    | NotFoundError
-    | WorkflowRunDeletedError
-    | ServiceUnavailableError
-    | InternalServerError;
-
-  @get
-  @route("/{run_id}/stream")
-  stream(
-    ...Qyl.Api.Contracts.ProjectScopeHeader,
-    @path("run_id") runId: WorkflowRunId,
-    @header("Last-Event-ID") lastEventId?: string,
-  ):
-    | SSEStream<WorkflowStreamEvents>
-    | ValidationError
-    | UnauthorizedError
-    | NotFoundError
-    | WorkflowRunDeletedError
-    | ServiceUnavailableError
-    | InternalServerError;
-
-  @post
-  @route("/{run_id}/commands")
-  submitControl(
-    ...Qyl.Api.Contracts.ProjectScopeHeader,
-    @path("run_id") runId: WorkflowRunId,
-    @body request: WorkflowControlRequest,
-  ):
-    | WorkflowControlCommand
-    | ValidationError
-    | UnauthorizedError
-    | NotFoundError
-    | WorkflowRunDeletedError
-    | ConflictError
-    | ServiceUnavailableError
-    | InternalServerError;
-
-  @get
-  @route("/{run_id}/commands")
-  pollControls(
-    ...Qyl.Api.Contracts.ProjectScopeHeader,
-    @path("run_id") runId: WorkflowRunId,
-    @query("after_sequence") afterSequence?: WorkflowSequence,
-    @query
-    @minValue(1)
-    @maxValue(100)
-    limit?: int32 = 20,
-    @query("wait_ms")
-    @minValue(0)
-    @maxValue(30000)
-    waitMs?: int32 = 0,
-  ):
-    | WorkflowControlCommandPage
-    | ValidationError
-    | UnauthorizedError
-    | NotFoundError
-    | WorkflowRunDeletedError
-    | ServiceUnavailableError
-    | InternalServerError;
-
-  @post
-  @route("/{run_id}/commands/{command_id}/status")
-  updateControl(
-    ...Qyl.Api.Contracts.ProjectScopeHeader,
-    @path("run_id") runId: WorkflowRunId,
-    @path("command_id") commandId: WorkflowCommandId,
-    @body request: WorkflowControlStatusUpdateRequest,
-  ):
-    | WorkflowControlCommand
-    | ValidationError
-    | UnauthorizedError
-    | NotFoundError
-    | WorkflowRunDeletedError
-    | ConflictError
-    | ServiceUnavailableError
-    | InternalServerError;
-}

package/models/diagnostics.tsp

@@ -1,204 +0,0 @@
-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;
-}