canvastty-plugin.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/howdeploy/CanvasTTY/blob/main/docs/canvastty-plugin.schema.json",
  "title": "CanvasTTY plugin manifest (apiVersion 1 and 2)",
  "type": "object",
  "additionalProperties": false,
  "required": ["apiVersion", "id", "name", "version", "description", "permissions", "contributions"],
  "anyOf": [
    { "properties": { "contributions": { "minItems": 1 } } },
    { "required": ["hooks"], "properties": { "hooks": { "minItems": 1 } } },
    { "required": ["services"], "properties": { "services": { "minItems": 1 } } }
  ],
  "if": { "properties": { "apiVersion": { "const": 1 } } },
  "then": { "not": { "required": ["services"] } },
  "properties": {
    "apiVersion": { "enum": [1, 2] },
    "id": { "type": "string", "minLength": 3, "maxLength": 80, "pattern": "^(?!.*\\.\\.)[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$" },
    "name": { "type": "string", "minLength": 1, "maxLength": 80 },
    "version": { "type": "string", "maxLength": 40, "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$" },
    "description": { "type": "string", "minLength": 1, "maxLength": 2000 },
    "description.ru": { "type": "string", "minLength": 1, "maxLength": 2000 },
    "description.en": { "type": "string", "minLength": 1, "maxLength": 2000 },
    "icon": { "type": "string", "minLength": 1, "maxLength": 180, "pattern": "^(?!/)(?!.*\\\\)(?!\\.\\.?/)(?!.*(?:/\\.\\.?/|/\\.\\.?$|//)).+$" },
    "author": { "type": "string", "minLength": 1, "maxLength": 120 },
    "homepage": { "type": "string", "format": "uri", "maxLength": 300, "pattern": "^https?://" },
    "settingsContribution": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$" },
    "coreFiles": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/$defs/moduleAsset" } },
    "modules": { "type": "array", "maxItems": 16, "items": { "$ref": "#/$defs/module" } },
    "platforms": {
      "type": "array",
      "minItems": 1,
      "uniqueItems": true,
      "items": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[a-z0-9][a-z0-9-]{0,31}$" }
    },
    "minHostVersion": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$" },
    "permissions": {
      "type": "array",
      "maxItems": 12,
      "uniqueItems": true,
      "items": { "enum": ["storage", "secrets", "sessions:read", "limits:read", "launcher:open", "external:open", "browser:open", "media:library", "playlists:read", "playlists:write", "hermes:hud", "network", "launch:contribute", "environment:provide", "decision:provide", "tools:agents", "sessions:events", "sessions:read-screen", "sessions:launch", "sessions:control", "cards:decorate", "browser:engine"] }
    },
    "contributions": {
      "type": "array",
      "minItems": 0,
      "maxItems": 32,
      "items": { "$ref": "#/$defs/contribution" }
    },
    "hooks": {
      "type": "array",
      "minItems": 1,
      "maxItems": 16,
      "items": { "$ref": "#/$defs/agentHook" }
    },
    "services": {
      "description": "apiVersion 2 only: bundled single-file services run as separate processes after the user trusts the plugin's native code.",
      "type": "array",
      "minItems": 1,
      "maxItems": 8,
      "items": { "$ref": "#/$defs/service" }
    }
  },
  "$defs": {
    "moduleAsset": {
      "type": "object",
      "additionalProperties": false,
      "required": ["path", "bytes", "sha256"],
      "properties": {
        "path": { "type": "string", "minLength": 1, "maxLength": 180 },
        "bytes": { "type": "integer", "minimum": 0, "maximum": 8388608 },
        "sha256": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" }
      }
    },
    "module": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "title", "defaultSelected", "permissions", "files"],
      "properties": {
        "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$" },
        "title": { "type": "string", "minLength": 1, "maxLength": 80 },
        "description": { "type": "string", "minLength": 1, "maxLength": 240 },
        "defaultSelected": { "type": "boolean" },
        "permissions": {
          "type": "array",
          "maxItems": 12,
          "uniqueItems": true,
          "items": { "enum": ["storage", "secrets", "sessions:read", "limits:read", "launcher:open", "external:open", "browser:open", "media:library", "playlists:read", "playlists:write", "hermes:hud", "network", "launch:contribute", "environment:provide", "decision:provide", "tools:agents", "sessions:events", "sessions:read-screen", "sessions:launch", "sessions:control", "cards:decorate", "browser:engine"] }
        },
        "files": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/$defs/moduleAsset" } }
      }
    },
    "agentHook": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "title", "entry", "providers", "events"],
      "properties": {
        "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$" },
        "title": { "type": "string", "minLength": 1, "maxLength": 80 },
        "description": { "type": "string", "minLength": 1, "maxLength": 240 },
        "entry": { "type": "string", "minLength": 1, "maxLength": 180, "pattern": "^(?!/)(?!.*\\\\)(?!\\.\\.?/)(?!.*(?:/\\.\\.?/|/\\.\\.?$|//)).+\\.(?:js|mjs|cjs)$" },
        "providers": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": { "enum": ["codex", "claude", "qwen", "kimi", "opencode", "hermes", "grok"] }
        },
        "events": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": { "enum": ["session-start", "prompt-submit", "permission-request", "permission-result", "after-tool", "stop", "session-end"] }
        },
        "module": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$" }
      }
    },
    "service": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "title", "entry"],
      "properties": {
        "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$" },
        "title": { "type": "string", "minLength": 1, "maxLength": 80 },
        "description": { "type": "string", "minLength": 1, "maxLength": 240 },
        "entry": { "type": "string", "minLength": 1, "maxLength": 180, "pattern": "^(?!/)(?!.*\\\\)(?!\\.\\.?/)(?!.*(?:/\\.\\.?/|/\\.\\.?$|//)).+\\.(?:js|mjs|cjs)$" },
        "module": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$" },
        "launch": { "$ref": "#/$defs/serviceLaunch" },
        "environments": {
          "description": "Session environments (needs environment:provide; at most 8 kinds per plugin, unique across its services): kinds offered under Where in the launcher; the host calls canvastty.environment.prepare/wrap/resume/release/describe.",
          "type": "array", "minItems": 1, "maxItems": 8,
          "items": { "$ref": "#/$defs/environmentKind" }
        },
        "decide": {
          "description": "Decision hooks (needs decision:provide; at most one service per plugin): the host calls canvastty.decide before local agents' shell and file-writing tool calls run; answers deny, ask or allow (allow counts only after a second confirmation).",
          "type": "object",
          "additionalProperties": false,
          "required": ["events"],
          "properties": {
            "events": { "type": "array", "minItems": 1, "items": { "enum": ["pre-tool"] } },
            "timeoutMs": { "description": "How long the host waits for an answer (the agent's call waits as long); 3000 when omitted.", "type": "integer", "minimum": 1000, "maximum": 60000 },
            "appliesTo": {
              "type": "array", "minItems": 1, "uniqueItems": true,
              "items": { "enum": ["codex", "claude", "qwen", "kimi", "opencode", "hermes", "grok", "omp", "pi", "cursor", "minimax", "devin", "antigravity"] }
            }
          }
        },
        "tools": {
          "description": "Agent tools (needs tools:agents): listed in the canvastty_agents MCP server as <pluginId>__<name> (dots in the id written as _) for sessions whose role is listed; the host calls canvastty.tools.call with the caller's session id.",
          "type": "array", "minItems": 1, "maxItems": 16,
          "items": { "$ref": "#/$defs/agentTool" }
        },
        "cardActions": {
          "description": "Card actions (needs cards:decorate): items in the options menu of matching cards; the host calls canvastty.cards.invoke and shows the answer's message as a toast.",
          "type": "array", "minItems": 1, "maxItems": 8,
          "items": { "$ref": "#/$defs/cardAction" }
        },
        "browserEngine": { "$ref": "#/$defs/browserEngine" }
      }
    },
    "browserEngine": {
      "description": "A browser engine for agents' background tabs (needs browser:engine; ids unique within the plugin). For each such tab the host calls canvastty.browserEngine.openTab { engineId, tabId } and expects { webSocketUrl } (a ws:// CDP endpoint on 127.0.0.1, [::1] or localhost with a port); canvastty.browserEngine.closeTab { engineId, tabId } is a notification. The core decides which tabs use it (only agents' new tabs, never shown, no cookies or profile) and moves a tab to Chromium on screenshots, bot walls, thin text, missing CDP methods, a disconnect, or when the tab is shown.",
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "title"],
      "properties": {
        "id": { "description": "What agents pass as engine to browser_new_tab; never auto or chromium.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$", "not": { "enum": ["auto", "chromium"] } },
        "title": { "type": "string", "minLength": 1, "maxLength": 80 },
        "description": { "type": "string", "minLength": 1, "maxLength": 240 },
        "layout": { "description": "The engine lays pages out for real (boxes and viewport mean something). false or omitted: observation skips geometry and clicks and hovers go through the DOM (element.click()).", "type": "boolean" }
      }
    },
    "agentTool": {
      "type": "object",
      "additionalProperties": false,
      "required": ["name", "description", "inputSchema", "roles"],
      "properties": {
        "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" },
        "description": { "type": "string", "minLength": 1, "maxLength": 1000 },
        "inputSchema": {
          "description": "JSON Schema of the arguments, at most 8 KB; its top level is an object.",
          "type": "object",
          "required": ["type"],
          "properties": { "type": { "const": "object" } }
        },
        "roles": {
          "type": "array", "minItems": 1, "uniqueItems": true,
          "items": { "enum": ["orchestrator", "agent", "subagent"] }
        }
      }
    },
    "cardAction": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "title"],
      "properties": {
        "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$" },
        "title": { "type": "string", "minLength": 1, "maxLength": 40 },
        "when": {
          "description": "Cards the action shows on; every listed key must match. A card outside an environment never matches environmentKinds.",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "providers": {
              "type": "array", "minItems": 1, "maxItems": 16, "uniqueItems": true,
              "items": { "enum": ["terminal", "codex", "claude", "qwen", "kimi", "opencode", "hermes", "grok", "omp", "pi", "cursor", "minimax", "devin", "antigravity"] }
            },
            "environmentKinds": {
              "type": "array", "minItems": 1, "maxItems": 16, "uniqueItems": true,
              "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,31}$" }
            },
            "roles": {
              "type": "array", "minItems": 1, "uniqueItems": true,
              "items": { "enum": ["orchestrator", "agent", "subagent"] }
            }
          }
        }
      }
    },
    "serviceLaunch": {
      "description": "Launch contributor (needs launch:contribute; at most one service per plugin): options shown in the agent launcher under Advanced; the host calls canvastty.launch.prepare for launches that chose this plugin, and with policy for every agent launch (chosen: false, refusal only).",
      "type": "object",
      "additionalProperties": false,
      "required": ["fields"],
      "properties": {
        "appliesTo": {
          "type": "array", "minItems": 1, "uniqueItems": true,
          "items": { "enum": ["codex", "claude", "qwen", "kimi", "opencode", "hermes", "grok", "omp", "pi", "cursor", "minimax", "devin", "antigravity"] }
        },
        "fields": { "type": "array", "maxItems": 8, "items": { "$ref": "#/$defs/launchField" } },
        "policy": { "description": "Also ask before every launch of these agents where the person did not choose the plugin; that answer may only refuse, and no answer refuses too.", "type": "boolean" },
        "delegable": { "description": "These options are safe for an orchestrator to choose for its subagents (spawn_agent launchOptions). Without it only the person chooses them in the launcher.", "type": "boolean" }
      }
    },
    "environmentKind": {
      "type": "object",
      "additionalProperties": false,
      "required": ["kind", "label"],
      "properties": {
        "kind": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,31}$" },
        "label": { "type": "string", "minLength": 1, "maxLength": 80 },
        "description": { "type": "string", "minLength": 1, "maxLength": 240 },
        "appliesTo": {
          "type": "array", "minItems": 1, "uniqueItems": true,
          "items": { "enum": ["terminal", "codex", "claude", "qwen", "kimi", "opencode", "hermes", "grok", "omp", "pi", "cursor", "minimax", "devin", "antigravity"] }
        },
        "fields": { "type": "array", "maxItems": 8, "items": { "$ref": "#/$defs/launchField" } },
        "keeps": {
          "description": "What of CanvasTTY's protection reaches the agent in this environment. Undeclared means no: the core refuses a launch that needs it (any profile but normal needs launch), or marks the card as not protected.",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "launch": { "description": "The launch's arguments and environment reach the agent unchanged (CanvasTTY's hooks and the profile's per-run settings work there).", "type": "boolean" },
            "isolated": { "description": "The agent does not run on this computer's files (container, remote host); this computer's isolation layer does not apply.", "type": "boolean" },
            "confines": { "description": "The environment itself confines the agent to the project.", "type": "boolean" }
          }
        }
      }
    },
    "launchField": {
      "type": "object",
      "additionalProperties": false,
      "required": ["key", "label", "kind"],
      "properties": {
        "key": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,39}$" },
        "label": { "type": "string", "minLength": 1, "maxLength": 80 },
        "kind": { "enum": ["boolean", "select", "text"] },
        "options": {
          "type": "array", "minItems": 1, "maxItems": 16,
          "items": {
            "type": "object", "additionalProperties": false, "required": ["value", "label"],
            "properties": {
              "value": { "type": "string", "minLength": 1, "maxLength": 200 },
              "label": { "type": "string", "minLength": 1, "maxLength": 80 }
            }
          }
        },
        "optionsFrom": { "const": "service", "description": "select only: the launcher also asks the service (canvastty.launch.options) for up to 64 more choices." },
        "default": { "type": ["boolean", "string"] },
        "maxLength": { "type": "integer", "minimum": 1, "maximum": 200 }
      }
    },
    "baseContribution": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "kind", "title", "entry", "defaultSize"],
      "properties": {
        "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$" },
        "kind": { "enum": ["home-widget", "canvas-app", "window"] },
        "title": { "type": "string", "minLength": 1, "maxLength": 80 },
        "description": { "type": "string", "minLength": 1, "maxLength": 240 },
        "entry": { "type": "string", "minLength": 1, "maxLength": 180, "pattern": "^(?!/)(?!.*\\\\)(?!\\.\\.?/)(?!.*(?:/\\.\\.?/|/\\.\\.?$|//)).+\\.html$" },
        "icon": { "type": "string", "minLength": 1, "maxLength": 180, "pattern": "^(?!/)(?!.*\\\\)(?!\\.\\.?/)(?!.*(?:/\\.\\.?/|/\\.\\.?$|//)).+$" },
        "module": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$" },
        "defaultSize": { "type": "object" },
        "minSize": { "type": "object" }
      }
    },
    "contribution": {
      "oneOf": [
        {
          "allOf": [
            { "$ref": "#/$defs/baseContribution" },
            {
              "properties": {
                "kind": { "const": "home-widget" },
                "defaultSize": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["columns", "rows"],
                  "properties": {
                    "columns": { "type": "integer", "minimum": 1, "maximum": 48 },
                    "rows": { "type": "integer", "minimum": 1, "maximum": 36 }
                  }
                }
              }
            }
          ]
        },
        {
          "allOf": [
            { "$ref": "#/$defs/baseContribution" },
            {
              "properties": {
                "kind": { "enum": ["canvas-app", "window"] },
                "defaultSize": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["width", "height"],
                  "properties": {
                    "width": { "type": "number", "minimum": 320, "maximum": 1600 },
                    "height": { "type": "number", "minimum": 220, "maximum": 1100 }
                  }
                },
                "minSize": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["width", "height"],
                  "properties": {
                    "width": { "type": "number", "minimum": 240, "maximum": 1600 },
                    "height": { "type": "number", "minimum": 140, "maximum": 1100 }
                  }
                }
              }
            }
          ]
        }
      ]
    }
  }
}