@ancplua/qyl-api-schema 0.4.0 → 0.5.1

package/generated/ts-runtime/api.js

@@ -0,0 +1,237 @@
+// <auto-generated/>
+// Copyright (c) 2025-2026 ancplua
+export const SortOrderValues = {
+    "asc": "asc",
+    "desc": "desc",
+};
+export const TimeBucketValues = {
+    "minute": "1m",
+    "fiveMinutes": "5m",
+    "fifteenMinutes": "15m",
+    "hour": "1h",
+    "day": "1d",
+    "week": "1w",
+    "auto": "auto",
+};
+export const SpanKindValues = {
+    "unspecified": 0,
+    "internal": 1,
+    "server": 2,
+    "client": 3,
+    "producer": 4,
+    "consumer": 5,
+};
+export const SpanStatusCodeValues = {
+    "unset": 0,
+    "ok": 1,
+    "error": 2,
+};
+export const SpanFlagsValues = {
+    "none": 0,
+    "sampled": 1,
+    "random": 2,
+};
+export const SeverityNumberValues = {
+    "unspecified": 0,
+    "trace": 1,
+    "trace2": 2,
+    "trace3": 3,
+    "trace4": 4,
+    "debug": 5,
+    "debug2": 6,
+    "debug3": 7,
+    "debug4": 8,
+    "info": 9,
+    "info2": 10,
+    "info3": 11,
+    "info4": 12,
+    "warn": 13,
+    "warn2": 14,
+    "warn3": 15,
+    "warn4": 16,
+    "error": 17,
+    "error2": 18,
+    "error3": 19,
+    "error4": 20,
+    "fatal": 21,
+    "fatal2": 22,
+    "fatal3": 23,
+    "fatal4": 24,
+};
+export const SeverityTextValues = {
+    "TRACE": "TRACE",
+    "DEBUG": "DEBUG",
+    "INFO": "INFO",
+    "WARN": "WARN",
+    "ERROR": "ERROR",
+    "FATAL": "FATAL",
+};
+export const MetricTypeValues = {
+    "gauge": "gauge",
+    "sum": "sum",
+    "histogram": "histogram",
+    "exponentialHistogram": "exponential_histogram",
+    "summary": "summary",
+};
+export const AggregationTemporalityValues = {
+    "unspecified": 0,
+    "delta": 1,
+    "cumulative": 2,
+};
+export const DataPointFlagsValues = {
+    "none": 0,
+    "noRecordedValue": 1,
+};
+export const InstrumentKindValues = {
+    "counter": "Counter",
+    "upDownCounter": "UpDownCounter",
+    "histogram": "Histogram",
+    "gauge": "Gauge",
+    "observableCounter": "ObservableCounter",
+    "observableGauge": "ObservableGauge",
+    "observableUpDownCounter": "ObservableUpDownCounter",
+};
+export const TelemetrySdkLanguageValues = {
+    "cpp": "cpp",
+    "dotnet": "dotnet",
+    "erlang": "erlang",
+    "go": "go",
+    "java": "java",
+    "nodejs": "nodejs",
+    "php": "php",
+    "python": "python",
+    "ruby": "ruby",
+    "rust": "rust",
+    "swift": "swift",
+    "webjs": "webjs",
+};
+export const ErrorTypeValues = {
+    "error": "_OTHER",
+    "timeout": "TIMEOUT",
+    "connectionRefused": "CONNECTION_REFUSED",
+    "dnsError": "DNS_ERROR",
+    "tlsError": "TLS_ERROR",
+    "authError": "AUTH_ERROR",
+    "permissionDenied": "PERMISSION_DENIED",
+    "notFound": "NOT_FOUND",
+    "resourceExhausted": "RESOURCE_EXHAUSTED",
+    "invalidArgument": "INVALID_ARGUMENT",
+    "cancelled": "CANCELLED",
+};
+export const EventDomainValues = {
+    "browser": "browser",
+    "device": "device",
+    "k8s": "k8s",
+    "session": "session",
+    "genAi": "gen_ai",
+    "exception": "exception",
+    "log": "log",
+};
+export const OriginalPayloadFormatValues = {
+    "pprof": "pprof",
+    "jfr": "jfr",
+    "linuxPerf": "linux_perf",
+};
+export const ProfileFrameTypeValues = {
+    "beam": "beam",
+    "cpython": "cpython",
+    "dotnet": "dotnet",
+    "go": "go",
+    "jvm": "jvm",
+    "kernel": "kernel",
+    "native": "native",
+    "perl": "perl",
+    "php": "php",
+    "ruby": "ruby",
+    "rust": "rust",
+    "v8js": "v8js",
+};
+export const CloudProviderValues = {
+    "alibabaCloud": "alibaba_cloud",
+    "aws": "aws",
+    "azure": "azure",
+    "gcp": "gcp",
+    "heroku": "heroku",
+    "ibmCloud": "ibm_cloud",
+    "tencentCloud": "tencent_cloud",
+};
+export const HostArchValues = {
+    "amd64": "amd64",
+    "arm32": "arm32",
+    "arm64": "arm64",
+    "ia64": "ia64",
+    "ppc32": "ppc32",
+    "ppc64": "ppc64",
+    "s390x": "s390x",
+    "x86": "x86",
+};
+export const OsTypeValues = {
+    "windows": "windows",
+    "linux": "linux",
+    "darwin": "darwin",
+    "freebsd": "freebsd",
+    "netbsd": "netbsd",
+    "openbsd": "openbsd",
+    "dragonflybsd": "dragonflybsd",
+    "hpux": "hpux",
+    "aix": "aix",
+    "solaris": "solaris",
+    "zOs": "z_os",
+};
+export const SessionEventNameValues = {
+    "sessionStart": "session.start",
+    "sessionEnd": "session.end",
+};
+export const SessionStateValues = {
+    "active": "active",
+    "idle": "idle",
+    "ended": "ended",
+    "timedOut": "timed_out",
+    "invalidated": "invalidated",
+};
+export const DeviceTypeValues = {
+    "desktop": "desktop",
+    "mobile": "mobile",
+    "tablet": "tablet",
+    "tv": "tv",
+    "console": "console",
+    "wearable": "wearable",
+    "iot": "iot",
+    "bot": "bot",
+    "unknown": "unknown",
+};
+export const HealthStatusValues = {
+    "healthy": "healthy",
+    "degraded": "degraded",
+    "unhealthy": "unhealthy",
+};
+export const RunnerResourceLifecycleValues = {
+    "pending": "pending",
+    "starting": "starting",
+    "ready": "ready",
+    "stopping": "stopping",
+    "stopped": "stopped",
+    "failed": "failed",
+};
+export const RunnerResourceKindValues = {
+    "collector": "collector",
+    "project": "project",
+    "command": "command",
+    "stdio": "stdio",
+    "http": "http",
+    "inproc": "inproc",
+};
+export const RunnerLogStreamValues = {
+    "stdout": "out",
+    "stderr": "err",
+};
+export const McpDataModeValues = {
+    "live": "live",
+    "demo": "demo",
+};
+export const FetchTelemetryViewValues = {
+    "traces": "traces",
+    "trace": "trace",
+    "logs": "logs",
+    "mcpStats": "mcp_stats",
+};

package/index.tsp

@@ -1,22 +1,10 @@
-// =============================================================================
-// @ancplua/qyl-api-schema — published entry point
-// =============================================================================
-// Consumer-facing barrel. Mirrors main.tsp minus local emit routing.
-// The local emitters depend on `file:` packages
-// (@ancplua/typespec-emit-*) which are not shipped to registry consumers and
-// would break TypeSpec import resolution.
-//
-// Use main.tsp inside this repo for local `tsp compile`; downstream consumers
-// reach the public surface through this file via the `.` export.
-// =============================================================================
+// @ancplua/qyl-api-schema — published TypeSpec entry point.
+// Build-only emitter configuration belongs in main.tsp and is intentionally absent here.
 
+import "@typespec/events";
 import "@typespec/http";
-import "@typespec/rest";
 import "@typespec/openapi";
-import "@typespec/openapi3";
-import "@typespec/versioning";
 import "@typespec/sse";
-import "@typespec/events";
 
 import "./generated/otel-keys.gen.tsp";
 
@@ -28,28 +16,14 @@ import "./otel/enums.tsp";
 import "./otel/resource.tsp";
 import "./otel/span.tsp";
 import "./otel/logs.tsp";
-import "./otel/metrics.tsp";
 import "./otel/profiles.tsp";
 
-import "./models/genai.tsp";
-import "./models/http.tsp";
-import "./models/rpc.tsp";
-import "./models/messaging.tsp";
-import "./models/db.tsp";
 import "./models/session.tsp";
-import "./models/otel-config.tsp";
-import "./models/log.tsp";
-import "./models/error.tsp";
-import "./models/test.tsp";
-import "./models/deployment.tsp";
-import "./models/system.tsp";
-import "./models/identity.tsp";
-import "./models/control-graph.tsp";
+import "./models/health.tsp";
+import "./models/runner.tsp";
+import "./models/runner-mcp.tsp";
+import "./models/mcp-tools.tsp";
 
 import "./api/routes.tsp";
 import "./api/streaming.tsp";
-
-using TypeSpec.Http;
-using TypeSpec.Rest;
-using TypeSpec.OpenAPI;
-using TypeSpec.Versioning;
+import "./api/runner.tsp";

package/models/health.tsp

@@ -0,0 +1,22 @@
+namespace Qyl.Api.Contracts.Health;
+
+@doc("Health state reported by a qyl-managed process.")
+enum HealthStatus {
+  healthy: "healthy",
+  degraded: "degraded",
+  unhealthy: "unhealthy",
+}
+
+@doc("One named health-check result.")
+model HealthCheckEntry {
+  status: HealthStatus;
+  description?: string;
+  durationMs: float64;
+}
+
+@doc("Readiness or liveness report returned by /health and /alive.")
+model HealthReport {
+  status: HealthStatus;
+  totalDurationMs: float64;
+  entries: Record<HealthCheckEntry>;
+}

package/models/mcp-tools.tsp

@@ -0,0 +1,217 @@
+import "../common/types.tsp";
+import "../otel/logs.tsp";
+import "../otel/span.tsp";
+import "./session.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;
+
+namespace Qyl.Api.Contracts.Mcp.Tools;
+
+@doc("Whether a qyl MCP tool read live collector data or the explicit demo dataset.")
+enum McpDataMode {
+  live: "live",
+  demo: "demo",
+}
+
+@doc("Data projection requested by the app-only fetch_telemetry tool.")
+enum FetchTelemetryView {
+  traces: "traces",
+  trace: "trace",
+  logs: "logs",
+  mcpStats: "mcp_stats",
+}
+
+@doc("Input for display_traces.")
+model DisplayTracesInput {
+  @encodedName("application/json", "trace_id")
+  traceId?: TraceId;
+  @encodedName("application/json", "session_id")
+  sessionId?: SessionId;
+  @minValue(1)
+  @maxValue(100)
+  limit?: int32 = 20;
+}
+
+@doc("Structured output for display_traces.")
+model DisplayTracesOutput {
+  traces: Trace[];
+  @encodedName("application/json", "selected_trace_id")
+  selectedTraceId?: TraceId;
+  mode: McpDataMode;
+}
+
+@doc("Input for display_mcp_dashboard.")
+model DisplayMcpDashboardInput {
+  @minValue(1)
+  @maxValue(168)
+  hours?: float64 = 24;
+}
+
+@doc("Structured output for display_mcp_dashboard.")
+model DisplayMcpDashboardOutput {
+  stats: McpDashboardStats;
+}
+
+@doc("Input for list_traces.")
+model ListTracesInput {
+  @minValue(1)
+  @maxValue(100)
+  limit?: int32 = 20;
+}
+
+@doc("Structured output for list_traces.")
+model ListTracesOutput {
+  traces: TraceSummary[];
+  mode: McpDataMode;
+}
+
+@doc("Input for get_trace.")
+model GetTraceInput {
+  @encodedName("application/json", "trace_id")
+  traceId: TraceId;
+}
+
+@doc("Structured output for get_trace.")
+model GetTraceOutput {
+  trace: Trace;
+  mode: McpDataMode;
+}
+
+@doc("Input for list_sessions.")
+model ListSessionsInput {
+  @minValue(1)
+  @maxValue(100)
+  limit?: int32 = 20;
+  @encodedName("application/json", "active_only")
+  activeOnly?: boolean;
+}
+
+@doc("Structured output for list_sessions.")
+model ListSessionsOutput {
+  sessions: SessionEntity[];
+  mode: McpDataMode;
+}
+
+@doc("Input for search_logs.")
+model SearchLogsInput {
+  @encodedName("application/json", "trace_id")
+  traceId?: TraceId;
+  @encodedName("application/json", "service_name")
+  serviceName?: string;
+  @encodedName("application/json", "severity_min")
+  @minValue(1)
+  @maxValue(24)
+  severityMin?: int32;
+  query?: string;
+  @minValue(1)
+  @maxValue(200)
+  limit?: int32 = 50;
+}
+
+@doc("Structured output for search_logs.")
+model SearchLogsOutput {
+  logs: LogRecord[];
+  mode: McpDataMode;
+}
+
+@doc("Input for the app-only fetch_telemetry tool.")
+model FetchTelemetryInput {
+  view: FetchTelemetryView;
+  @encodedName("application/json", "trace_id")
+  traceId?: TraceId;
+  @encodedName("application/json", "service_name")
+  serviceName?: string;
+  @encodedName("application/json", "severity_min")
+  @minValue(1)
+  @maxValue(24)
+  severityMin?: int32;
+  query?: string;
+  @minValue(1)
+  @maxValue(200)
+  limit?: int32;
+  @minValue(1)
+  @maxValue(168)
+  hours?: float64;
+}
+
+@doc("Structured output for the app-only fetch_telemetry tool.")
+model FetchTelemetryOutput {
+  traces?: Trace[];
+  trace?: Trace;
+  logs?: LogRecord[];
+  stats?: McpDashboardStats;
+  mode: McpDataMode;
+}
+
+@doc("Aggregate MCP traffic statistics shown by qyl.mcp.")
+model McpDashboardStats {
+  window: McpDashboardWindow;
+  buckets: McpDashboardBucket[];
+  totals: McpDashboardTotals;
+  @encodedName("application/json", "by_server")
+  byServer: McpNameRequestCount[];
+  @encodedName("application/json", "by_transport")
+  byTransport: McpNameRequestCount[];
+  @encodedName("application/json", "by_method")
+  byMethod: McpNameRequestCount[];
+  tools: McpToolStats[];
+  @encodedName("application/json", "span_count_analyzed")
+  @minValue(0)
+  spanCountAnalyzed: int32;
+  truncated: boolean;
+  mode: McpDataMode;
+}
+
+model McpDashboardWindow {
+  start: utcDateTime;
+  end: utcDateTime;
+  @encodedName("application/json", "bucket_ms")
+  @minValue(0)
+  bucketMs: float64;
+}
+
+model McpDashboardBucket {
+  start: utcDateTime;
+  @minValue(0)
+  requests: int32;
+  @minValue(0)
+  errors: int32;
+}
+
+model McpDashboardTotals {
+  @minValue(0)
+  requests: int32;
+  @minValue(0)
+  errors: int32;
+  @encodedName("application/json", "error_rate")
+  @minValue(0)
+  @maxValue(1)
+  errorRate: float64;
+}
+
+model McpNameRequestCount {
+  name: string;
+  @minValue(0)
+  requests: int32;
+}
+
+model McpToolStats {
+  name: string;
+  @minValue(0)
+  requests: int32;
+  @minValue(0)
+  errors: int32;
+  @encodedName("application/json", "error_rate")
+  @minValue(0)
+  @maxValue(1)
+  errorRate: float64;
+  @encodedName("application/json", "avg_ms")
+  @minValue(0)
+  avgMs: float64;
+  @encodedName("application/json", "p95_ms")
+  @minValue(0)
+  p95Ms: float64;
+}

package/models/runner-mcp.tsp

@@ -0,0 +1,76 @@
+namespace Qyl.Api.Contracts.Runner.Mcp;
+
+@doc("Stable qyl projection of an MCP tool advertised by a runner resource.")
+model RunnerMcpTool {
+  name: string;
+  title?: string;
+  description?: string;
+  inputSchema: Record<unknown>;
+  outputSchema?: Record<unknown>;
+  annotations?: Record<unknown>;
+  @encodedName("application/json", "_meta")
+  metadata?: Record<unknown>;
+}
+
+@doc("MCP tools currently advertised by a runner resource.")
+model RunnerMcpToolsResponse {
+  tools: RunnerMcpTool[];
+  nextCursor?: string;
+  @encodedName("application/json", "_meta")
+  metadata?: Record<unknown>;
+}
+
+@doc("Tool call accepted by the runner's MCP projection.")
+model RunnerMcpToolCallRequest {
+  name: string;
+  arguments?: Record<unknown>;
+}
+
+@doc("One MCP content item projected onto a stable qyl JSON shape.")
+model RunnerMcpContent {
+  type: string;
+  text?: string;
+  data?: string;
+  mimeType?: string;
+  uri?: url;
+  name?: string;
+  title?: string;
+  description?: string;
+  @minValue(0)
+  size?: int64;
+  resource?: Record<unknown>;
+  annotations?: Record<unknown>;
+  @encodedName("application/json", "_meta")
+  metadata?: Record<unknown>;
+}
+
+@doc("Stable qyl projection of an MCP tool-call result.")
+model RunnerMcpToolCallResponse {
+  content: RunnerMcpContent[];
+  structuredContent?: Record<unknown>;
+  isError: boolean;
+  @encodedName("application/json", "_meta")
+  metadata?: Record<unknown>;
+}
+
+@doc("Resource URI accepted by the runner's MCP projection.")
+model RunnerMcpResourceReadRequest {
+  uri: url;
+}
+
+@doc("Text or base64 resource content returned by an MCP server. Exactly one of text or blob is present.")
+model RunnerMcpResourceContent {
+  uri: url;
+  mimeType?: string;
+  text?: string;
+  blob?: string;
+  @encodedName("application/json", "_meta")
+  metadata?: Record<unknown>;
+}
+
+@doc("Stable qyl projection of an MCP resources/read result.")
+model RunnerMcpResourceReadResponse {
+  contents: RunnerMcpResourceContent[];
+  @encodedName("application/json", "_meta")
+  metadata?: Record<unknown>;
+}

package/models/runner.tsp

@@ -0,0 +1,67 @@
+import "@typespec/http";
+
+using TypeSpec.Http;
+
+namespace Qyl.Api.Contracts.Runner;
+
+@doc("Lifecycle state of a resource supervised by the local qyl runner.")
+enum RunnerResourceLifecycle {
+  pending: "pending",
+  starting: "starting",
+  ready: "ready",
+  stopping: "stopping",
+  stopped: "stopped",
+  failed: "failed",
+}
+
+@doc("Kind of process or connection supervised by the local qyl runner.")
+enum RunnerResourceKind {
+  collector: "collector",
+  project: "project",
+  command: "command",
+  stdio: "stdio",
+  http: "http",
+  inproc: "inproc",
+}
+
+@doc("Identity reported by a connected MCP server during initialization.")
+model RunnerMcpServerInfo {
+  name: string;
+  version: string;
+}
+
+@doc("Current client-visible state of one runner resource.")
+model RunnerResourceState {
+  name: string;
+  lifecycle: RunnerResourceLifecycle;
+  timestamp: utcDateTime;
+  kind?: RunnerResourceKind;
+  @minValue(1)
+  @maxValue(65535)
+  allocatedPort?: int32;
+  endpoint?: url;
+  lastError?: string;
+  serverInfo?: RunnerMcpServerInfo;
+  @minValue(0)
+  toolCount?: int32;
+  @minValue(0)
+  restarts?: int32;
+}
+
+@doc("A runner lifecycle action was accepted and continues asynchronously.")
+model RunnerActionAccepted {
+  @statusCode statusCode: 202;
+}
+
+@doc("Origin stream for one captured child-process log line.")
+enum RunnerLogStream {
+  stdout: "out",
+  stderr: "err",
+}
+
+@doc("One bounded child-process log line exposed by the runner.")
+model RunnerLogLine {
+  resource: string;
+  stream: RunnerLogStream;
+  line: string;
+}

package/models/session.tsp

@@ -1,5 +1,5 @@
 // =============================================================================
-// ANcpLua v2.0 - Session Semantic Conventions
+// Qyl session API contracts
 // =============================================================================
 // User session telemetry attributes.
 // =============================================================================

package/otel/enums.tsp

@@ -1,5 +1,5 @@
 // =============================================================================
-// ANcpLua v2.0 - OpenTelemetry Core Enumerations
+// OpenTelemetry JSON projection enumerations
 // =============================================================================
 // All OTel standard enumerations following OTel Semantic Conventions.
 // =============================================================================

package/otel/logs.tsp

@@ -1,5 +1,5 @@
 // =============================================================================
-// ANcpLua v2.0 - OpenTelemetry Log Record Model
+// OpenTelemetry log JSON projection
 // =============================================================================
 // Structured logging following OTel log data model.
 // =============================================================================