@neurosquad/card-sdk 1.0.0

package/schema/neurosquad-card.v1.json

@@ -0,0 +1,434 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://neurosquad.ai/schemas/neurosquad-card.v1.json",
+  "title": "NeuroSquad custom card manifest",
+  "description": "neurosquad-card.json at the root of a NeuroSquad custom card package.",
+  "type": "object",
+  "required": ["manifestVersion", "name", "displayName", "version", "protocol"],
+  "additionalProperties": false,
+  "$defs": {
+    "localized80": {
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 80
+        },
+        {
+          "type": "object",
+          "required": ["en"],
+          "additionalProperties": false,
+          "properties": {
+            "en": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 80
+            },
+            "ru": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 80
+            },
+            "zh": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 80
+            }
+          }
+        }
+      ]
+    },
+    "localized300": {
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 300
+        },
+        {
+          "type": "object",
+          "required": ["en"],
+          "additionalProperties": false,
+          "properties": {
+            "en": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 300
+            },
+            "ru": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 300
+            },
+            "zh": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 300
+            }
+          }
+        }
+      ]
+    },
+    "localized500": {
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 500
+        },
+        {
+          "type": "object",
+          "required": ["en"],
+          "additionalProperties": false,
+          "properties": {
+            "en": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 500
+            },
+            "ru": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 500
+            },
+            "zh": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 500
+            }
+          }
+        }
+      ]
+    },
+    "size": {
+      "type": "object",
+      "required": ["w", "h"],
+      "additionalProperties": false,
+      "properties": {
+        "w": {
+          "type": "integer",
+          "minimum": 200,
+          "maximum": 2400
+        },
+        "h": {
+          "type": "integer",
+          "minimum": 120,
+          "maximum": 1800
+        }
+      }
+    },
+    "port": {
+      "type": "object",
+      "required": ["id", "label", "type"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{0,31}$"
+        },
+        "label": {
+          "$ref": "#/$defs/localized80"
+        },
+        "description": {
+          "$ref": "#/$defs/localized500"
+        },
+        "type": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 97
+        },
+        "schema": {
+          "type": "object"
+        },
+        "mode": {
+          "enum": ["stream", "request"]
+        },
+        "response": {
+          "type": "object",
+          "required": ["type"],
+          "additionalProperties": false,
+          "properties": {
+            "type": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 97
+            },
+            "schema": {
+              "type": "object"
+            }
+          }
+        },
+        "retain": {
+          "type": "boolean"
+        },
+        "default": {
+          "type": "boolean"
+        }
+      }
+    }
+  },
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "maxLength": 500
+    },
+    "manifestVersion": {
+      "const": 1
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{1,47}$"
+    },
+    "displayName": {
+      "$ref": "#/$defs/localized80"
+    },
+    "version": {
+      "type": "string",
+      "maxLength": 64,
+      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$"
+    },
+    "description": {
+      "$ref": "#/$defs/localized300"
+    },
+    "author": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "maxLength": 500,
+          "pattern": "^https://"
+        }
+      }
+    },
+    "license": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 100
+    },
+    "homepage": {
+      "type": "string",
+      "format": "uri",
+      "maxLength": 500,
+      "pattern": "^https://"
+    },
+    "icon": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 240
+    },
+    "protocol": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 1000
+    },
+    "minAppVersion": {
+      "type": "string",
+      "maxLength": 64,
+      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$"
+    },
+    "entry": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 240
+    },
+    "card": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "defaultSize": {
+          "$ref": "#/$defs/size"
+        },
+        "minSize": {
+          "$ref": "#/$defs/size"
+        },
+        "maxSize": {
+          "$ref": "#/$defs/size"
+        }
+      }
+    },
+    "permissions": {
+      "type": "array",
+      "maxItems": 32,
+      "items": {
+        "anyOf": [
+          {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64
+          },
+          {
+            "type": "object",
+            "required": ["id"],
+            "additionalProperties": false,
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 64
+              },
+              "hosts": {
+                "type": "array",
+                "maxItems": 32,
+                "items": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 260
+                }
+              },
+              "reason": {
+                "$ref": "#/$defs/localized300"
+              },
+              "optional": {
+                "type": "boolean"
+              }
+            }
+          }
+        ]
+      }
+    },
+    "settings": {
+      "type": "array",
+      "maxItems": 40,
+      "items": {
+        "type": "object",
+        "required": ["key", "type", "label"],
+        "additionalProperties": false,
+        "properties": {
+          "key": {
+            "type": "string",
+            "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$"
+          },
+          "type": {
+            "enum": ["string", "text", "number", "boolean", "select", "secret", "color"]
+          },
+          "label": {
+            "$ref": "#/$defs/localized80"
+          },
+          "description": {
+            "$ref": "#/$defs/localized300"
+          },
+          "default": {
+            "type": ["string", "number", "boolean"]
+          },
+          "required": {
+            "type": "boolean"
+          },
+          "scope": {
+            "enum": ["instance", "package"]
+          },
+          "placeholder": {
+            "$ref": "#/$defs/localized80"
+          },
+          "maxLength": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 100000
+          },
+          "min": {
+            "type": "number"
+          },
+          "max": {
+            "type": "number"
+          },
+          "step": {
+            "type": "number",
+            "exclusiveMinimum": 0
+          },
+          "options": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 50,
+            "items": {
+              "type": "object",
+              "required": ["value", "label"],
+              "additionalProperties": false,
+              "properties": {
+                "value": {
+                  "type": "string",
+                  "maxLength": 200
+                },
+                "label": {
+                  "$ref": "#/$defs/localized80"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "ports": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "inputs": {
+          "type": "array",
+          "maxItems": 16,
+          "items": {
+            "$ref": "#/$defs/port"
+          }
+        },
+        "outputs": {
+          "type": "array",
+          "maxItems": 16,
+          "items": {
+            "$ref": "#/$defs/port"
+          }
+        }
+      }
+    },
+    "tools": {
+      "type": "array",
+      "maxItems": 32,
+      "items": {
+        "type": "object",
+        "required": ["name", "description", "inputSchema"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]{0,39}$"
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 80
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000
+          },
+          "inputSchema": {
+            "type": "object"
+          },
+          "readOnly": {
+            "type": "boolean"
+          },
+          "timeoutMs": {
+            "type": "integer",
+            "minimum": 1000,
+            "maximum": 120000
+          }
+        }
+      }
+    },
+    "keywords": {
+      "type": "array",
+      "maxItems": 20,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 40
+      }
+    }
+  }
+}

package/templates/react/README.md

@@ -0,0 +1,34 @@
+# __CARD_DISPLAY_NAME__
+
+A custom card for [NeuroSquad](https://neurosquad.ai), made with `@neurosquad/card-sdk`
+(React + Vite template).
+
+## Develop
+
+```sh
+npm install
+npm run dev        # preview in the browser against a mock host with sample agents
+```
+
+Live in the app:
+
+1. In NeuroSquad: **Settings → Custom cards → Developer mode**.
+2. `npx neurosquad-card dev` — it runs `npm run watch` (rebuilds `dist/` on save),
+   links this folder into the app (confirm there) and prints the card's log.
+   Add the card from the canvas: **+ → Custom card…**.
+
+## Check and share
+
+```sh
+npm run build      # dist/ — the app loads dist/index.html (see "entry" in the manifest)
+npm run validate   # the app's own checks + the install dialog preview
+npm run pack       # what would be installed, and the tree hash
+```
+
+**Commit `dist/`.** NeuroSquad installs straight from the GitHub repository and
+does not run your build. People install the card by pasting `owner/repo` (or
+`owner/repo/path/to/folder`) into **Settings → Custom cards**.
+
+Card code runs in a sandbox: no inline scripts, no external resources (Vite
+bundles everything), network only through `card.net.fetch` to hosts declared in
+the `network` permission.

package/templates/react/_gitignore

@@ -0,0 +1,10 @@
+node_modules
+# packed archives (neurosquad-card pack)
+*.tgz
+.DS_Store
+# secrets never go into a card package (pack refuses them anyway)
+.env*
+!.env.example
+# dist/ is NOT ignored: the app installs the built card from the repository.
+# The negation keeps it even inside a parent repository that ignores dist.
+!dist/

package/templates/react/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>__CARD_DISPLAY_NAME__</title>
+  </head>
+  <body class="ns-kit">
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/react/neurosquad-card.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "./node_modules/@neurosquad/card-sdk/schema/neurosquad-card.v1.json",
+  "manifestVersion": 1,
+  "name": "__CARD_NAME__",
+  "displayName": "__CARD_DISPLAY_NAME__",
+  "version": "0.1.0",
+  "protocol": 1,
+  "description": "A starter NeuroSquad card (React): live agent statuses, a scratchpad that is saved, a port and a tool for connected agents.",
+  "license": "MIT",
+  "icon": "icon.png",
+  "entry": "dist/index.html",
+  "card": {
+    "defaultSize": {
+      "w": 420,
+      "h": 360
+    },
+    "minSize": {
+      "w": 280,
+      "h": 220
+    }
+  },
+  "permissions": [
+    {
+      "id": "agents.read",
+      "reason": {
+        "en": "Shows which agents are working",
+        "ru": "Показывает, какие агенты работают",
+        "zh": "显示哪些智能体正在工作"
+      }
+    },
+    {
+      "id": "cards.connected",
+      "optional": true,
+      "reason": {
+        "en": "Sends the scratchpad to a note you connect with an arrow",
+        "ru": "Отправляет черновик в заметку, соединённую стрелкой",
+        "zh": "将草稿发送到用箭头连接的笔记"
+      }
+    }
+  ],
+  "settings": [
+    {
+      "key": "greeting",
+      "type": "string",
+      "label": {
+        "en": "Greeting",
+        "ru": "Приветствие",
+        "zh": "问候语"
+      },
+      "default": "Hello from __CARD_DISPLAY_NAME__",
+      "maxLength": 80
+    }
+  ],
+  "ports": {
+    "inputs": [
+      {
+        "id": "text",
+        "label": {
+          "en": "Text in",
+          "ru": "Текст",
+          "zh": "文本输入"
+        },
+        "description": "Appended to the scratchpad.",
+        "type": "ns:text",
+        "default": true
+      }
+    ],
+    "outputs": [
+      {
+        "id": "scratchpad",
+        "label": {
+          "en": "Scratchpad",
+          "ru": "Черновик",
+          "zh": "草稿"
+        },
+        "description": "The scratchpad text, when you press Send.",
+        "type": "ns:markdown",
+        "retain": true
+      }
+    ]
+  },
+  "tools": [
+    {
+      "name": "read_scratchpad",
+      "title": "Read the scratchpad",
+      "description": "Returns the text the user wrote in this card's scratchpad (may be empty).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "readOnly": true
+    }
+  ]
+}

package/templates/react/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "__CARD_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "watch": "vite build --watch",
+    "validate": "neurosquad-card validate",
+    "pack": "neurosquad-card pack"
+  },
+  "dependencies": {
+    "@neurosquad/card-sdk": "^__SDK_VERSION__",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^5.1.0",
+    "typescript": "^5.9.0",
+    "vite": "^7.2.0"
+  }
+}