@ancplua/qyl-api-schema 0.5.0 → 0.5.1

package/README.md

@@ -16,7 +16,7 @@ generated/otel-keys.gen.tsp
         v
 authored Qyl TypeSpec
         |
-        +----> OpenAPI and JSON Schema
+        +----> OpenAPI ----> bundled JSON Schema
         +----> Qyl.Api.Contracts
         +----> generated TypeScript contracts
 ```
@@ -67,8 +67,10 @@ Important generated outputs include:
 - `generated/contracts/**/*.cs`
 - `generated/ts-types/**`
 
-Generated files are not editing surfaces. Change TypeSpec or the owning emitter and
-regenerate.
+Generated files are not editing surfaces. OpenAPI comes from the official TypeSpec
+emitter; the bundled JSON Schema is a deterministic projection of its component
+schemas so both artifacts preserve the same wire names. Change TypeSpec or the
+owning generator and regenerate.
 
 ## Publish
 

package/api/runner.tsp

@@ -45,12 +45,25 @@ namespace Qyl.Api.Contracts.Runner {
     streamLogs(
       @path resource: string,
     ): SSEStream<RunnerLogEvents> | NotFoundError | InternalServerError;
+
+    @post
+    @route("/{resource}/restart")
+    restart(
+      @path resource: string,
+    ): RunnerActionAccepted | NotFoundError | ConflictError | InternalServerError;
+
+    @post
+    @route("/{resource}/stop")
+    stop(
+      @path resource: string,
+    ): RunnerActionAccepted | NotFoundError | ConflictError | InternalServerError;
   }
 
-  @route("/runner/mcp/{resource}/tools")
+  @route("/runner/mcp/{resource}")
   @tag("Runner MCP")
   interface RunnerMcpApi {
     @get
+    @route("/tools")
     listTools(
       @path resource: string,
     ): RunnerMcpToolsResponse
@@ -60,7 +73,7 @@ namespace Qyl.Api.Contracts.Runner {
       | InternalServerError;
 
     @post
-    @route("/call")
+    @route("/tools/call")
     callTool(
       @path resource: string,
       @body request: RunnerMcpToolCallRequest,
@@ -70,5 +83,17 @@ namespace Qyl.Api.Contracts.Runner {
       | ConflictError
       | BadGatewayError
       | InternalServerError;
+
+    @post
+    @route("/resources/read")
+    readResource(
+      @path resource: string,
+      @body request: RunnerMcpResourceReadRequest,
+    ): RunnerMcpResourceReadResponse
+      | ValidationError
+      | NotFoundError
+      | ConflictError
+      | BadGatewayError
+      | InternalServerError;
   }
 }

package/common/types.tsp

@@ -6,10 +6,8 @@
 // (GenAI keys come from the dedicated GenAI registry since the 1.42 split).
 // =============================================================================
 
-import "@typespec/json-schema";
 import "@typespec/openapi";
 
-using TypeSpec.JsonSchema;
 using TypeSpec.OpenAPI;
 
 namespace Qyl.Api.Contracts.Common;
@@ -20,7 +18,6 @@ namespace Qyl.Api.Contracts.Common;
 // The semantic-conventions pin lives in the generated keys header and is
 // machine-checked; a hand-maintained enum of upstream releases would only drift.
 
-@jsonSchema
 @doc("Unique trace identifier (32 lowercase hex characters)")
 @pattern("^[a-f0-9]{32}$")
 @minLength(32)
@@ -30,7 +27,6 @@ namespace Qyl.Api.Contracts.Common;
 @TypeSpec.OpenAPI.extension("x-csharp-type", "TraceId")
 scalar TraceId extends string;
 
-@jsonSchema
 @doc("Unique span identifier (16 lowercase hex characters)")
 @pattern("^[a-f0-9]{16}$")
 @minLength(16)
@@ -40,18 +36,15 @@ scalar TraceId extends string;
 @TypeSpec.OpenAPI.extension("x-csharp-type", "SpanId")
 scalar SpanId extends string;
 
-@jsonSchema
 @doc("W3C Trace Context traceparent header format")
 @pattern("^[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$")
 @example("00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01")
 scalar TraceParent extends string;
 
-@jsonSchema
 @doc("W3C Trace Context tracestate header (vendor-specific key-value pairs)")
 @example("rojo=00f067aa0ba902b7,congo=t61rcWkgMzE")
 scalar TraceState extends string;
 
-@jsonSchema
 @doc("Unique session identifier")
 @minLength(1)
 @maxLength(128)
@@ -59,7 +52,6 @@ scalar TraceState extends string;
 @TypeSpec.OpenAPI.extension("x-csharp-type", "SessionId")
 scalar SessionId extends string;
 
-@jsonSchema
 @doc("User identifier (pseudonymized for privacy)")
 @minLength(1)
 @maxLength(256)
@@ -69,35 +61,29 @@ scalar UserId extends string;
 // Temporal Scalars - Timestamps & Durations
 // =============================================================================
 
-@jsonSchema
 @doc("ISO 8601 timestamp with nanosecond precision (RFC 3339)")
 @encode(DateTimeKnownEncoding.rfc3339)
 scalar Timestamp extends utcDateTime;
 
-@jsonSchema
 @doc("Unsigned Unix timestamp in nanoseconds since epoch")
 @minValue(0)
 @TypeSpec.OpenAPI.extension("x-csharp-type", "ulong")
 scalar UnixNanos extends uint64;
 
-@jsonSchema
 @doc("Duration in nanoseconds")
 @minValue(0)
 @TypeSpec.OpenAPI.extension("x-csharp-type", "ulong")
 scalar DurationNs extends uint64;
 
-@jsonSchema
 @doc("Duration in milliseconds")
 @minValue(0)
 @TypeSpec.OpenAPI.extension("x-csharp-type", "double")
 scalar DurationMs extends float64;
 
-@jsonSchema
 @doc("Duration in seconds")
 @minValue(0)
 scalar DurationS extends float64;
 
-@jsonSchema
 @doc("ISO 8601 duration format (e.g., PT1H30M)")
 @encode(DurationKnownEncoding.ISO8601)
 scalar IsoDuration extends duration;
@@ -106,29 +92,24 @@ scalar IsoDuration extends duration;
 // Network Scalars - IP Addresses & Ports
 // =============================================================================
 
-@jsonSchema
 @doc("IPv4 address in dotted-decimal notation")
 @pattern("^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$")
 @example("192.168.1.1")
 scalar IPv4Address extends string;
 
-@jsonSchema
 @doc("IPv6 address in standard notation")
 @example("2001:0db8:85a3:0000:0000:8a2e:0370:7334")
 scalar IPv6Address extends string;
 
-@jsonSchema
 @doc("IP address (IPv4 or IPv6)")
 scalar IpAddress extends string;
 
-@jsonSchema
 @doc("Network port number (1-65535)")
 @minValue(1)
 @maxValue(65535)
 @TypeSpec.OpenAPI.extension("x-csharp-type", "int")
 scalar Port extends int32;
 
-@jsonSchema
 @doc("MAC address in colon-separated hex notation")
 @pattern("^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$")
 @example("00:1A:2B:3C:4D:5E")
@@ -138,32 +119,27 @@ scalar MacAddress extends string;
 // Size & Count Scalars
 // =============================================================================
 
-@jsonSchema
 @doc("Size in bytes")
 @minValue(0)
 @TypeSpec.OpenAPI.extension("x-csharp-type", "long")
 scalar ByteSize extends int64;
 
-@jsonSchema
 @doc("Token count (for LLM operations)")
 @minValue(0)
 @TypeSpec.OpenAPI.extension("x-csharp-type", "long")
 scalar TokenCount extends int64;
 
-@jsonSchema
 @doc("Generic non-negative counter")
 @minValue(0)
 @TypeSpec.OpenAPI.extension("x-csharp-type", "long")
 scalar Count extends int64;
 
-@jsonSchema
 @doc("Percentage value (0.0 to 100.0)")
 @minValue(0.0)
 @maxValue(100.0)
 @TypeSpec.OpenAPI.extension("x-csharp-type", "double")
 scalar Percentage extends float64;
 
-@jsonSchema
 @doc("Ratio value (0.0 to 1.0)")
 @minValue(0.0)
 @maxValue(1.0)
@@ -174,13 +150,11 @@ scalar Ratio extends float64;
 // GenAI-Specific Scalars
 // =============================================================================
 
-@jsonSchema
 @doc("Cost in USD (floating point)")
 @minValue(0)
 @TypeSpec.OpenAPI.extension("x-csharp-type", "double")
 scalar CostUsd extends float64;
 
-@jsonSchema
 @doc("Temperature setting for LLM requests (0.0-2.0)")
 @minValue(0)
 @maxValue(2)
@@ -191,50 +165,41 @@ scalar Temperature extends float64;
 // Semantic Scalars - Special Purpose Types
 // =============================================================================
 
-@jsonSchema
 @doc("SHA-256 hash in lowercase hex")
 @pattern("^[a-f0-9]{64}$")
 @minLength(64)
 @maxLength(64)
 scalar Sha256Hash extends string;
 
-@jsonSchema
 @doc("Semantic version string (e.g., 1.2.3)")
 @pattern("^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$")
 @example("2.1.0")
 scalar SemVer extends string;
 
-@jsonSchema
 @doc("URL string (absolute)")
 @format("uri")
 scalar UrlString extends string;
 
-@jsonSchema
 @doc("URL path component")
 @example("/api/v1/users")
 scalar UrlPath extends string;
 
-@jsonSchema
 @doc("URL query string (without leading ?)")
 @example("page=1&limit=100")
 scalar UrlQuery extends string;
 
-@jsonSchema
 @doc("HTTP method name (uppercase)")
 @example("GET")
 scalar HttpMethod extends string;
 
-@jsonSchema
 @doc("MIME content type")
 @example("application/json")
 scalar ContentType extends string;
 
-@jsonSchema
 @doc("User agent string")
 @example("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36")
 scalar UserAgent extends string;
 
-@jsonSchema
 @doc("Language/locale code (BCP 47)")
 @pattern("^[a-z]{2,3}(-[A-Z]{2})?$")
 @example("en-US")