@ancplua/qyl-api-schema 0.2.0

package/models/agent/agent-run.tsp

@@ -0,0 +1,154 @@
+// =============================================================================
+// ANcpLua v2.0 - Agent Run Contract Model (OTel v1.40)
+// =============================================================================
+// Agent run records extracted from OTLP spans.
+// Maps OTel GenAI semantic convention attributes to qyl API contract fields.
+//
+// OTel semconv mapping:
+//   gen_ai.agent.name        → agent_name
+//   gen_ai.agent.id          → agent_id
+//   gen_ai.agent.description → agent_description
+//   gen_ai.operation.name    → operation_name
+//   gen_ai.request.model     → gen_ai_request_model
+//   gen_ai.provider.name     → gen_ai_provider_name
+//   gen_ai.usage.input_tokens  → gen_ai_input_tokens
+//   gen_ai.usage.output_tokens → gen_ai_output_tokens
+// =============================================================================
+
+import "@typespec/openapi";
+import "../../common/types.tsp";
+import "../../otel/enums.tsp";
+
+using TypeSpec.OpenAPI;
+using Qyl.Api.Contracts.Common;
+using Qyl.Api.Contracts.OTel.Enums;
+
+namespace Qyl.Api.Contracts.Domains.Agent.Run;
+
+// =============================================================================
+// Agent Run Status
+// =============================================================================
+
+@doc("Agent run execution status")
+enum AgentRunStatus {
+  @doc("Agent is currently executing")
+  running: "running",
+
+  @doc("Agent completed successfully")
+  completed: "completed",
+
+  @doc("Agent execution failed")
+  failed: "failed",
+
+  @doc("Agent execution was cancelled")
+  cancelled: "cancelled",
+}
+
+// =============================================================================
+// Agent Run Entity
+// =============================================================================
+
+@doc("Agent run entity materialized from OTLP spans with gen_ai.agent.* attributes")
+@TypeSpec.OpenAPI.extension("x-csharp-type", "AgentRunEntity")
+model AgentRunEntity {
+  // === Identifiers ===
+
+  @doc("Unique agent run identifier")
+  @key
+  runId: string;
+
+  @doc("Parent OTel trace identifier")
+  traceId: TraceId;
+
+  @doc("Root span ID of the agent invocation")
+  spanId?: SpanId;
+
+  @doc("Parent run ID for nested agent invocations")
+  parentRunId?: string;
+
+  @doc("Session identifier for grouping related runs")
+  sessionId?: SessionId;
+
+  // === Agent Identity (OTel gen_ai.agent.*) ===
+
+  @doc("Agent name - OTel: gen_ai.agent.name")
+  @TypeSpec.OpenAPI.extension("x-promoted", true)
+  agentName: string;
+
+  @doc("Agent identifier - OTel: gen_ai.agent.id")
+  @TypeSpec.OpenAPI.extension("x-promoted", true)
+  agentId?: string;
+
+  @doc("Agent description - OTel: gen_ai.agent.description")
+  @TypeSpec.OpenAPI.extension("x-promoted", true)
+  agentDescription?: string;
+
+  // === GenAI Attributes (OTel gen_ai.*) ===
+
+  @doc("Operation name - OTel: gen_ai.operation.name")
+  @TypeSpec.OpenAPI.extension("x-promoted", true)
+  operationName?: string;
+
+  @doc("LLM model used - OTel: gen_ai.request.model")
+  @TypeSpec.OpenAPI.extension("x-promoted", true)
+  genAiRequestModel?: string;
+
+  @doc("Provider name - OTel: gen_ai.provider.name")
+  @TypeSpec.OpenAPI.extension("x-promoted", true)
+  genAiProviderName?: string;
+
+  // === Execution State ===
+
+  @doc("Execution status")
+  status: AgentRunStatus;
+
+  // === Token Usage (OTel gen_ai.usage.*) ===
+
+  @doc("Input/prompt tokens - OTel: gen_ai.usage.input_tokens")
+  @TypeSpec.OpenAPI.extension("x-promoted", true)
+  genAiInputTokens?: TokenCount;
+
+  @doc("Output/completion tokens - OTel: gen_ai.usage.output_tokens")
+  @TypeSpec.OpenAPI.extension("x-promoted", true)
+  genAiOutputTokens?: TokenCount;
+
+  @doc("Estimated cost in USD")
+  @TypeSpec.OpenAPI.extension("x-promoted", true)
+  genAiCostUsd?: CostUsd;
+
+  @doc("Number of tool calls made")
+  toolCallCount?: int32;
+
+  // === Timing ===
+
+  @doc("Start timestamp in nanoseconds since epoch")
+  startTimeUnixNano: UnixNanos;
+
+  @doc("End timestamp in nanoseconds since epoch")
+  endTimeUnixNano?: UnixNanos;
+
+  @doc("Duration in nanoseconds")
+  durationNs?: DurationNs;
+
+  // === Service Info ===
+
+  @doc("Service name from resource attributes")
+  @TypeSpec.OpenAPI.extension("x-promoted", true)
+  serviceName?: string;
+
+  // === Error ===
+
+  @doc("Error message if failed")
+  errorMessage?: string;
+
+  // === Attributes (JSON Blobs) ===
+
+  @doc("Additional attributes as JSON")
+  attributesJson?: string;
+
+  // === Internal ===
+
+  @doc("Row creation timestamp")
+  @TypeSpec.OpenAPI.extension("x-internal", true)
+  createdAt?: utcDateTime;
+}

package/models/agent/tool-call.tsp

@@ -0,0 +1,122 @@
+// =============================================================================
+// ANcpLua v2.0 - Tool Call Contract Model (OTel v1.40)
+// =============================================================================
+// Tool call records extracted from OTLP spans.
+// Maps OTel GenAI tool semantic convention attributes to qyl API contract fields.
+//
+// OTel semconv mapping:
+//   gen_ai.tool.name           → tool_name
+//   gen_ai.tool.type           → tool_type
+//   gen_ai.tool.call.id        → call_id
+//   gen_ai.tool.call.arguments → arguments_json
+//   gen_ai.tool.call.result    → result_json
+//   gen_ai.tool.description    → tool_description
+//   gen_ai.operation.name      → operation_name (= "execute_tool")
+// =============================================================================
+
+import "@typespec/openapi";
+import "../../common/types.tsp";
+import "../../otel/enums.tsp";
+
+using TypeSpec.OpenAPI;
+using Qyl.Api.Contracts.Common;
+using Qyl.Api.Contracts.OTel.Enums;
+
+namespace Qyl.Api.Contracts.Domains.Agent.ToolCall;
+
+// =============================================================================
+// Tool Call Status
+// =============================================================================
+
+@doc("Tool call execution status")
+enum ToolCallStatus {
+  @doc("Tool is currently executing")
+  running: "running",
+
+  @doc("Tool completed successfully")
+  completed: "completed",
+
+  @doc("Tool execution failed")
+  failed: "failed",
+}
+
+// =============================================================================
+// Tool Call Entity
+// =============================================================================
+
+@doc("Tool call entity materialized from OTLP spans with gen_ai.tool.* attributes")
+@TypeSpec.OpenAPI.extension("x-csharp-type", "ToolCallEntity")
+model ToolCallEntity {
+  // === Identifiers ===
+
+  @doc("Unique tool call identifier - OTel: gen_ai.tool.call.id")
+  @key
+  @TypeSpec.OpenAPI.extension("x-promoted", true)
+  callId: string;
+
+  @doc("Parent agent run identifier")
+  runId: string;
+
+  @doc("Parent OTel trace identifier")
+  traceId: TraceId;
+
+  @doc("Associated OTel span identifier")
+  spanId: SpanId;
+
+  // === Tool Identity (OTel gen_ai.tool.*) ===
+
+  @doc("Tool name - OTel: gen_ai.tool.name (e.g., 'Read', 'Bash', 'Edit', 'TodoWrite')")
+  @TypeSpec.OpenAPI.extension("x-promoted", true)
+  toolName: string;
+
+  @doc("Tool type categorization - OTel: gen_ai.tool.type (e.g., 'function', 'extension')")
+  @TypeSpec.OpenAPI.extension("x-promoted", true)
+  toolType?: string;
+
+  @doc("Tool description - OTel: gen_ai.tool.description")
+  @TypeSpec.OpenAPI.extension("x-promoted", true)
+  toolDescription?: string;
+
+  // === Tool Call Data (OTel gen_ai.tool.call.*) ===
+
+  @doc("Tool input arguments as JSON - OTel: gen_ai.tool.call.arguments")
+  @TypeSpec.OpenAPI.extension("x-promoted", true)
+  argumentsJson?: string;
+
+  @doc("Tool output result as JSON - OTel: gen_ai.tool.call.result")
+  @TypeSpec.OpenAPI.extension("x-promoted", true)
+  resultJson?: string;
+
+  // === Execution State ===
+
+  @doc("Execution status")
+  status: ToolCallStatus;
+
+  // === Timing ===
+
+  @doc("Tool call start time in nanoseconds since epoch")
+  startTimeUnixNano: UnixNanos;
+
+  @doc("Tool call end time in nanoseconds since epoch")
+  endTimeUnixNano?: UnixNanos;
+
+  @doc("Duration in nanoseconds")
+  durationNs?: DurationNs;
+
+  // === Error ===
+
+  @doc("Error message if failed")
+  errorMessage?: string;
+
+  // === Ordering ===
+
+  @doc("Execution order within the agent run")
+  @minValue(0)
+  sequenceNumber: int32;
+
+  // === Internal ===
+
+  @doc("Row creation timestamp")
+  @TypeSpec.OpenAPI.extension("x-internal", true)
+  createdAt?: utcDateTime;
+}

package/models/agent/workflow-checkpoint.tsp

@@ -0,0 +1,50 @@
+// =============================================================================
+// ANcpLua v2.0 - Workflow Checkpoint Contract Model (OTel v1.40)
+// =============================================================================
+// Checkpoint state persistence for workflow execution recovery.
+// Enables resume-from-checkpoint after failures or cancellations.
+// =============================================================================
+
+import "@typespec/openapi";
+import "../../common/types.tsp";
+
+using TypeSpec.OpenAPI;
+using Qyl.Api.Contracts.Common;
+
+namespace Qyl.Api.Contracts.Domains.Agent.Checkpoint;
+
+// =============================================================================
+// Workflow Checkpoint Entity
+// =============================================================================
+
+@doc("Workflow checkpoint entity for persisting workflow node state for recovery")
+@TypeSpec.OpenAPI.extension("x-csharp-type", "WorkflowCheckpointEntity")
+model WorkflowCheckpointEntity {
+  // === Identifiers ===
+
+  @doc("Unique checkpoint identifier")
+  @key
+  checkpointId: string;
+
+  @doc("Parent workflow execution identifier")
+  executionId: string;
+
+  // === Node State ===
+
+  @doc("Workflow node identifier")
+  nodeId: string;
+
+  @doc("Serialized node state as JSON")
+  stateJson: string;
+
+  // === Ordering ===
+
+  @doc("Checkpoint sequence number within the execution")
+  @minValue(0)
+  sequenceNumber: int32;
+
+  // === Timing ===
+
+  @doc("Checkpoint creation time in nanoseconds since epoch")
+  createdAtUnixNano: UnixNanos;
+}

package/models/agent/workflow-execution.tsp

@@ -0,0 +1,136 @@
+// =============================================================================
+// ANcpLua v2.0 - Workflow Execution Contract Model (OTel v1.40)
+// =============================================================================
+// Workflow execution tracking for multi-step AI agent workflows.
+// Defines the public qyl workflow execution contract.
+// =============================================================================
+
+import "@typespec/openapi";
+import "../../common/types.tsp";
+import "../../otel/enums.tsp";
+
+using TypeSpec.OpenAPI;
+using Qyl.Api.Contracts.Common;
+using Qyl.Api.Contracts.OTel.Enums;
+
+namespace Qyl.Api.Contracts.Domains.Agent.Workflow;
+
+// =============================================================================
+// Workflow Execution Status
+// =============================================================================
+
+@doc("Workflow execution status")
+enum WorkflowExecutionStatus {
+  @doc("Workflow is pending execution")
+  pending: "pending",
+
+  @doc("Workflow is currently running")
+  running: "running",
+
+  @doc("Workflow completed successfully")
+  completed: "completed",
+
+  @doc("Workflow execution failed")
+  failed: "failed",
+
+  @doc("Workflow execution was cancelled")
+  cancelled: "cancelled",
+}
+
+// =============================================================================
+// Workflow Trigger Type
+// =============================================================================
+
+@doc("What triggered a workflow execution")
+enum WorkflowTrigger {
+  @doc("Manually triggered by user or agent")
+  manual: "manual",
+
+  @doc("Triggered by schedule/cron")
+  schedule: "schedule",
+
+  @doc("Triggered by event (e.g., error, alert)")
+  event: "event",
+
+  @doc("Triggered by another workflow")
+  workflow: "workflow",
+}
+
+// =============================================================================
+// Workflow Execution Entity
+// =============================================================================
+
+@doc("Workflow execution entity for tracking multi-step agent workflows")
+@TypeSpec.OpenAPI.extension("x-csharp-type", "WorkflowExecutionEntity")
+model WorkflowExecutionEntity {
+  // === Identifiers ===
+
+  @doc("Unique execution identifier")
+  @key
+  executionId: string;
+
+  @doc("Associated OTel trace identifier")
+  traceId?: TraceId;
+
+  // === Workflow Identity ===
+
+  @doc("Workflow name identifier")
+  workflowName: string;
+
+  @doc("What triggered the workflow")
+  trigger: WorkflowTrigger;
+
+  // === Execution State ===
+
+  @doc("Execution status")
+  status: WorkflowExecutionStatus;
+
+  // === I/O ===
+
+  @doc("Workflow input as JSON")
+  inputJson?: string;
+
+  @doc("Workflow output as JSON")
+  outputJson?: string;
+
+  // === Token Usage (OTel gen_ai.usage.*) ===
+
+  @doc("Total input tokens - OTel: gen_ai.usage.input_tokens")
+  genAiInputTokens?: TokenCount;
+
+  @doc("Total output tokens - OTel: gen_ai.usage.output_tokens")
+  genAiOutputTokens?: TokenCount;
+
+  @doc("Estimated cost in USD")
+  genAiCostUsd?: CostUsd;
+
+  // === Progress ===
+
+  @doc("Total number of workflow nodes")
+  nodeCount?: int32;
+
+  @doc("Number of completed nodes")
+  completedNodes?: int32;
+
+  // === Timing ===
+
+  @doc("Start timestamp in nanoseconds since epoch")
+  startTimeUnixNano: UnixNanos;
+
+  @doc("End timestamp in nanoseconds since epoch")
+  endTimeUnixNano?: UnixNanos;
+
+  @doc("Duration in nanoseconds")
+  durationNs?: DurationNs;
+
+  // === Error ===
+
+  @doc("Error message if failed")
+  errorMessage?: string;
+
+  // === Internal ===
+
+  @doc("Row creation timestamp")
+  @TypeSpec.OpenAPI.extension("x-internal", true)
+  createdAt?: utcDateTime;
+}