@ancplua/qyl-api-schema 0.5.0 → 0.5.1

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

@@ -247,11 +247,32 @@ export declare const RunnerResourceLifecycleValues: {
     readonly failed: "failed";
 };
 export type RunnerResourceLifecycle = typeof RunnerResourceLifecycleValues[keyof typeof RunnerResourceLifecycleValues];
+export declare const RunnerResourceKindValues: {
+    readonly collector: "collector";
+    readonly project: "project";
+    readonly command: "command";
+    readonly stdio: "stdio";
+    readonly http: "http";
+    readonly inproc: "inproc";
+};
+export type RunnerResourceKind = typeof RunnerResourceKindValues[keyof typeof RunnerResourceKindValues];
 export declare const RunnerLogStreamValues: {
     readonly stdout: "out";
     readonly stderr: "err";
 };
 export type RunnerLogStream = typeof RunnerLogStreamValues[keyof typeof RunnerLogStreamValues];
+export declare const McpDataModeValues: {
+    readonly live: "live";
+    readonly demo: "demo";
+};
+export type McpDataMode = typeof McpDataModeValues[keyof typeof McpDataModeValues];
+export declare const FetchTelemetryViewValues: {
+    readonly traces: "traces";
+    readonly trace: "trace";
+    readonly logs: "logs";
+    readonly mcpStats: "mcp_stats";
+};
+export type FetchTelemetryView = typeof FetchTelemetryViewValues[keyof typeof FetchTelemetryViewValues];
 export type AttributeValue = string | boolean | number | string[] | boolean[] | number[];
 export type ApiError = NotFoundError | ValidationError | UnauthorizedError | ForbiddenError | ConflictError | RateLimitError | InternalServerError | BadGatewayError | ServiceUnavailableError;
 export type LogBody = LogBodyString | LogBodyKvList | LogBodyArray | LogBodyBytes;
@@ -422,9 +443,8 @@ export interface SpanStatus {
     "code": SpanStatusCode;
     "message"?: string;
 }
-export interface Trace {
+export interface TraceSummary {
     "trace_id": TraceId;
-    "spans": Span[];
     "root_span"?: Span;
     "span_count": number;
     "duration_ns": number;
@@ -433,6 +453,9 @@ export interface Trace {
     "services": string[];
     "has_error": boolean;
 }
+export interface Trace extends TraceSummary {
+    "spans": Span[];
+}
 export interface SpanQueryFilters {
     "trace_id"?: TraceId;
     "parent_span_id"?: SpanId;
@@ -651,14 +674,21 @@ export interface HealthReport {
     "totalDurationMs": number;
     "entries": Record<string, HealthCheckEntry>;
 }
+export interface RunnerMcpServerInfo {
+    "name": string;
+    "version": string;
+}
 export interface RunnerResourceState {
     "name": string;
     "lifecycle": RunnerResourceLifecycle;
     "timestamp": string;
-    "kind"?: string;
+    "kind"?: RunnerResourceKind;
     "allocatedPort"?: number;
     "endpoint"?: string;
     "lastError"?: string;
+    "serverInfo"?: RunnerMcpServerInfo;
+    "toolCount"?: number;
+    "restarts"?: number;
 }
 export interface RunnerLogLine {
     "resource": string;
@@ -669,12 +699,15 @@ export interface RunnerMcpTool {
     "name": string;
     "title"?: string;
     "description"?: string;
-    "inputSchema"?: Record<string, unknown>;
+    "inputSchema": Record<string, unknown>;
     "outputSchema"?: Record<string, unknown>;
+    "annotations"?: Record<string, unknown>;
+    "_meta"?: Record<string, unknown>;
 }
 export interface RunnerMcpToolsResponse {
     "tools": RunnerMcpTool[];
     "nextCursor"?: string;
+    "_meta"?: Record<string, unknown>;
 }
 export interface RunnerMcpToolCallRequest {
     "name": string;
@@ -698,6 +731,125 @@ export interface RunnerMcpToolCallResponse {
     "content": RunnerMcpContent[];
     "structuredContent"?: Record<string, unknown>;
     "isError": boolean;
+    "_meta"?: Record<string, unknown>;
+}
+export interface RunnerMcpResourceReadRequest {
+    "uri": string;
+}
+export interface RunnerMcpResourceContent {
+    "uri": string;
+    "mimeType"?: string;
+    "text"?: string;
+    "blob"?: string;
+    "_meta"?: Record<string, unknown>;
+}
+export interface RunnerMcpResourceReadResponse {
+    "contents": RunnerMcpResourceContent[];
+    "_meta"?: Record<string, unknown>;
+}
+export interface DisplayTracesInput {
+    "trace_id"?: TraceId;
+    "session_id"?: SessionId;
+    "limit"?: number;
+}
+export interface DisplayTracesOutput {
+    "traces": Trace[];
+    "selected_trace_id"?: TraceId;
+    "mode": McpDataMode;
+}
+export interface DisplayMcpDashboardInput {
+    "hours"?: number;
+}
+export interface DisplayMcpDashboardOutput {
+    "stats": McpDashboardStats;
+}
+export interface McpDashboardStats {
+    "window": McpDashboardWindow;
+    "buckets": McpDashboardBucket[];
+    "totals": McpDashboardTotals;
+    "by_server": McpNameRequestCount[];
+    "by_transport": McpNameRequestCount[];
+    "by_method": McpNameRequestCount[];
+    "tools": McpToolStats[];
+    "span_count_analyzed": number;
+    "truncated": boolean;
+    "mode": McpDataMode;
+}
+export interface McpDashboardWindow {
+    "start": string;
+    "end": string;
+    "bucket_ms": number;
+}
+export interface McpDashboardBucket {
+    "start": string;
+    "requests": number;
+    "errors": number;
+}
+export interface McpDashboardTotals {
+    "requests": number;
+    "errors": number;
+    "error_rate": number;
+}
+export interface McpNameRequestCount {
+    "name": string;
+    "requests": number;
+}
+export interface McpToolStats {
+    "name": string;
+    "requests": number;
+    "errors": number;
+    "error_rate": number;
+    "avg_ms": number;
+    "p95_ms": number;
+}
+export interface ListTracesInput {
+    "limit"?: number;
+}
+export interface ListTracesOutput {
+    "traces": TraceSummary[];
+    "mode": McpDataMode;
+}
+export interface GetTraceInput {
+    "trace_id": TraceId;
+}
+export interface GetTraceOutput {
+    "trace": Trace;
+    "mode": McpDataMode;
+}
+export interface ListSessionsInput {
+    "limit"?: number;
+    "active_only"?: boolean;
+}
+export interface ListSessionsOutput {
+    "sessions": SessionEntity[];
+    "mode": McpDataMode;
+}
+export interface SearchLogsInput {
+    "trace_id"?: TraceId;
+    "service_name"?: string;
+    "severity_min"?: number;
+    "query"?: string;
+    "limit"?: number;
+}
+export interface SearchLogsOutput {
+    "logs": LogRecord[];
+    "mode": McpDataMode;
+}
+export interface FetchTelemetryInput {
+    "view": FetchTelemetryView;
+    "trace_id"?: TraceId;
+    "service_name"?: string;
+    "severity_min"?: number;
+    "query"?: string;
+    "limit"?: number;
+    "hours"?: number;
+}
+export interface FetchTelemetryOutput {
+    "traces"?: Trace[];
+    "trace"?: Trace;
+    "logs"?: LogRecord[];
+    "stats"?: McpDashboardStats;
+    "mode": McpDataMode;
 }
 export interface LogStreamEvent {
     "type": "log";

package/generated/ts-runtime/api.js

@@ -213,7 +213,25 @@ export const RunnerResourceLifecycleValues = {
     "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

@@ -22,6 +22,7 @@ import "./models/session.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";

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

@@ -5,14 +5,19 @@ model RunnerMcpTool {
   name: string;
   title?: string;
   description?: string;
-  inputSchema?: Record<unknown>;
+  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.")
@@ -44,4 +49,28 @@ 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

@@ -1,3 +1,7 @@
+import "@typespec/http";
+
+using TypeSpec.Http;
+
 namespace Qyl.Api.Contracts.Runner;
 
 @doc("Lifecycle state of a resource supervised by the local qyl runner.")
@@ -10,17 +14,43 @@ enum RunnerResourceLifecycle {
   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?: string;
+  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.")

package/otel/span.tsp

@@ -147,16 +147,13 @@ model SpanLink {
 // Trace Model (Collection of Spans)
 // =============================================================================
 
-@doc("Complete trace containing all related spans")
-model Trace {
+@doc("Trace summary without the full span collection")
+model TraceSummary {
   @doc("Trace identifier")
   @key
   @encodedName("application/json", "trace_id")
   traceId: TraceId;
 
-  @doc("All spans in this trace")
-  spans: Span[];
-
   @doc("Root span of the trace")
   @encodedName("application/json", "root_span")
   rootSpan?: Span;
@@ -185,6 +182,12 @@ model Trace {
   hasError: boolean;
 }
 
+@doc("Complete trace containing all related spans")
+model Trace extends TraceSummary {
+  @doc("All spans in this trace")
+  spans: Span[];
+}
+
 // =============================================================================
 // Span Query Filters
 // =============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancplua/qyl-api-schema",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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": {
@@ -37,6 +37,12 @@
       "types": "./generated/ts-runtime/api.d.ts",
       "import": "./generated/ts-runtime/api.js",
       "default": "./generated/ts-runtime/api.js"
+    },
+    "./openapi": {
+      "default": "./generated/openapi/qyl.openapi.json"
+    },
+    "./json-schema": {
+      "default": "./generated/json-schema/qyl-api-schema.json"
     }
   },
   "files": [
@@ -50,6 +56,7 @@
     "models/health.tsp",
     "models/runner-mcp.tsp",
     "models/runner.tsp",
+    "models/mcp-tools.tsp",
     "models/session.tsp",
     "otel/enums.tsp",
     "otel/logs.tsp",
@@ -60,6 +67,8 @@
     "generated/otel-keys.gen.tsp",
     "generated/ts-runtime/api.d.ts",
     "generated/ts-runtime/api.js",
+    "generated/openapi/qyl.openapi.json",
+    "generated/json-schema/qyl-api-schema.json",
     "README.md",
     "LICENSE"
   ],
@@ -72,9 +81,10 @@
     "clean:generated": "node scripts/clean-generated.mjs",
     "build:emitters": "tsc -p emitters/csharp && tsc -p emitters/ts-types",
     "build:ts-runtime": "tsc -p tsconfig.contracts.json",
+    "build:json-schema": "node scripts/openapi-to-json-schema.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 build:ts-runtime",
+    "compile": "npm run clean:generated && npm run build:emitters && tsp compile main.tsp && npm run build:json-schema && npm run build:ts-runtime",
     "watch": "tsp compile main.tsp --watch",
     "format": "tsp format **/*.tsp",
     "lint": "npm run build:emitters && tsp compile main.tsp --no-emit --warn-as-error",
@@ -84,7 +94,6 @@
     "@typespec/compiler": "^1.13.0 || >=1.13.0-dev.0",
     "@typespec/events": "^0.83.0",
     "@typespec/http": "^1.13.0",
-    "@typespec/json-schema": "^1.13.0",
     "@typespec/openapi": "^1.13.0",
     "@typespec/sse": "^0.83.0"
   },
@@ -95,7 +104,6 @@
     "@typespec/compiler": "1.13.0",
     "@typespec/events": "0.83.0",
     "@typespec/http": "1.13.0",
-    "@typespec/json-schema": "1.13.0",
     "@typespec/openapi": "1.13.0",
     "@typespec/openapi3": "1.13.0",
     "@typespec/sse": "0.83.0",