Разрешения

Карточка без разрешений может рисовать в своей коробке, пользоваться хранилищем, читать свои настройки, менять свою шапку — и ни с кем ничем не обмениваться. Всё остальное — это разрешения, которые вы объявляете в манифесте, а пользователь выдаёт.

Как это устроено:

• На пакет, с проверкой на каждый запрос. Пользователь выдаёт разрешение вашему пакету карточки (всем её копиям на всех холстах). Приложение проверяет выдачу при каждом вызове, внутри приложения — не в SDK и не в вашей карточке.
• Обязательные — целиком при установке. Диалог установки перечисляет их, начиная с самых рискованных. Отказаться — значит не устанавливать.
• Необязательные — во время работы ("optional": true). Вызовите card.permissions.request(), пока карточка на экране; приложение спросит в своём диалоге на всё окно, и пользователь может отказать.
• Одни включают другие. fs.write включает fs.read; agents.output, agents.prompt и terminals.write включают agents.read.
• Пользователь может отозвать любое разрешение в Settings → Custom cards. Страницы карточки перезагружаются с урезанными правами и получают событие permissions.changed; пишите код с расчётом на это.
• Обновление, добавляющее разрешения или сетевые хосты, применяется только после согласия пользователя. Разрешения, которые вы убрали, отзываются.
• Стрелка — согласие на данные. Разрешения, которые затрагивают другую карточку, агента или терминал, работают только с карточками, соединёнными с вашей стрелкой, — в любом направлении, если не сказано иное.

Если разрешения нет, вызов падает с PERMISSION_DENIED (error.permission называет какое).

Коротко

Каждое разрешение

agents.read — низкий

Пользователь видит: See the agents on this canvas — «Видеть агентов на этом холсте. Их имена, какой инструмент у каждого и работает ли он, ждёт вас или закончил».

Открывает: card.agents.list() / get(), события agents.status, agents.turn, agents.changed и встроенный выходной порт агента status.

Границы: ИИ-агенты и терминалы воркспейса самой карточки. Другие карточки — не агенты и в список не попадают.

agents.output — высокий

Пользователь видит: Read what agents and terminals connected to it print — «Читать вывод подключённых к ней агентов и терминалов. Всё, что на экранах карточек агентов и терминалов, соединённых с ней стрелкой, включая показанные там секреты».

Открывает: card.agents.readScreen(), card.agents.lastReply(), живой вывод через card.agents.onOutput(), выходные порты агента reply и терминала exit.

Границы: только агенты и терминалы, подключённые стрелкой. Включает agents.read.

agents.prompt — высокий

Пользователь видит: Give instructions to agents connected to it — «Давать указания подключённым к ней агентам. Набирать и отправлять промпты ИИ-агентам, соединённым с ней стрелкой. Агент может править файлы и запускать команды, значит, карточка может заставить его сделать всё, что умеет агент».

Открывает: card.agents.prompt() и входной порт агента prompt.

Границы: подключённые стрелкой ИИ-агенты (не терминалы). Промпты идут через очередь промптов и бюджет воркспейса, не больше 6 в минуту на карточку (метод и входной порт агента prompt считаются вместе); каждый виден на стрелке и в журнале стрелки. Агенту в опасном режиме каждый промпт отправляется только после согласия пользователя на карточке. Включает agents.read.

terminals.write — высокий

Пользователь видит: Run commands in terminals connected to it — «Запускать команды в подключённых к ней терминалах. Набирать и выполнять команды в карточках терминалов, соединённых с ней стрелкой, — всё, что могли бы запустить вы сами».

Открывает: card.terminals.run() и write(), входной порт терминала command.

Границы: карточки терминалов (bash, PowerShell, cmd), подключённые стрелкой. Не больше 30 команд в минуту на карточку — run и порт терминала command считаются вместе; write — не больше 60 в минуту. Каждая команда видна на стрелке. Включает agents.read.

cards.connected — средний

Пользователь видит: Read and change cards connected to it — «Читать и менять подключённые к ней карточки. Заметки, чек-листы, доски задач и стикеры, соединённые с ней стрелкой».

Открывает: порты встроенных карточек — заметки, списка задач, доски задач и стикера: дописать заметку, добавить задачи, прочитать список.

Границы: карточки этих четырёх видов, подключённые стрелкой.

network — средний, нужны hosts

Пользователь видит: Connect to api.github.com, *.example.com — «Подключаться к … Отправлять и получать данные только с этих адресов в интернете. Туда может уйти всё, что видит карточка».

Открывает: card.net.fetch() к этим хостам по https.

Границы: ровно объявленные шаблоны хостов и только публичные адреса — хост, который резолвится в частный, локальный или адрес облачных метаданных, отклоняется, и при каждом редиректе тоже. Попросить «любой хост» в версии 1 нельзя.

network.local — высокий

Пользователь видит: Connect to servers on this computer — «Подключаться к серверам на этом компьютере. Обращаться к программам на localhost, например дев-серверам и локальным базам данных».

Открывает: card.net.fetch() к localhost, 127.0.0.1 и ::1, по http или https.

Границы: любой порт, кроме собственных серверов NeuroSquad: его MCP-сервера, сервера удалённого доступа, сервера подключения папок для разработчиков, порта отладки Chrome каждой браузерной карточки и дев-сервера самого приложения. Подстановки секретов в запросах к этому компьютеру никогда не заполняются.

fs.read — высокий

Пользователь видит: Read files in the workspace folder — «Читать файлы в папке воркспейса. Любой файл в папке проекта этого воркспейса, включая секреты в файлах вроде .env».

Открывает: card.fs.stat/list/read*/watch() и абсолютный путь path воркспейса в card.workspace.

Границы: папка воркспейса. Пути задаются относительно неё; .. и абсолютные пути отклоняются, ссылка, ведущая наружу, — тоже. Если папка воркспейса — это домашняя папка пользователя, корень диска или в ней лежит папка данных самого NeuroSquad, отклоняется любой вызов к файлам.

fs.write — высокий

Пользователь видит: Change files in the workspace folder — «Менять файлы в папке воркспейса. Создавать, перезаписывать и переносить в корзину файлы в папке проекта этого воркспейса. Агенты воркспейса читают и запускают эти файлы, поэтому карточка может заставить их выполнять команды. Защищены: .git, настройки агентов (.claude, .mcp.json, CLAUDE.md, AGENTS.md и подобные) и данные самого NeuroSquad».

Открывает: card.fs.writeText/writeBytes/mkdir/trash().

Границы: как у fs.read, за вычетом защищённых путей: любой .git, настройки агентов и редакторов, CI-процессы. Безвозвратного удаления нет — trash переносит в корзину ОС. Включает fs.read.

clipboard.write — низкий

Пользователь видит: Copy to your clipboard — «Копировать в буфер обмена. Заменять содержимое буфера обмена текстом из карточки».

Открывает: card.copyText(), не чаще раза в секунду. Читать буфер обмена нельзя.

canvas.spawn — низкий

Пользователь видит: Add cards next to itself — «Добавлять карточки рядом с собой. Ставить на холст до 4 новых карточек рядом с собой».

Открывает: card.spawn() — ещё одну копию вашей карточки или заметку, список задач, доску задач, стикер, соединённые с ней стрелкой.

Границы: 4 карточки на карточку, 4 в минуту, в пределах лимита карточек воркспейса.

background — низкий

Пользователь видит: Keep running when you are not looking — «Работать, когда вы не смотрите. Оставаться активной, пока её воркспейс скрыт. Тратит больше памяти и батареи».

Открывает: карточку не усыпляют, когда она скрыта.

Границы: в фоне во всём приложении работает не больше 8 таких карточек; сверх этого те, что давно не показывались, всё равно усыпляются.

usage.read — низкий

Пользователь видит: See token usage and costs — «Видеть расход токенов и стоимость. Сколько токенов потратили агенты этого воркспейса и сколько это стоило».

Открывает: card.usage().

Границы: воркспейс самой карточки.

Что ещё перечисляет диалог установки

Выводится из манифеста, а не из разрешений: имена инструментов, которые карточка даёт подключённым агентам, и сколько у неё входных и выходных портов. Необязательные разрешения показываются под It may ask later for.