@clowder-ai/plugin-contract 0.1.0-beta.2 → 0.1.0-beta.20

package/src/schemas/companion-bridge.schema.json

@@ -0,0 +1,937 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://clowder-ai.dev/schemas/companion-bridge/v1",
+  "title": "Desktop companion renderer bridge",
+  "description": "Closed package presentation bridge. The Host-owned isolated preload owns WebRTC, microphone playback and its receive-only provider data channel. Packages never provide SDP, get a peer/channel handle, or send provider events. Host binds owner, installation and conversation; the trusted executor requires explicit gestures for voice and screen admission. Renderer screen observations remain untrusted. No new M0 methods.",
+  "$defs": {
+    "CompanionSelectionId": {
+      "type": "string",
+      "pattern": "^[a-zA-Z0-9_-]{1,160}$"
+    },
+    "CompanionScreenFrame": {
+      "type": "object",
+      "properties": {
+        "image": {
+          "type": "string",
+          "maxLength": 1400000,
+          "pattern": "^data:image/(jpeg|png|webp);base64,"
+        },
+        "width": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1600
+        },
+        "height": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1600
+        },
+        "frameId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 160
+        },
+        "sourceLabel": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "observedAt": {
+          "type": "number",
+          "minimum": 0
+        }
+      },
+      "required": [
+        "image",
+        "width",
+        "height",
+        "frameId",
+        "sourceLabel",
+        "observedAt"
+      ],
+      "additionalProperties": false
+    },
+    "CompanionCommand": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "state"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "prepare"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "audio.connect"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "audio.close"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "audio.microphone"
+            },
+            "muted": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "kind",
+            "muted"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "audio.speaker"
+            },
+            "muted": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "kind",
+            "muted"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "stop"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "text"
+            },
+            "text": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 8000
+            },
+            "clientMessageId": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          "required": [
+            "kind",
+            "text",
+            "clientMessageId"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "documents"
+            },
+            "allowed": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "kind",
+            "allowed"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "screen.pick"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "screen.open"
+            },
+            "selectionId": {
+              "$ref": "#/$defs/CompanionSelectionId"
+            },
+            "label": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 256
+            }
+          },
+          "required": [
+            "kind",
+            "selectionId",
+            "label"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "screen.frame"
+            },
+            "selectionId": {
+              "$ref": "#/$defs/CompanionSelectionId"
+            },
+            "frame": {
+              "$ref": "#/$defs/CompanionScreenFrame"
+            }
+          },
+          "required": [
+            "kind",
+            "selectionId",
+            "frame"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "screen.close"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "conversation.open"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": { "const": "decisions.read" },
+            "offset": { "type": "integer", "minimum": 0 },
+            "limit": { "type": "integer", "minimum": 1, "maximum": 20 }
+          },
+          "required": ["kind", "offset", "limit"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": { "const": "f221.inspect" },
+            "proposalId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,200}$" }
+          },
+          "required": ["kind", "proposalId"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "view.resize"
+            },
+            "expanded": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "kind",
+            "expanded"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "view.layout"
+            },
+            "panel": {
+              "enum": [
+                "none",
+                "bubble",
+                "actions",
+                "menu",
+                "chat",
+                "decisions"
+              ]
+            },
+            "width": {
+              "type": "integer",
+              "minimum": 120,
+              "maximum": 420
+            },
+            "height": {
+              "type": "integer",
+              "minimum": 32,
+              "maximum": 500
+            }
+          },
+          "required": [
+            "kind",
+            "panel",
+            "width",
+            "height"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "view.drag"
+            },
+            "phase": {
+              "enum": [
+                "start",
+                "end"
+              ]
+            }
+          },
+          "required": [
+            "kind",
+            "phase"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "view.hide"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "conversation.read"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "CompanionActor": {
+      "type": "object",
+      "properties": {
+        "catId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 160
+        },
+        "displayName": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        }
+      },
+      "required": [
+        "catId",
+        "displayName"
+      ],
+      "additionalProperties": false
+    },
+    "CompanionLiveTransport": {
+      "type": "object",
+      "properties": {
+        "kind": { "const": "gpt_live_v3" },
+        "verifiedModel": { "type": "null" }
+      },
+      "required": ["kind", "verifiedModel"],
+      "additionalProperties": false
+    },
+    "CompanionNativeWorkEntry": {
+      "type": "object",
+      "properties": {
+        "taskId": { "type": "string", "minLength": 1, "maxLength": 500 },
+        "nativeTurnId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,160}$" },
+        "kind": { "enum": ["reasoning", "tool", "workspace_fetch", "workspace_dispatch", "screen_read"] },
+        "startedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+        "expiresAt": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }
+      },
+      "required": ["taskId", "nativeTurnId", "kind", "startedAt", "expiresAt"],
+      "additionalProperties": false
+    },
+    "CompanionNativeWorkEvent": {
+      "type": "object",
+      "properties": {
+        "eventId": { "type": "string", "minLength": 1, "maxLength": 500 },
+        "taskId": { "type": "string", "minLength": 1, "maxLength": 500 },
+        "kind": { "enum": ["reasoning", "tool", "workspace_fetch", "workspace_dispatch", "screen_read", "result"] },
+        "phase": { "enum": ["started", "completed", "failed", "cancelled", "expired", "result_handed_to_voice"] },
+        "occurredAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+        "expiresAt": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
+        "resultId": { "type": "string", "minLength": 1, "maxLength": 500 },
+        "nativeCarrierCatId": { "type": "string", "minLength": 1, "maxLength": 160 }
+      },
+      "required": ["eventId", "taskId", "kind", "phase", "occurredAt", "expiresAt"],
+      "additionalProperties": false
+    },
+    "CompanionNativeWork": {
+      "type": "object",
+      "properties": {
+        "scopeId": { "type": ["string", "null"], "pattern": "^[0-9a-f]{16}$" },
+        "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+        "active": { "type": "array", "maxItems": 64, "items": { "$ref": "#/$defs/CompanionNativeWorkEntry" } },
+        "recent": { "type": "array", "maxItems": 16, "items": { "$ref": "#/$defs/CompanionNativeWorkEvent" } }
+      },
+      "required": ["scopeId", "revision", "active", "recent"],
+      "additionalProperties": false
+    },
+    "CompanionState": {
+      "type": "object",
+      "properties": {
+        "kind": {
+          "const": "state"
+        },
+        "phase": {
+          "enum": [
+            "idle",
+            "preparing",
+            "ready",
+            "connecting",
+            "talking",
+            "closed",
+            "failed"
+          ]
+        },
+        "displayName": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "skin": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "duty": {
+          "$ref": "#/$defs/CompanionActor"
+        },
+        "carrier": {
+          "$ref": "#/$defs/CompanionActor"
+        },
+        "documentsAllowed": {
+          "type": "boolean"
+        },
+        "toolsReady": {
+          "type": "boolean"
+        },
+        "nativeActivity": {
+          "enum": ["none", "reasoning", "tool_running"]
+        },
+        "liveTransport": {
+          "$ref": "#/$defs/CompanionLiveTransport"
+        },
+        "nativeWork": {
+          "$ref": "#/$defs/CompanionNativeWork"
+        }
+      },
+      "required": [
+        "kind",
+        "phase",
+        "displayName",
+        "skin",
+        "duty",
+        "carrier",
+        "documentsAllowed",
+        "toolsReady",
+        "nativeActivity",
+        "liveTransport",
+        "nativeWork"
+      ],
+      "additionalProperties": false
+    },
+    "CompanionDecisions": {
+      "type": "object",
+      "properties": {
+        "kind": { "const": "decisions" },
+        "status": { "enum": ["available", "unavailable"] },
+        "approvalCount": { "type": ["integer", "null"], "minimum": 0 },
+        "needsMeCount": { "type": ["integer", "null"], "minimum": 0 },
+        "otherNeedsMeCount": { "type": ["integer", "null"], "minimum": 0 },
+        "approvals": {
+          "type": "array",
+          "maxItems": 20,
+          "items": {
+            "type": "object",
+            "properties": {
+              "proposalId": { "type": "string", "minLength": 1, "maxLength": 200 },
+              "sourceFeatureId": { "type": "string", "minLength": 1, "maxLength": 40 },
+              "summary": { "type": "string", "maxLength": 500 },
+              "resolution": { "enum": ["open", "accepted", "rejected", "closed_without_decision"] },
+              "materializationState": { "enum": ["not_started", "outcome_unknown", "in_progress", "succeeded", "failed"] },
+              "linkedNeedsMe": { "type": "boolean" }
+            },
+            "required": ["proposalId", "sourceFeatureId", "summary", "resolution", "materializationState", "linkedNeedsMe"],
+            "additionalProperties": false
+          }
+        },
+        "otherNeedsMe": {
+          "type": "array",
+          "maxItems": 20,
+          "items": {
+            "type": "object",
+            "properties": {
+              "subjectRef": { "type": "string", "minLength": 1, "maxLength": 256 },
+              "summary": { "type": "string", "maxLength": 500 }
+            },
+            "required": ["subjectRef", "summary"],
+            "additionalProperties": false
+          }
+        },
+        "page": {
+          "type": "object",
+          "properties": {
+            "offset": { "type": "integer", "minimum": 0 },
+            "limit": { "type": "integer", "minimum": 1, "maximum": 20 },
+            "hasMoreApprovals": { "type": "boolean" },
+            "hasMoreNeedsMe": { "type": "boolean" }
+          },
+          "required": ["offset", "limit", "hasMoreApprovals", "hasMoreNeedsMe"],
+          "additionalProperties": false
+        }
+      },
+      "required": ["kind", "status", "approvalCount", "needsMeCount", "otherNeedsMeCount", "approvals", "otherNeedsMe", "page"],
+      "additionalProperties": false
+    },
+    "CompanionDecisionTrial": {
+      "type": "object",
+      "properties": {
+        "kind": { "const": "decision-trial" },
+        "status": { "enum": ["dismissed", "trial_confirmed", "stale", "unavailable"] }
+      },
+      "required": ["kind", "status"],
+      "additionalProperties": false
+    },
+    "CompanionErrorCode": {
+      "enum": [
+        "invalid_request",
+        "permission_required",
+        "unavailable",
+        "session_required",
+        "busy",
+        "selection_changed",
+        "carrier_unavailable",
+        "cancelled",
+        "unconfirmed"
+      ]
+    },
+    "CompanionReply": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "ok"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "$ref": "#/$defs/CompanionState"
+        },
+        {
+          "$ref": "#/$defs/CompanionDecisions"
+        },
+        {
+          "$ref": "#/$defs/CompanionDecisionTrial"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "delivery"
+            },
+            "delivery": {
+              "enum": [
+                "accepted",
+                "unconfirmed"
+              ]
+            }
+          },
+          "required": [
+            "kind",
+            "delivery"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "selection"
+            },
+            "selectionId": {
+              "$ref": "#/$defs/CompanionSelectionId"
+            }
+          },
+          "required": [
+            "kind",
+            "selectionId"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "navigation"
+            },
+            "delivery": {
+              "enum": [
+                "requested",
+                "unconfirmed"
+              ]
+            }
+          },
+          "required": [
+            "kind",
+            "delivery"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "error"
+            },
+            "code": {
+              "$ref": "#/$defs/CompanionErrorCode"
+            }
+          },
+          "required": [
+            "kind",
+            "code"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "layout"
+            },
+            "pet": {
+              "type": "object",
+              "properties": {
+                "x": {
+                  "type": "number"
+                },
+                "y": {
+                  "type": "number"
+                }
+              },
+              "required": [
+                "x",
+                "y"
+              ],
+              "additionalProperties": false
+            },
+            "panel": {
+              "type": "object",
+              "properties": {
+                "x": {
+                  "type": "number"
+                },
+                "y": {
+                  "type": "number"
+                },
+                "width": {
+                  "type": "number",
+                  "minimum": 0,
+                  "maximum": 2000
+                },
+                "height": {
+                  "type": "number",
+                  "minimum": 0,
+                  "maximum": 2000
+                }
+              },
+              "required": [
+                "x",
+                "y",
+                "width",
+                "height"
+              ],
+              "additionalProperties": false
+            },
+            "width": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 2000
+            },
+            "height": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 2000
+            }
+          },
+          "required": [
+            "kind",
+            "pet",
+            "panel",
+            "width",
+            "height"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "conversation"
+            },
+            "threadTitle": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 256
+            },
+            "messages": {
+              "type": "array",
+              "maxItems": 32,
+              "items": {
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "maxLength": 256
+                  },
+                  "role": {
+                    "enum": [
+                      "user",
+                      "assistant"
+                    ]
+                  },
+                  "text": {
+                    "type": "string",
+                    "maxLength": 16000
+                  },
+                  "name": {
+                    "type": "string",
+                    "maxLength": 256
+                  }
+                },
+                "required": [
+                  "id",
+                  "role",
+                  "text",
+                  "name"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "hasMore": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "kind",
+            "threadTitle",
+            "messages",
+            "hasMore"
+          ],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "CompanionEvent": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "media-stopped"
+            },
+            "reason": {
+              "enum": [
+                "locked",
+                "suspended",
+                "hidden",
+                "closed",
+                "revoked"
+              ]
+            }
+          },
+          "required": [
+            "kind",
+            "reason"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "audio"
+            },
+            "type": {
+              "enum": [
+                "connected",
+                "recovering",
+                "recovered",
+                "error"
+              ]
+            }
+          },
+          "required": [
+            "kind",
+            "type"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "audio"
+            },
+            "type": {
+              "const": "transcript"
+            },
+            "role": {
+              "enum": [
+                "user",
+                "assistant"
+              ]
+            },
+            "text": {
+              "type": "string",
+              "maxLength": 16000
+            },
+            "turnId": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 256
+            },
+            "itemId": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 256
+            }
+          },
+          "required": [
+            "kind",
+            "type",
+            "role",
+            "text"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "audio"
+            },
+            "type": {
+              "const": "turn-done"
+            },
+            "role": {
+              "enum": [
+                "user",
+                "assistant"
+              ]
+            },
+            "transcript": {
+              "type": "string",
+              "maxLength": 16000
+            },
+            "turnId": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 256
+            }
+          },
+          "required": [
+            "kind",
+            "type"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "const": "view-dismiss"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "additionalProperties": false
+        }
+      ]
+    }
+  }
+}