@ancplua/qyl-api-schema 0.3.0 → 0.5.0

package/generated/ts-runtime/api.js

@@ -0,0 +1,219 @@
+// <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 RunnerLogStreamValues = {
+    "stdout": "out",
+    "stderr": "err",
+};

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,13 @@ 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 "./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/runner-mcp.tsp

@@ -0,0 +1,47 @@
+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>;
+}
+
+@doc("MCP tools currently advertised by a runner resource.")
+model RunnerMcpToolsResponse {
+  tools: RunnerMcpTool[];
+  nextCursor?: string;
+}
+
+@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;
+}

package/models/runner.tsp

@@ -0,0 +1,37 @@
+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("Current client-visible state of one runner resource.")
+model RunnerResourceState {
+  name: string;
+  lifecycle: RunnerResourceLifecycle;
+  timestamp: utcDateTime;
+  kind?: string;
+  @minValue(1)
+  @maxValue(65535)
+  allocatedPort?: int32;
+  endpoint?: url;
+  lastError?: string;
+}
+
+@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.
 // =============================================================================

package/otel/otel-conventions.tsp

@@ -10,5 +10,4 @@ import "./enums.tsp";
 import "./resource.tsp";
 import "./span.tsp";
 import "./logs.tsp";
-import "./metrics.tsp";
 import "./profiles.tsp";

package/otel/profiles.tsp

@@ -1,5 +1,5 @@
 // =============================================================================
-// ANcpLua v2.0 - OpenTelemetry Profiles Model (v1development)
+// OpenTelemetry profiles JSON projection (v1development)
 // =============================================================================
 // Continuous profiling signal following OTel Profiles proto specification.
 // Proto package: opentelemetry.proto.profiles.v1development

package/otel/resource.tsp

@@ -1,5 +1,5 @@
 // =============================================================================
-// ANcpLua v2.0 - OpenTelemetry Resource Model
+// OpenTelemetry resource JSON projection
 // =============================================================================
 // Resource attributes identifying the entity producing telemetry.
 // =============================================================================

package/otel/span.tsp

@@ -1,5 +1,5 @@
 // =============================================================================
-// ANcpLua v2.0 - OpenTelemetry Span Model
+// OpenTelemetry span JSON projection
 // =============================================================================
 // Distributed tracing span representation following OTel specification.
 // =============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancplua/qyl-api-schema",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "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": {
@@ -19,29 +19,48 @@
     "openapi"
   ],
   "type": "module",
+  "tspMain": "index.tsp",
   "exports": {
-    ".": "./index.tsp",
-    "./otel": "./otel/otel-conventions.tsp",
-    "./models/*": "./models/*.tsp",
-    "./models/agent/*": "./models/agent/*.tsp",
-    "./common/*": "./common/*.tsp",
-    "./api/*": "./api/*.tsp",
-    "./intelligence/*": "./intelligence/*.tsp",
-    "./intelligence/seed/*": "./intelligence/seed/*.tsp",
-    "./generated/otel-keys": "./generated/otel-keys.gen.tsp"
+    ".": {
+      "typespec": "./index.tsp",
+      "default": "./index.tsp"
+    },
+    "./otel": {
+      "typespec": "./otel/otel-conventions.tsp",
+      "default": "./otel/otel-conventions.tsp"
+    },
+    "./generated/otel-keys": {
+      "typespec": "./generated/otel-keys.gen.tsp",
+      "default": "./generated/otel-keys.gen.tsp"
+    },
+    "./types": {
+      "types": "./generated/ts-runtime/api.d.ts",
+      "import": "./generated/ts-runtime/api.js",
+      "default": "./generated/ts-runtime/api.js"
+    }
   },
   "files": [
     "index.tsp",
-    "api/**/*.tsp",
-    "common/**/*.tsp",
-    "intelligence/**/*.tsp",
-    "models/**/*.tsp",
-    "otel/**/*.tsp",
-    "generated/**/*.tsp",
-    "generated/README.md",
-    "tspconfig.yaml",
+    "api/routes.tsp",
+    "api/runner.tsp",
+    "api/streaming.tsp",
+    "common/errors.tsp",
+    "common/pagination.tsp",
+    "common/types.tsp",
+    "models/health.tsp",
+    "models/runner-mcp.tsp",
+    "models/runner.tsp",
+    "models/session.tsp",
+    "otel/enums.tsp",
+    "otel/logs.tsp",
+    "otel/otel-conventions.tsp",
+    "otel/profiles.tsp",
+    "otel/resource.tsp",
+    "otel/span.tsp",
+    "generated/otel-keys.gen.tsp",
+    "generated/ts-runtime/api.d.ts",
+    "generated/ts-runtime/api.js",
     "README.md",
-    "VERSIONING.md",
     "LICENSE"
   ],
   "publishConfig": {
@@ -50,9 +69,12 @@
     "registry": "https://registry.npmjs.org"
   },
   "scripts": {
-    "build:emitters": "tsc -p emitters/telemetry-control-graph && tsc -p emitters/csharp && tsc -p emitters/ts-types && tsc -p emitters/otelconventions-lint",
+    "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",
     "prepare": "npm run build:emitters",
-    "compile": "npm run build:emitters && tsp compile main.tsp",
+    "prepack": "npm run compile",
+    "compile": "npm run clean:generated && npm run build:emitters && tsp compile main.tsp && 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",
@@ -64,29 +86,19 @@
     "@typespec/http": "^1.13.0",
     "@typespec/json-schema": "^1.13.0",
     "@typespec/openapi": "^1.13.0",
-    "@typespec/openapi3": "^1.13.0",
-    "@typespec/rest": "^0.83.0",
-    "@typespec/sse": "^0.83.0",
-    "@typespec/streams": "^0.83.0",
-    "@typespec/versioning": "^0.83.0"
+    "@typespec/sse": "^0.83.0"
   },
   "devDependencies": {
     "@ancplua/typespec-emit-csharp": "file:./emitters/csharp",
     "@ancplua/typespec-emit-ts-types": "file:./emitters/ts-types",
-    "@ancplua/typespec-otelconventions-lint": "file:./emitters/otelconventions-lint",
-    "@qyl/telemetry-control-graph": "file:./emitters/telemetry-control-graph",
-    "@types/node": "25.9.4",
+    "@types/node": "25.9.5",
     "@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/rest": "0.83.0",
     "@typespec/sse": "0.83.0",
-    "@typespec/streams": "0.83.0",
-    "@typespec/versioning": "0.83.0",
-    "typescript": "6.0.3",
-    "vitest": "4.1.9"
+    "typescript": "6.0.3"
   }
 }

package/VERSIONING.md

@@ -1,84 +0,0 @@
-# TypeSpec Versioning In qyl-api-schema
-
-This repository uses `@typespec/versioning` to record when schema elements were added or removed across qyl API versions and OpenTelemetry compatibility-model pins. The annotations live in TypeSpec so schema evolution is reviewable at the contract source.
-
-## Release versioning (the package version)
-
-Separate from the `@typespec/versioning` schema annotations below: the published **package** version
-(npm `@ancplua/qyl-api-schema` and NuGet `Qyl.Api.Contracts`) is **CI-owned and tag-derived** — no
-hand-bumped version lives in any committed file. To cut a release, publish a GitHub Release whose tag
-is `vMAJOR.MINOR.PATCH[-prerelease]`; `publish.yml` strips the leading `v` and stamps that single
-version onto both npm and NuGet (no build metadata — npm rejects it and NuGet strips it), so the two
-registries are lockstep by construction. The committed `package.json` version is the non-authoritative
-placeholder `0.0.0-development`, and `packaging/Qyl.Api.Contracts.csproj` carries no `<Version>`.
-
-## Where it is used
-
-- `models/genai.tsp` for GenAI semantic-convention shaped models
-- `models/db.tsp` for DB semantic-convention shaped models
-- `models/http.tsp` for HTTP semantic-convention shaped models
-- `api/routes.tsp` for API versioning
-
-## Pattern: version registry + annotations
-
-```tsp
-import "@typespec/versioning";
-using TypeSpec.Versioning;
-
-@versioned(GenAiVersions)
-namespace Qyl.Api.Contracts.Domains.AI.GenAi;
-
-enum GenAiVersions {
-  v1_27: "1.27.0",
-  v1_28: "1.28.0",
-  v1_29: "1.29.0",
-  v1_37: "1.37.0",
-  v1_38: "1.38.0",
-  v1_39: "1.39.0",
-  v1_40: "1.40.0",
-  v1_41: "1.41.0",
-}
-
-model GenAiSpanAttributes {
-  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.GenAi.UsageInputTokens)
-  usageInputTokens?: TokenCount;
-
-  @encodedName("application/json", "gen_ai.usage.input_tokens.cached")
-  @added(GenAiVersions.v1_38)
-  usageInputTokensCached?: TokenCount;
-}
-```
-
-Note (v0.3.0): the pre-migration `gen_ai.*` fields that carried upstream-deleted
-wire keys (`gen_ai.system`, `gen_ai.prompt`, `gen_ai.completion`,
-`gen_ai.usage.prompt_tokens` / `.completion_tokens`, and the
-`gen_ai.openai.*` vendor keys) were **removed from the contract surface**
-when the OTel 1.42 GenAI-registry split was adopted. Old-key telemetry is a
-collector *ingestion normalization* concern (mapping below), not a contract
-field.
-
-## Ingestion mapping (deprecated -> current)
-
-Consumers can keep ingestion backward-compatible by normalizing deprecated attribute keys. Keep any downstream mapping aligned with the TypeSpec history.
-
-```csharp
-public static readonly FrozenDictionary<string, string> DeprecatedMappings =
-    new Dictionary<string, string>(StringComparer.Ordinal)
-    {
-        ["gen_ai.system"] = "gen_ai.provider.name",
-        ["gen_ai.usage.prompt_tokens"] = "gen_ai.usage.input_tokens",
-        ["gen_ai.usage.completion_tokens"] = "gen_ai.usage.output_tokens",
-        ["agents.tool.call_id"] = "gen_ai.tool.call.id",
-        ["db.system"] = "db.system.name"
-    }.ToFrozenDictionary(StringComparer.Ordinal);
-```
-
-Downstream consumers should cover these mappings in ingestion tests.
-
-## Workflow for schema evolution
-
-- Add a new version entry to the enum in the owning namespace.
-- Mark additions and removals with `@added` and `@removed`.
-- Update downstream normalization mappings to keep ingestion compatibility.
-- Extend downstream ingestion tests to cover the new mapping.
-- Run `npm run compile` after TypeSpec changes.