chat-send.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://opensquilla.dev/contracts/gateway/v4/conversation/chat-send.schema.json",
  "title": "OpenSquilla chat.send Contract",
  "description": "Language-neutral Contract for the v4 chat.send command. The schema documents the stable ingress fields while retaining open additive fields and legacy aliases. Generated wire types are adapter-only.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "request": { "$ref": "#/$defs/ChatSendRequestFrame" },
    "response": { "$ref": "#/$defs/ChatSendResponseFrame" }
  },
  "x-opensquilla-wire": {
    "protocol": "opensquilla-websocket-json",
    "version": 4,
    "compatibility": "exact-json-tree"
  },
  "x-opensquilla-codegen": {
    "python": { "tool": "datamodel-code-generator", "version": "0.75.1", "target": "pydantic_v2.BaseModel" },
    "typescript": { "tool": "json-schema-to-typescript", "version": "15.0.4" },
    "runtimeValidation": { "tool": "ajv", "version": "8.17.1", "mode": "standalone-adapter-only" }
  },
  "x-opensquilla-method": {
    "name": "chat.send",
    "kind": "command",
    "scope": "operator.write",
    "guestAllowed": true,
    "idempotency": "idempotent",
    "timeout": { "policy": "caller" },
    "capability": { "kind": "method-availability", "name": "chat.send" },
    "request": "#/$defs/ChatSendRequestFrame",
    "params": "#/$defs/ChatSendParams",
    "response": "#/$defs/ChatSendResponseFrame",
    "result": "#/$defs/ChatSendResult",
    "errors": [
      { "code": "INVALID_PARAMS" },
      { "code": "INVALID_REQUEST" },
      { "code": "UNAUTHORIZED" },
      { "code": "UNAVAILABLE", "retryable": true },
      { "code": "STORAGE_BUSY", "retryable": true, "retryAfterMs": true, "details": true },
      { "code": "QUEUE_FULL", "retryable": true },
      { "code": "QUEUE_FULL_DIRTY", "retryable": false, "details": true },
      { "code": "SESSION_CHANGED", "retryable": true },
      { "code": "IDEMPOTENCY_CONFLICT", "retryable": false },
      { "code": "META_CONTROL_CONFLICT", "retryable": false },
      { "code": "COLLECT_RACE", "retryable": true },
      { "code": "SESSION_CONFLICT", "retryable": true },
      { "code": "INTERNAL_ERROR" }
    ]
  },
  "$defs": {
    "ChatSendSource": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "elevated": { "type": ["string", "null"] },
        "runMode": { "type": ["string", "null"] },
        "run_mode": { "type": ["string", "null"] },
        "noMemoryCapture": { "type": ["boolean", "null"] },
        "no_memory_capture": { "type": ["boolean", "null"] }
      }
    },
    "ChatSendAttachment": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "type": { "type": "string" },
        "mime": { "type": "string" },
        "mime_type": { "type": "string" },
        "name": { "type": "string" },
        "filename": { "type": "string" },
        "data": { "type": ["string", "null"] },
        "file_uuid": { "type": ["string", "null"] },
        "size": { "type": ["integer", "null"], "minimum": 0 }
      }
    },
    "ChatSendParams": {
      "title": "chat.send params",
      "description": "Stable chat ingress fields. The Gateway continues to accept snake/camel aliases and additive implementation-specific fields.",
      "type": "object",
      "additionalProperties": true,
      "required": ["message"],
      "properties": {
        "message": { "type": "string" },
        "sessionKey": { "type": "string" },
        "session_key": { "type": "string" },
        "key": { "type": "string" },
        "clientRequestId": { "type": ["string", "null"] },
        "client_request_id": { "type": ["string", "null"] },
        "clientMessageId": { "type": ["string", "null"] },
        "client_message_id": { "type": ["string", "null"] },
        "promptAnnotationIds": { "type": ["array", "null"], "items": { "type": "string" } },
        "prompt_annotation_ids": { "type": ["array", "null"], "items": { "type": "string" } },
        "documentContext": { "type": ["object", "null"], "additionalProperties": true },
        "document_context": { "type": ["object", "null"], "additionalProperties": true },
        "_source": { "anyOf": [{ "$ref": "#/$defs/ChatSendSource" }, { "type": "null" }] },
        "intent": { "type": ["string", "null"] },
        "workspaceId": { "type": ["string", "null"] },
        "workspace_id": { "type": ["string", "null"] },
        "collaborationMode": { "type": ["string", "null"] },
        "collaboration_mode": { "type": ["string", "null"] },
        "initialRoutingMode": { "type": ["string", "null"] },
        "initial_routing_mode": { "type": ["string", "null"] },
        "forkBeforeMessageId": { "type": ["string", "null"] },
        "fork_before_message_id": { "type": ["string", "null"] },
        "displayText": { "type": ["string", "null"] },
        "display_text": { "type": ["string", "null"] },
        "attachments": { "type": ["array", "null"], "items": { "$ref": "#/$defs/ChatSendAttachment" } }
      }
    },
    "ChatSendLegacyNonObjectParams": {
      "description": "v4 ReqFrame.params remains Any; malformed non-object values are forwarded so the existing handler preserves its validation/error behavior.",
      "anyOf": [
        { "type": "array", "items": {} },
        { "type": "string" },
        { "type": "number" },
        { "type": "boolean" }
      ]
    },
    "ChatSendRequestFrame": {
      "type": "object",
      "additionalProperties": false,
      "required": ["type", "id", "method"],
      "properties": {
        "type": { "const": "req" },
        "id": { "type": "string" },
        "method": { "const": "chat.send" },
        "params": {
          "anyOf": [
            { "$ref": "#/$defs/ChatSendParams" },
            { "$ref": "#/$defs/ChatSendLegacyNonObjectParams" },
            { "type": "null" }
          ]
        }
      }
    },
    "ChatSendResult": {
      "title": "chat.send result",
      "description": "The acceptance response is intentionally open: deployments may add task, replay, terminal, or attachment fields without changing the v4 tree.",
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "ok": { "type": ["boolean", "null"] },
        "status": { "type": ["string", "null"] },
        "sessionKey": { "type": ["string", "null"] },
        "session_key": { "type": ["string", "null"] },
        "key": { "type": ["string", "null"] },
        "message_id": { "type": ["string", "null"] },
        "user_message_id": { "type": ["string", "null"] },
        "client_message_id": { "type": ["string", "null"] },
        "clientMessageId": { "type": ["string", "null"] },
        "task_id": { "type": ["string", "null"] },
        "taskId": { "type": ["string", "null"] },
        "replayed": { "type": ["boolean", "null"] },
        "instant_accept": { "type": ["boolean", "null"] },
        "task_status": { "type": ["string", "null"] },
        "taskStatus": { "type": ["string", "null"] },
        "terminal_reason": { "type": ["string", "null"] },
        "terminalReason": { "type": ["string", "null"] },
        "terminal_message": { "type": ["string", "null"] },
        "terminalMessage": { "type": ["string", "null"] },
        "reason": { "type": ["string", "null"] },
        "acceptedPromptAnnotationIds": { "type": ["array", "null"], "items": { "type": "string" } },
        "accepted_prompt_annotation_ids": { "type": ["array", "null"], "items": { "type": "string" } }
      }
    },
    "RpcError": {
      "type": "object",
      "additionalProperties": true,
      "required": ["code", "message"],
      "properties": {
        "code": { "type": "string" },
        "message": { "type": "string" },
        "details": {},
        "retryable": { "type": ["boolean", "null"] },
        "retry_after_ms": { "type": ["integer", "null"], "minimum": 0 },
        "accepted": { "type": ["boolean", "null"] }
      }
    },
    "ChatSendOkResponseFrame": {
      "type": "object",
      "additionalProperties": false,
      "required": ["type", "id", "ok", "payload"],
      "properties": {
        "type": { "const": "res" },
        "id": { "type": "string" },
        "ok": { "const": true },
        "payload": { "$ref": "#/$defs/ChatSendResult" },
        "error": { "type": "null" }
      }
    },
    "ChatSendErrorResponseFrame": {
      "type": "object",
      "additionalProperties": false,
      "required": ["type", "id", "ok", "error"],
      "properties": {
        "type": { "const": "res" },
        "id": { "type": "string" },
        "ok": { "const": false },
        "payload": { "type": "null" },
        "error": { "$ref": "#/$defs/RpcError" }
      }
    },
    "ChatSendResponseFrame": {
      "oneOf": [
        { "$ref": "#/$defs/ChatSendOkResponseFrame" },
        { "$ref": "#/$defs/ChatSendErrorResponseFrame" }
      ]
    }
  }
}