@neurosquad/card-sdk 1.0.0

package/templates/vanilla/main.js

@@ -0,0 +1,256 @@
+// __CARD_DISPLAY_NAME__ — a NeuroSquad card. Docs for every call: vendor/card-sdk.js is
+// @neurosquad/card-sdk; its types and README describe the whole API.
+import {
+  connect,
+  createTranslator,
+  isCardSdkError,
+  permissionForPeer,
+  requestPermissions
+} from './vendor/card-sdk.js'
+
+// Inside NeuroSquad the app hands us a private channel. Opened on its own
+// (npx serve . → http://localhost:3000) the page runs against a mock host.
+const card = window.parent === window ? await previewHost() : await connect()
+
+const t = createTranslator(
+  {
+    en: {
+      agents: 'Agents',
+      scratchpad: 'Scratchpad',
+      send: 'Send',
+      noAgents: 'No agents on this canvas yet',
+      working_one: '{{count}} agent working',
+      working_other: '{{count}} agents working',
+      sent_one: 'Sent to {{count}} card',
+      sent_other: 'Sent to {{count}} cards',
+      notConnected: 'Draw an arrow from this card to a note to send it there',
+      status: {
+        working: 'working',
+        'needs-input': 'waiting for you',
+        finished: 'finished',
+        idle: 'idle',
+        exited: 'stopped'
+      }
+    },
+    ru: {
+      agents: 'Агенты',
+      scratchpad: 'Черновик',
+      send: 'Отправить',
+      noAgents: 'На холсте пока нет агентов',
+      working_one: 'Работает {{count}} агент',
+      working_few: 'Работают {{count}} агента',
+      working_many: 'Работают {{count}} агентов',
+      working_other: 'Работают {{count}} агента',
+      sent_one: 'Отправлено в {{count}} карточку',
+      sent_few: 'Отправлено в {{count}} карточки',
+      sent_many: 'Отправлено в {{count}} карточек',
+      sent_other: 'Отправлено в {{count}} карточки',
+      notConnected: 'Проведите стрелку от этой карточки к заметке, чтобы отправить туда',
+      status: {
+        working: 'работает',
+        'needs-input': 'ждёт вас',
+        finished: 'закончил',
+        idle: 'свободен',
+        exited: 'остановлен'
+      }
+    },
+    zh: {
+      agents: '智能体',
+      scratchpad: '草稿',
+      send: '发送',
+      noAgents: '画布上还没有智能体',
+      working_other: '{{count}} 个智能体正在工作',
+      sent_other: '已发送到 {{count}} 张卡片',
+      notConnected: '从此卡片画一条箭头到笔记，即可发送到那里',
+      status: {
+        working: '工作中',
+        'needs-input': '等待你',
+        finished: '已完成',
+        idle: '空闲',
+        exited: '已停止'
+      }
+    }
+  },
+  card
+)
+
+const $ = (id) => document.getElementById(id)
+const pad = $('pad')
+let agents = []
+
+// --- render --------------------------------------------------------------------
+
+function renderStatic() {
+  document.querySelectorAll('[data-t]').forEach((el) => (el.textContent = t(el.dataset.t)))
+  $('workspace').textContent = card.workspace.name
+  $('greeting').textContent = card.settings.value('greeting') ?? card.instance.displayName
+}
+
+const TONE = {
+  working: 'accent',
+  'needs-input': 'warning',
+  finished: 'success',
+  idle: '',
+  exited: 'danger'
+}
+
+function renderAgents() {
+  const list = $('agents')
+  list.replaceChildren(
+    ...agents.map((agent) => {
+      const item = document.createElement('li')
+      item.className = 'ns-list-item'
+      const dot = document.createElement('span')
+      dot.className = `ns-dot ${TONE[agent.status] ? `ns-dot--${TONE[agent.status]}` : ''}`
+      const name = document.createElement('span')
+      name.className = 'ns-truncate'
+      name.textContent = agent.name
+      const status = document.createElement('span')
+      status.className = 'agent-status ns-muted'
+      status.textContent = t(`status.${agent.status}`)
+      item.append(dot, name, status)
+      return item
+    })
+  )
+  if (agents.length === 0) {
+    const empty = document.createElement('li')
+    empty.className = 'ns-list-item ns-muted'
+    empty.textContent = t('noAgents')
+    list.append(empty)
+  }
+  const working = agents.filter((agent) => agent.status === 'working').length
+  $('working').textContent = String(working)
+  $('working').title = t('working', { count: working })
+  // What the overview tile shows when the canvas is zoomed out.
+  card.setOverview({
+    primary: t('working', { count: working }),
+    tone: working ? 'accent' : 'default',
+    icon: 'users'
+  })
+}
+
+// --- data ------------------------------------------------------------------------
+
+async function loadAgents() {
+  try {
+    agents = await card.agents.list()
+  } catch (error) {
+    card.log.warn('could not list agents', error)
+    agents = []
+  }
+  renderAgents()
+}
+
+card.agents.onChanged((next) => {
+  agents = next
+  renderAgents()
+})
+card.agents.onStatus(({ agentId, status }) => {
+  agents = agents.map((agent) => (agent.id === agentId ? { ...agent, status } : agent))
+  renderAgents()
+})
+
+// The scratchpad is saved in the card's own storage (survives reloads and restarts).
+pad.value = await card.storage.get('scratchpad', '')
+let saveTimer
+pad.addEventListener('input', () => {
+  clearTimeout(saveTimer)
+  saveTimer = setTimeout(() => card.storage.set('scratchpad', pad.value), 400)
+})
+card.lifecycle.onSuspend(() => card.storage.set('scratchpad', pad.value))
+
+// Input port: text from a connected card lands in the scratchpad.
+card.ports.onMessage((text) => {
+  pad.value = pad.value ? `${pad.value}\n${text}` : String(text)
+  card.storage.set('scratchpad', pad.value)
+})
+
+// Output port: Send pushes the scratchpad to connected cards (a note appends it).
+$('send').addEventListener('click', async () => {
+  try {
+    // A note's input needs the optional cards.connected permission: ask for
+    // it (the app shows its own prompt) before the first send.
+    const needed = card.ports.peers
+      .filter((peer) => peer.direction !== 'upstream')
+      .map((peer) => permissionForPeer(peer, { outputType: 'ns:markdown' }))
+      .filter((id) => id !== null)
+    if (needed.length > 0) await requestPermissions(card, ...new Set(needed))
+    const delivered = await card.ports.emit('scratchpad', pad.value)
+    $('hint').textContent = delivered > 0 ? t('sent', { count: delivered }) : t('notConnected')
+  } catch (error) {
+    $('hint').textContent = isCardSdkError(error) ? error.hostMessage : String(error)
+  }
+})
+
+// A tool for connected agents: they can read what the user wrote here.
+card.tools.handle('read_scratchpad', () => pad.value || '(the scratchpad is empty)')
+
+// Keep the UI in step with the app.
+card.settings.onChange(renderStatic)
+t.onChange(() => {
+  renderStatic()
+  renderAgents()
+})
+
+renderStatic()
+await loadAgents()
+document.querySelector('main').removeAttribute('aria-busy')
+
+// --- standalone preview -------------------------------------------------------------
+
+async function previewHost() {
+  const { createMockHost } = await import('./vendor/testing.js')
+  const manifest = await (await fetch('./neurosquad-card.json')).json()
+  const host = createMockHost({
+    manifest,
+    agents: [
+      {
+        id: 'a1',
+        name: 'Claude Code',
+        harness: 'claude-code',
+        kind: 'ai',
+        status: 'working',
+        connected: true
+      },
+      {
+        id: 'a2',
+        name: 'Codex',
+        harness: 'codex-cli',
+        kind: 'ai',
+        status: 'needs-input',
+        connected: false
+      },
+      {
+        id: 't1',
+        name: 'PowerShell',
+        harness: 'shell-powershell',
+        kind: 'shell',
+        status: 'idle',
+        connected: false
+      }
+    ],
+    peers: [
+      {
+        cardId: 'note-1',
+        kind: 'note',
+        name: 'Notes',
+        direction: 'downstream',
+        inputs: [
+          {
+            id: 'append',
+            label: 'Append',
+            type: 'ns:markdown',
+            mode: 'stream',
+            retain: false,
+            default: true,
+            // Like the app: sending to a note needs cards.connected.
+            permission: 'cards.connected'
+          }
+        ],
+        outputs: []
+      }
+    ]
+  })
+  window.mockHost = host // play with it from DevTools: mockHost.setAgentStatus('a2', 'working')
+  return host.connect()
+}

package/templates/vanilla/neurosquad-card.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "./vendor/neurosquad-card.schema.json",
+  "manifestVersion": 1,
+  "name": "__CARD_NAME__",
+  "displayName": "__CARD_DISPLAY_NAME__",
+  "version": "0.1.0",
+  "protocol": 1,
+  "description": "A starter NeuroSquad card: live agent statuses, a scratchpad that is saved, a port and a tool for connected agents.",
+  "license": "MIT",
+  "icon": "icon.png",
+  "entry": "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/vanilla/style.css

@@ -0,0 +1,41 @@
+/* Your card's own styles. The frame is the card body: fill it and scroll inside. */
+html,
+body {
+  height: 100%;
+  overflow: hidden;
+}
+
+.app {
+  display: grid;
+  grid-template-rows: auto minmax(64px, 1fr) minmax(96px, 1.2fr) auto;
+  grid-template-columns: minmax(0, 1fr);
+  gap: 10px;
+  height: 100%;
+  padding: 12px;
+}
+
+.agents {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  min-height: 0;
+  padding: 10px;
+}
+
+.agents .ns-list {
+  flex: 1;
+}
+
+.pad {
+  min-height: 0;
+}
+
+.pad .ns-textarea {
+  height: 100%;
+  resize: none;
+}
+
+.agent-status {
+  margin-left: auto;
+  font-size: 12px;
+}