connect() и объект карточки

Всё, что делает карточка, идёт через один объект — карточку, которую возвращает connect():

import { connect } from '@neurosquad/card-sdk'
 
const card = await connect()
card.setStatus(`Hello, ${card.workspace.name}`, { tone: 'success' })

connect() ждёт, пока приложение передаст карточке её личный канал, представляется и возвращает Card. Повторный вызов возвращает ту же карточку.

connect(options?)

import { connect } from '@neurosquad/card-sdk'
 
const card = await connect({
  theme: true,          // apply the app theme as --ns-* CSS variables on <html> (default true)
  syncLang: true,       // keep <html lang> equal to the app language (default true)
  forwardErrors: true,  // send uncaught errors and rejections to the card log (default true)
  timeoutMs: 10_000     // how long to wait for the app (default 10 000)
})

Отклоняется с CardSdkError:

• UNAVAILABLE — страница открыта не внутри карточки NeuroSquad (сама по себе в браузере). Для превью используйте мок-хост, как это делают шаблоны.
• PROTOCOL_MISMATCH — приложение старше протокола карточек, на котором говорит ваш SDK. Карточка показывает «нужен более новый NeuroSquad».

Объект карточки

Контекст

card.context — это HostContext: то, что приложение отправило при подключении карточки, обновляемое по каждому событию (видимость, размер, тема, язык, настройки, разрешения, соседи). При каждом изменении объект заменяется, а не мутирует, — его безопасно использовать с useSyncExternalStore из React.

import type { HostContext } from '@neurosquad/card-sdk'
 
function describe(context: HostContext): string {
  const { instance, workspace, visibility, i18n, launch } = context
  return `${instance.displayName} ${instance.version} in "${workspace.name}", ${visibility}, ${i18n.language}, started: ${launch}`
}
 
card.onContextChange((context) => render(describe(context)))

Сокращения на самой карточке: card.instanceId, card.instance, card.workspace, card.visibility, card.expanded, card.size, card.theme, card.i18n, card.language, card.launch, card.spawnInit, card.limits, card.appVersion.

launch говорит, что произошло: created (карточку только что добавили на холст), opened (открыли воркспейс), resumed (вернулась после усыпления), reloaded (пользователь нажал Reload, в режиме разработчика изменился файл или отозвали разрешение), updated (установлена новая версия вашей карточки).

Любой метод, любое событие

Пространства имён — это удобная обёртка над двумя примитивами, оба полностью типизированы по протоколу:

// Any method: params and result are typed from the method name.
const { keys } = await card.call('storage.keys', { scope: 'instance', prefix: 'draft:' })
const info = await card.call('card.getInfo')
 
// Any event: the payload is typed from the event name. Returns a function that removes the listener.
const off = card.on('agents.turn', (turn) => {
  if (turn.phase === 'end') render(`${turn.agentId} finished a turn`)
})
off()
 
// Once, or as a promise.
card.once('lifecycle.expanded', ({ expanded }) => render(expanded))
const next = await card.waitFor('agents.status', (e) => e.status === 'needs-input', { timeoutMs: 60_000 })
render(next.agentId)

Темы с подпиской (agents.status, agents.turn, agents.changed, storage.changed) подписываются в приложении автоматически, пока есть хотя бы один слушатель, и отписываются, когда уходит последний. Для agents.output нужны идентификаторы агентов — используйте card.agents.onOutput(). Если для темы нужно разрешение, которого у вас нет, слушатель просто ничего не получает, а в журнал карточки уходит предупреждение.

События, которые могут прийти раньше, чем вы подпишетесь, — ports.message, ui.menu, fs.changed, — сохраняются (до 100) и доставляются первому слушателю, так что между connect() и вашим on() ничего не теряется.

Все события

Определение возможностей

Новые методы и события появляются внутри одной версии протокола. Прежде чем пользоваться тем, чего в приложении пользователя может ещё не быть, проверьте:

if (await card.host.supports('usage.summary')) {
  const usage = await card.usage('today')
  render(usage.totalCostMicroUsd)
}
 
const { protocol, methods, events } = await card.host.capabilities()
render(protocol, methods.length, events.length)
 
// A method newer than your SDK's types:
const result = await card.callUnchecked('some.newMethod', { any: 'params' })
render(result)

Соглашения

• Идентификаторы. Идентификаторы карточек и агентов — это идентификаторы на холсте, тот же cardId, что вы получаете из card.ports.peers, card.agents.list() или card.spawn().
• Подключена — значит, между двумя карточками есть стрелка, в любом направлении. Для портов направление ещё и важно (см. Порты).
• Каждый вызов проверяется дважды. SDK проверяет параметры по тем же схемам, что и приложение, и сразу падает с INVALID_PARAMS и точным путём; приложение проверяет снова — плюс разрешения, видимость, стрелки и ограничения частоты.
• Передаётся только JSON. Никаких Blob и ArrayBuffer: помощники, которые принимают байты (fs.writeBytes, тела net.fetch), сами кодируют их в base64.
• Ответы могут прийти не по порядку; события приходят в том порядке, в каком их отправило приложение.
• Никогда не доверяйте событиям message у window. Любая другая карточка на холсте может сделать postMessage в ваш фрейм. Доверенный канал только один — тот, что SDK получает от приложения в connect(); не добавляйте свои слушатели message, которые что-то делают с пришедшим.