@ancplua/qyl-api-schema 0.5.0 → 0.5.2

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

@@ -247,11 +247,46 @@ 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 RunnerMcpToolTaskSupportValues: {
+    readonly forbidden: "forbidden";
+    readonly optional: "optional";
+    readonly required: "required";
+};
+export type RunnerMcpToolTaskSupport = typeof RunnerMcpToolTaskSupportValues[keyof typeof RunnerMcpToolTaskSupportValues];
+export declare const RunnerMcpTaskStatusValues: {
+    readonly working: "working";
+    readonly inputRequired: "input_required";
+    readonly completed: "completed";
+    readonly failed: "failed";
+    readonly cancelled: "cancelled";
+};
+export type RunnerMcpTaskStatus = typeof RunnerMcpTaskStatusValues[keyof typeof RunnerMcpTaskStatusValues];
+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 +457,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 +467,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,34 +688,60 @@ 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;
     "stream": RunnerLogStream;
     "line": string;
 }
+export interface RunnerMcpIcon {
+    "src": string;
+    "mimeType"?: string;
+    "sizes"?: string[];
+    "theme"?: string;
+}
+export interface RunnerMcpToolExecution {
+    "taskSupport"?: RunnerMcpToolTaskSupport;
+}
 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>;
+    "execution"?: RunnerMcpToolExecution;
+    "icons"?: RunnerMcpIcon[];
+    "_meta"?: Record<string, unknown>;
 }
 export interface RunnerMcpToolsResponse {
     "tools": RunnerMcpTool[];
     "nextCursor"?: string;
+    "_meta"?: Record<string, unknown>;
 }
 export interface RunnerMcpToolCallRequest {
     "name": string;
     "arguments"?: Record<string, unknown>;
+    "task"?: RunnerMcpTaskMetadata;
+    "_meta"?: Record<string, unknown>;
+}
+export interface RunnerMcpTaskMetadata {
+    "ttl"?: number;
 }
 export interface RunnerMcpContent {
     "type": string;
@@ -690,14 +753,151 @@ export interface RunnerMcpContent {
     "title"?: string;
     "description"?: string;
     "size"?: number;
-    "resource"?: Record<string, unknown>;
+    "icons"?: RunnerMcpIcon[];
+    "resource"?: RunnerMcpResourceContent;
+    "id"?: string;
+    "input"?: unknown;
+    "toolUseId"?: string;
+    "content"?: RunnerMcpContent[];
+    "structuredContent"?: Record<string, unknown>;
+    "isError"?: boolean;
     "annotations"?: Record<string, unknown>;
     "_meta"?: Record<string, unknown>;
 }
+export interface RunnerMcpResourceContent {
+    "uri": string;
+    "mimeType"?: string;
+    "text"?: string;
+    "blob"?: string;
+    "_meta"?: Record<string, unknown>;
+}
+export interface RunnerMcpTask {
+    "taskId": string;
+    "status": RunnerMcpTaskStatus;
+    "statusMessage"?: string;
+    "createdAt": string;
+    "lastUpdatedAt": string;
+    "ttl"?: number;
+    "pollInterval"?: number;
+}
 export interface RunnerMcpToolCallResponse {
     "content": RunnerMcpContent[];
     "structuredContent"?: Record<string, unknown>;
     "isError": boolean;
+    "task"?: RunnerMcpTask;
+    "_meta"?: Record<string, unknown>;
+}
+export interface RunnerMcpResourceReadRequest {
+    "uri": 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,37 @@ 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 RunnerMcpToolTaskSupportValues = {
+    "forbidden": "forbidden",
+    "optional": "optional",
+    "required": "required",
+};
+export const RunnerMcpTaskStatusValues = {
+    "working": "working",
+    "inputRequired": "input_required",
+    "completed": "completed",
+    "failed": "failed",
+    "cancelled": "cancelled",
+};
+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

@@ -1,27 +1,62 @@
 namespace Qyl.Api.Contracts.Runner.Mcp;
 
+@doc("Icon metadata carried by MCP tools and resource links.")
+model RunnerMcpIcon {
+  src: string;
+  mimeType?: string;
+  sizes?: string[];
+  theme?: string;
+}
+
+@doc("Task-augmentation support advertised for an MCP tool.")
+enum RunnerMcpToolTaskSupport {
+  forbidden: "forbidden",
+  optional: "optional",
+  required: "required",
+}
+
+@doc("Execution metadata advertised for an MCP tool.")
+model RunnerMcpToolExecution {
+  taskSupport?: RunnerMcpToolTaskSupport;
+}
+
 @doc("Stable qyl projection of an MCP tool advertised by a runner resource.")
 model RunnerMcpTool {
   name: string;
   title?: string;
   description?: string;
-  inputSchema?: Record<unknown>;
+  inputSchema: Record<unknown>;
   outputSchema?: Record<unknown>;
+  annotations?: Record<unknown>;
+  execution?: RunnerMcpToolExecution;
+  icons?: RunnerMcpIcon[];
+  @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>;
+  task?: RunnerMcpTaskMetadata;
+  @encodedName("application/json", "_meta")
+  metadata?: Record<unknown>;
 }
 
-@doc("One MCP content item projected onto a stable qyl JSON shape.")
+@doc("Task-augmentation metadata accepted on an MCP tool call. ttl is encoded as milliseconds.")
+model RunnerMcpTaskMetadata {
+  ttl?: float64;
+}
+
+@doc("One MCP content item projected onto a stable qyl JSON shape. Variant-specific required fields follow its type discriminator.")
 model RunnerMcpContent {
   type: string;
   text?: string;
@@ -33,15 +68,69 @@ model RunnerMcpContent {
   description?: string;
   @minValue(0)
   size?: int64;
-  resource?: Record<unknown>;
+  icons?: RunnerMcpIcon[];
+  resource?: RunnerMcpResourceContent;
+  id?: string;
+  input?: unknown;
+  toolUseId?: string;
+  content?: RunnerMcpContent[];
+  structuredContent?: Record<unknown>;
+  isError?: boolean;
   annotations?: Record<unknown>;
   @encodedName("application/json", "_meta")
   metadata?: Record<unknown>;
 }
 
+@doc("Lifecycle state of an MCP task returned by a task-augmented tool call.")
+enum RunnerMcpTaskStatus {
+  working: "working",
+  inputRequired: "input_required",
+  completed: "completed",
+  failed: "failed",
+  cancelled: "cancelled",
+}
+
+@doc("Task returned by an MCP task-augmented tool call. ttl and pollInterval are encoded as milliseconds.")
+model RunnerMcpTask {
+  taskId: string;
+  status: RunnerMcpTaskStatus;
+  statusMessage?: string;
+  createdAt: utcDateTime;
+  lastUpdatedAt: utcDateTime;
+  ttl?: float64;
+  pollInterval?: float64;
+}
+
 @doc("Stable qyl projection of an MCP tool-call result.")
 model RunnerMcpToolCallResponse {
   content: RunnerMcpContent[];
   structuredContent?: Record<unknown>;
   isError: boolean;
+  task?: RunnerMcpTask;
+  @encodedName("application/json", "_meta")
+  metadata?: Record<unknown>;
+}
+
+@doc("Resource URI accepted by the runner's MCP projection.")
+model RunnerMcpResourceReadRequest {
+  uri: url;
+  @encodedName("application/json", "_meta")
+  metadata?: Record<unknown>;
+}
+
+@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>;
 }