Референца SDK-а

Комплетан API пакета @beeuni/sdk — методе клијента, модули, потези и дистрибуција.

Ова страница представља комплетан API интерфејс @beeuni/sdk: све методе клијента, модуле независне од радног оквира, помоћне функције за потезе и начин дистрибуције пакета. Користите SDK за почетак и Сесије за детаљан опис животног циклуса сесије.

Клијент

createBeeuni(config) враћа једног клијента. Свака метода је типизован позив платформског API-ја. Референце project(id) и session(pid, sid) везују идентификаторе тако да их никада не понављате.

const beeuni = createBeeuni({ backendUrl, getToken });

beeuni.accounts; // account / team operations
beeuni.accountInvites; // invite accept/decline by token alone
beeuni.projects; // top-level project operations
beeuni.connectors; // Connector calls scoped by an agent-minted token
beeuni.connector(slug); // one connector in the token's scope → see p.connector(slug)
beeuni.project(id); // id-bound project handle
beeuni.session(pid, sid); // id-bound session handle → see Sessions
beeuni.github; // GitHub App install + repo linking (account-scoped)
beeuni.gitBackend; // the instance git backend ("Beeuni managed")
beeuni.billing; // credits, subscription, tier, transactions
beeuni.sandboxShares; // public share links for a sandbox port
beeuni.connectStatus; // easy-connect status
beeuni.marketplace; // public marketplace catalog
beeuni.validateToken; // pasted-API-key check
beeuni.config; // platform config in effect
beeuni.runtime(); // runtime REST compatibility client

Налози — beeuni.accounts

accounts.tokens издаје API кључеве ограничене на налог (beeuni_pat_...). Погледајте SDK аутентификација за комплетан модел токена.

accounts.audit је евиденција за реконструкцију у предузећу. Она обједињује аутентификоване API захтеве са семантичким догађајима сесија, конектора, одобрења и рачунара.

Сваки догађај садржи project_id, session_id, actor_type, source, outcome, request_id, trace_id и correlation_id када их радња достави. API не чува тела захтева, промптове, тајне, акредитиве нити необрађене аргументе конектора у централизованом догађају. Догађаји конектора могу да садрже ограничен преглед аргумената који прикрива поља налик акредитивима и непрозирне податке.

Доделе приступа

Beeuni има једну врсту записа о додели права: доделу. Она повезује једног субјекта (user, group, service_account или pending) са једном улогом, у једном опсегу (account или једном project), уз могуће сужавање на један објекат (agent, skill, secret, app или trigger) и могуће укључивање expires_at. Групни приступ, приступ по ресурсу и везивања прилагођених улога — све су то доделе. Погледајте Налози и приступ за опис модела.

Канонски REST интерфејс је:

SDK их излаже као listAssignments, createAssignment, revokeAssignment и listPermissions. Ред каталога садржи action, scope_type, resource_type, delegable, description, area, level и implies — читајте га уместо да стрингове радњи уграђујете у код.

За доделу прилагођене улоге потребно је право rbac на налогу; без њега рута враћа 402 са code: "entitlement_required".

Позивнице за налог — beeuni.accountInvites

Приступа им се само помоћу токена позивнице — позвана особа можда још није члан.

Пројекти — beeuni.projects

provision креира нови пројекат; не покреће изоловано окружење постојећег пројекта. Уместо тога покрените сесију — погледајте Сесије.

Пошаљите idempotency_key када је могућ поновни покушај — поновно учитавање, друга картица, истек времена након којег сте поновили захтев. provision при сваком позиву креира потпуно ново спремиште којим се управља, па без кључа сви ти позиви креирају стварне дупликате пројеката. Користите исти кључ за сваки покушај једног логичког креирања и поновљени позиви ће вратити пројекат који је први покушај креирао (201, исти project_id, push_token: null). Кључ идентификује покушај, а не тело захтева — поновна употреба кључа са другачијим name враћа први пројекат и игнорише нову вредност, па генеришите нов кључ за свако засебно креирање. Креирање другог пројекта са истим називом и без кључа и даље ради.

Поновљени позив који стигне док први још обезбеђује ресурсе добија 409 са code: 'provision_in_flight' уместо project_id који тај позив још може да поништи. Покушајте поново са истим кључем.

project(id).sessions.list({ scope: 'project' }) је преглед животног циклуса за позиваоца са дозволама управника пројекта. Додаје доступне сесије које су недоступне, загрејане или логички обрисане, са метаподацима о власништву и стању извршавања. Оба опсега приказа изостављају све сесије које позивалац не може да отвори.

sessions.list и sessions.listPage такође прихватају филтере хијерархије и атрибуције. Без њих листа остаје равна и непромењена.

Сваки ред сесије има parent_session_id и initiator ({ type: 'member' | 'trigger' | 'channel' | 'api' | 'system', id, label }). initiator наводи ко је покренуо цело извршавање; подређена сесија копира ту вредност од надређене. sessionParentId(session) чита parent_session_id, а затим застарели metadata.spawned_by_session. Курсор важи само за скуп филтера за који је издат.

GitHub — beeuni.github

Инсталација GitHub App-а и повезивање репозиторијума на нивоу налога, не пројекта.

Ова листа садржи само стварне везе налога. „Beeuni managed“ није једна од њих — то је позадински систем инстанце описан испод.

Git позадински систем инстанце — beeuni.gitBackend

Један власник и акредитив за цело окружење, који се користе за репозиторијуме којима управља Beeuni. То никада није веза налога и никада се не појављује у beeuni.github.listInstallations.

Наплата — beeuni.billing

Чита кредите, претплату, план и историју трансакција. Користите Beeuni плаћање и управљање наплатом за плаћања и куповину кредита.

sessionCosts.list() прихвата accountId, projectId, limit и offset. Сваки ред обједињује коначни LLM трошак и обрачунати трошак рачунарских ресурса sandbox-а. sessionCosts.get() додаје коришћење модела и евиденцију која разликује LLM и рачунарске ресурсе. Листа укључује укупан износ за усаглашавање трошкова без сесије.

Дељење sandbox-а — beeuni.sandboxShares

Јавни линкови за дељење једног изложеног порта sandbox-а. Важе за sandbox, не за пројекат.

Каталог тржишта — beeuni.marketplace

Прегледање јавног каталога, само за читање — разликује се од project(id).marketplace, који инсталира ставку у пројекат.

Обавештења — beeuni.notifications

Обавештења позиваоца, на свим налозима и пројектима. Свака пријављена особа има једно пријемно сандуче, један запис о подешавањима и Web Push претплате за своје прегледаче. Сваки метод захтева акредитиве особе: сервисни налог добија 403.

const page = await beeuni.notifications.list({ limit: 20 });
await beeuni.notifications.markRead({ ids: [page.notifications[0].id] });
await beeuni.notifications.updatePreferences({ kinds: { turn_done: { push: false } } });

Врсте (InboxNotificationKind, наведене у INBOX_NOTIFICATION_KINDS):

DEFAULT_NOTIFICATION_PREFERENCES садржи ове подразумеване вредности. Ред у пријемном сандучету се увек уписује; подешавања одређују само push обавештења и е-пошту. Е-порука са сажетком наводи редове који су и даље непрочитани 15 минута након пристизања, уз највише један сажетак на сат. Сакријте колону е-поште када је email_available false.

url сваког реда отвара његову тему. Његов упит ?notification=<id> омогућава страници да означи ред као прочитан.

Објекат сесије садржи праћење једне сесије за позиваоца:

Објекат пројекта — beeuni.project(id)

Везује идентификатор пројекта; сваки подресурс је везан за њега.

const p = beeuni.project(projectId);
await p.detail();
await p.update({ name });
await p.llmCatalog();

p.tokens — API кључеви ограничени на пројекат

Аутоматски се издају при креирању сесије као BEEUNI_TOKEN; могу се издати и ручно.

p.setupLinks — везе за подешавање које издаје агент

Веза коју особа отвара да унесе тајну или повеже апликацију, без пуног приступа пројекту.

p.apps — апликације (издања, машине, волумени)

Доступно преко функције пројекта apps. Водич: SDK → Апликације.

p.secrets — тајне пројекта

runtime са потрошачем sandbox представља излагање кроз окружење — подразумевано, и једину политику која ставља вредност у отвореном тексту у сесију. egress са потрошачем network представља излагање контролисано на излазу: сесија чува референцу, а Beeuni умеће стварну вредност изван sandbox окружења, за тачно оне HTTPS хостове које политика наводи. Излагање контролисано на излазу је експериментално; захтева заставицу функције secrets_egress (Settings → Feature flags). Када је заставица искључена, setStrategy(identifier, 'egress', …) и upsert(...) са излазном политиком враћају 403 feature_disabled. Ниједан потрошач broker уопште није присутан у сесији. Погледајте Тајне. Метод broker(...) захтева токен ограничен на сесију и активну референцу сесије.

p.access — доделе пројекта, позиви, захтеви

Сваки метод овде чита или уписује доделу која важи за овај пројекат. Пројектне улоге су manager и member.

p.access.resourceGrants је приказ доделе објекта: ограничава субјекта на један објекат у пројекту уместо на цео пројекат. Beeuni тренутно примењује доделе објеката на агенте и вештине. Агент је подразумевано затворен — члан му приступа само када додела наводи њега или неку од његових група. Додела објекта сама по себи не носи дозволе и ограничава менаџера пројекта исто колико и члана.

p.connector(slug) — један конектор

options: account, approvalContext, timeoutMs (подразумевано 90 000), signal. Уз датотеку из beeuni connectors types, аргументи и излаз су типизирани.

p.connectors — конектори алата

p.connectors.discover служи за преглед каталога директних конектора. Функција је експериментална и подразумевано искључена — омогућите је за сваки пројекат у Settings → Feature flags → “Connectors API Discover”. Easy Connect остаје подразумевано тржиште конектора.

p.connectors.pipedream је путања компатибилности за ранији управљани OAuth; listApps враћа само OAuth апликације. За нове управљане интеграције користите Easy Connect. Апликације са API кључем повежите директно.

Конектор дефинише алат, апликацију добављача и смернице. connections чува његове повезане налоге — конектор може да садржи више њих истовремено. Сесија може да фиксира један за сваки позив помоћу connector_bindings: { alias: { connection_id } }, или појединачни позив може да наведе један помоћу call(tool, args, { account }). Акредитиви остају шифровани и одређују се за сваки захтев.

connections је једина активна фасада за ауторизацију. Повучени називи authorizations и profiles нису део тренутног SDK интерфејса.

Налози и провера у тренутку позива

Свака веза има owner_type: project (дељена — доступна свакоме коме је одобрен приступ конектору, било особи или сервисном налогу) или member (приватна — доступна само свом власнику, и то само у приватној сесији; никада сервисном налогу). Дељени налог може да се ограничи на групе и особе: connections.list() враћа његове дозволе у shared_with, а connectionSharedWithEveryone(connection) показује да ли сви у пројекту могу да га користе. Ограничени налог прати правила приватног налога за наведене особе, а usable: false означава налог који позивалац види само да би њиме управљао. Доделите или опозовите приступ помоћу createAssignment / revokeAssignment (object: { type: 'connection', id }) — погледајте Изаберите ко може да користи дељени налог. p.connectors.accounts(slug) наводи све налоге којима овај позивалац може да приступи, са подразумеваним на првом месту:

const accounts = await beeuni.project(projectId).connectors.accounts('stripe-read');
// [{ connection_id, label, owner_type, is_default }, ...]

await beeuni.project(projectId).connectors.call(
  'stripe-read.get_balance',
  {},
  { account: 'My Stripe' }, // a connection id, a label, or the words `me` / `project`
);

Позив који не наводи налог прво се разрешава на подразумевани приватни налог позиваоца, а затим на подразумевани дељени налог пројекта. Именовани налог који не може да се разреши бива одбијен са connector_not_connected — никада се не замењује прећутно — а одбијање наводи requested_account и available_accounts. Сваки успешан позив враћа податак о налогу под којим је извршен: result.account = { connection_id, label, owner_type }.

Више нема провере конектора при креирању сесије. Раније је сесија била одбијана са 409 CONNECTOR_CONNECTION_REQUIRED када обавезни конектор није имао употребљиву везу; тог одбијања више нема (require_connectors нема дејство — погледајте p.sessions). Провера је премештена на позив: одбијени connector_not_connected садржи connect_url, хостовани линк за ауторизацију, кад год може да се генерише за позиваоца — цео проблем решава се једним кликом, преко дугмета за повезивање у транскрипту.

p.policies — смернице пројекта

p.triggers — cron, webhook, мониторске и догађајне аутоматизације

Окидач покреће радњу агента према распореду, долазном webhook-у, надгледаној команди или догађају апликације на конектору. Погледајте Окидачи за стратегију сесије и шаблонизацију корисног садржаја.

create(input) прихвата { name, type: 'cron' | 'webhook' | 'monitor' | 'event', prompt_template, slug?, agent?, model?, enabled?, session_mode?, session_id?, cron?, run_at?, timezone?, secret_env?, connector?, event?, event_source?, event_account?, event_config?, session_access? }. name and prompt_template су обавезни. cron/run_at се међусобно искључују (type: 'cron'); secret_env ( HMAC тајна за webhook) примењује се на type: 'webhook'.

Окидач event захтева connector (slug конектора) и event (идентификатор типа из eventTypes). event_account је опционо: ознака једног дељеног налога тог конектора; null или изостављена вредност користи подразумевани дељени налог конектора. event_source је опционо: идентификатор адаптера извора догађаја, као што је composio. null или изостављена вредност користи провајдера конектора. Идентификатор типа припада том адаптеру. event_config се обликује према config_schema тог типа. eventTypes и eventApps приказују адаптер као source; provider је застарели алијас. Сваки наведени окидач садржи event: { connector, account, connected_as, type, config, source, provider, app, status: 'active' | 'needs_connection' | 'error' | 'pending', error, last_event_at } | null. Шаблони упита читају догађај као {{ event.data.<field> }} уз event.id, event.type, event.app, event.connector и event.occurred_at.

session_access одређује ко може да отвори сесије које окидач креира. Његов облик је { mode: 'private' | 'members' | 'project', memberIds: string[], groupIds: string[] } and defaults to private. Ова политика је стање извршавања локално за налог. Не улази у преносиви манифест beeuni.yaml. Ажурирање само session_access не креира Git комит. Закачена сесија задржава сопствена подешавања дељења. Менаџер пројекта увек може да отвори сесије које је креирао окидач, укључујући сесије које користе private или приступ за изабране чланове.

session_access је подешавање видљивости по ресурсу, додато моделу улога, а не улога. Одређује ко може да отвори сесије једног окидача. Не даје ниједну дозволу коју одлука на основу улоге одбија. Погледајте Налози и приступ.

p.marketplace / p.registry — инсталиране ставке

Инсталира датотеке ставке из каталога на подразумевану грану пројекта. registry.* је идентичан алијас за marketplace.*.

p.files — датотеке репозиторијума (читање)

Приступ git стаблу пројекта само за читање. За читање и писање датотека унутар активне сесије користите операције над датотекама те сесије — погледајте Датотеке у одељку Модули испод.

p.git — историја

p.changeRequests — животни циклус и спајање

Захтев за измену (CR) је начин на који се рад сесије спаја у подразумевану грану.

p.sessions — и објекат за приступ сесији

Објекат за приступ сесији је срж извршног окружења — погледајте Сесије.

create(input) прихвата connector_bindings са slug-ом везе конектора као кључем. Свака вредност именује connection_id. Такође прихвата secrets за сужавање скупа тајни које потичу из бекенда. require_connectors је застарео и неактиван: поље се и даље прихвата (стари клијент се никада не одбија зато што га шаље), али га ништа не чита — сесија се никада не одбија при креирању због конектора без употребљивог налога. Погледајте Налози и провера у тренутку позива.

p.approvals — пријемно сандуче за одобрења конектора

Радње условљене одобрењем конектора које чекају одлуку — основа за корисничко искуство одобравања дозвола (APPROVE / ASK / BLOCK).

p.gateway — надзор LLM-а

Евиденције захтева, збирни подаци о трошковима и кашњењу, буџети и API кључеви мрежног пролаза за саобраћај овог пројекта ка моделима.

Политика усмеравања садржи подразумевани модел, модел за вид и уређени ланац резервних модела, при чему се сваки модел испробава највише једном; fallbackOn је transient или any-error.

Мрежни пролаз прелази на следећи резервни модел само када тренутни модел откаже пре него што врати било какав излаз:

• transient: мрежна грешка, истек времена, било који 5xx или 402, 403, 429.
• any-error: сваки отказ, укључујући 400.

Отказ након што је излаз започео остаје везан за тај модел. Захтев са вашим сопственим кључем провајдера (BYOK) никада не прелази на модел који наплаћује Beeuni. Сваки резервни модел добија сопствене подразумеване поставке генерисања.

p.channels — Slack / имејл / глас

Интерфејси конектора који омогућавају агенту да делује као Slack апликација, имејл адреса или да се придружи гласовном позиву у реалном времену.

p.modelDefaults — подразумеване поставке модела

Подразумеване поставке модела на нивоу налога, агента и пројекта, које разрешава мрежни пролаз.

p.setDefaultAgent — подразумевани агент пројекта

p.setDefaultAgent(agentName) проверава да ли је агент декларисан и омогућен, а затим га поставља као default_agent у beeuni.yaml пројекта. Нове сесије дају предност овом агенту, осим ако корисник не изабере другог.

p.updateFeatureFlag — заставице функционалности

p.updateFeatureFlag(feature, enabled) укључује или искључује једну заставицу функционалности за пројекат. Проследите enabled: null да бисте уклонили замену и вратили се на подразумевану вредност платформе. Позива канонски PATCH /v1/projects/:id/features.

feature је један од FEATURE_FLAG_KEYS (извезен из @beeuni/sdk, типа FeatureFlagKey). Позиваоцу је потребна дозвола project.settings.write за пројекат; у супротном рута одговара са 403.

Свака рута условљена заставицом одбија захтев на исти начин док је заставица искључена: HTTP 403 са { error, code: "feature_disabled", feature }. Користите isFeatureDisabledError(error) за гранање на основу тога и featureDisabledKey(error) за читање кључа заставице — никада не проверавајте подударање текста поруке.

p.updateExperimentalFeature(feature, enabled) је застарели алијас. Он и даље позива застарели алијас руте PATCH /v1/projects/:id/experimental како би корисници везани за старији API у употреби наставили да раде. Користите p.updateFeatureFlag у новом коду.

p.sandbox — шаблони и израде снимака стања

Конфигурација израде изолованог окружења поред sandboxHealth/sandboxTemplates на објекту пројекта: шаблони за Dockerfile/слику/пул спремних окружења и њихове израде снимака стања.

Администраторски кукови платформе (@beeuni/sdk/react)

Ови кукови служе администраторској конзоли. API на њих одговара само администратору платформе. Свака мутација поништава упите ['admin', 'accounts'].

Излаз за посебне случајеве

beeuni.runtime() враћа типизовани runtime REST клијент за активни sandbox. На клијенту који је направио createScopedBeeuni (@beeuni/sdk/server), баца изузетак — „активно“ извршно окружење на нивоу целог процеса је sandbox другог захтева на серверу са више закупаца, што доводи до цурења података између закупаца. Уместо тога користите beeuni.session(pid, sid).runtime у опсегу сесије (прво позовите ensureReady()), који проналази sandbox те сесије.

Модули

Модули независни од радног оквира иза фасаде клијента и React хукова. Користите их када вам треба једна операција без фасаде, чиста помоћна функција или слој изолације само за Node. Сваки модул има ниво стабилности да бисте знали на чему можете да градите.

Коренска улазна тачка је канонска. Сваки назив испод који је независан од радног оквира може се увести директно из @beeuni/sdk:

import { files, getSessionHealth, getClient, authenticatedFetch, backendApi } from '@beeuni/sdk';

Канонски модули

Датотеке

import { files } from '@beeuni/sdk';

const tree = await files.list('/workspace/src');
const { content } = await files.read('/workspace/README.md');
const hits = await files.findText('TODO');
await files.upload(file, '/workspace/uploads', file.name, {
  onProgress: ({ loadedBytes, totalBytes }) => {
    console.log(`${loadedBytes}/${totalBytes}`);
  },
});

Отпремања већа од 64 KiB прелазе границу sandbox-а у провереним деловима. Повратни позив за напредак извршава се након што сваки део стигне у систем датотека сесије.

uploadNativeFile({ uri, name, type? }, targetPath, baseUrl) отпрема датотеку са уређаја из React Native-а у једном захтеву. Извршно окружење стримује бајтове из uri, тако да они никада не улазе у JS хип. Користи исту аутентификацију, крајњи рок и поновно извршавање 401 као files.upload. Не дели податке на сегменте.

fetchProjectArchive, fetchCostExportCsv и позиви верзије за sandbox шаљу податке преко истог транспорта. При неуспеху се баца ApiError са status.

files.write(path, blob) замењује датотеку на path и не успева ако је path фасцикла. files.create(path) прави празну датотеку и никада не преписује постојећу: када датотека или фасцикла већ постоји на path, баца FileExistsError (status 409, code 'FILE_EXISTS').

import { FileExistsError, files } from '@beeuni/sdk';

try {
  await files.create('/workspace/notes.md');
} catch (error) {
  if (error instanceof FileExistsError) console.log(`${error.path} already exists`);
  else throw error;
}

files циља глобално активан sandbox. Ако ваш хост истовремено покреће више од једне сесије, уместо тога позовите s.files на референци сесије. Он увек циља sandbox те сесије. Погледајте Сесије.

Помоћне функције извршног окружења сесије

import { getSessionHealth, isRuntimeReady } from '@beeuni/sdk';

const result = await getSessionHealth();
if (result.ok && isRuntimeReady(result.health)) {
  // the sandbox daemon is ready
}

getSessionHealth никада не баца изузетак за статус ван опсега 2xx. Враћа { status, ok, health, body } и препушта вам да одлучите шта статус значи. Исти модул извози URL помоћне функције које претварају излаз агента localhost у доступан прокси URL: detectLocalhostUrls, rewriteLocalhostUrl, proxyLocalhostUrl, parseLocalhostUrl и buildWebProxyUrl.

runtime клијент

import { getClient } from '@beeuni/sdk';

const client = getClient();
const { data } = await client.session.list({ limit: 100 });

getClient() враћа типизовани клијент за компатибилност са runtime за активан sandbox, са већ укљученом аутентификацијом. Дајте предност beeuni.session(pid, sid).runtime, истом клијенту ограниченом на једну сесију, уместо глобалног getClient() када ваш хост покреће више од једне сесије.

Помоћне функције за аутентификацију

import { authenticatedFetch, getAuthToken } from '@beeuni/sdk';

const res = await authenticatedFetch(`${runtimeUrl}/beeuni/health`);
const token = await getAuthToken();

Токен долази из функције getToken коју сте проследили у createBeeuni. Већини кода апликације овај модул није потребан — слојеви за датотеке, сесије и фасаду већ обављају аутентификацију за вас.

API клијент

import { backendApi } from '@beeuni/sdk';

const data = await backendApi.get('/some/endpoint');
await backendApi.post('/some/endpoint', { name: 'x' });

backendApi је типизовани HTTP клијент на коме се заснива свака REST функција. Користите га само за крајњу тачку која још нема типизовани омотач.

Листе агената и модела за састављач

Направите бирач агената и бирач модела у састављачу сесије по истим правилима која користи веб апликација Beeuni. Свака функција је чиста: преузмите улазне податке клијентом, па их проследите.

import {
  composerSelectableAgents,
  createModelVisibility,
  flattenModels,
  modelInDefaultView,
  pickerProviderList,
  projectConfigAgentsToRuntimeAgents,
  resolveComposerAgent,
  resolveComposerModel,
  resolveModelDefault,
} from '@beeuni/sdk';

// Agents: the roster, the picker list, and the agent the send carries.
const roster = projectConfigAgentsToRuntimeAgents(detail.config);
const pickerAgents = composerSelectableAgents(roster, { enableProjects: false });
const agent = resolveComposerAgent({
  agents: roster,
  boundAgent: session?.agent,
  defaultAgent: detail.config.default_agent,
  selectedAgent: pick,
});
if (agent.disabled) {
  // no accessible agent: refuse the send
}

// Models: gateway projects read /model-picker, native projects merge the
// catalog synthesis with the running sandbox's provider list.
const gatewayEnabled = detail.project.experimental?.llm_gateway === true;
const providers = pickerProviderList({
  gatewayEnabled,
  modelPicker,
  runtimeProviders,
  llmCatalogProviders,
  secretNames,
});
const models = flattenModels(providers, { providerMode: gatewayEnabled ? 'gateway' : 'native' });
const isVisible = createModelVisibility({ catalogModels: models });
const defaultView = models.filter(
  (m) => m.enabled !== false && modelInDefaultView(m, { search: '', isStoreVisible: isVisible, selected }),
);
const { model, explicit } = resolveComposerModel({
  models,
  picks: [sessionPick],
  serverDefault: resolveModelDefault(modelDefaults, agent.selected ?? undefined),
  providers,
});

resolveComposerModel враћа explicit: undefined када је састављач на подразумеваној поставци. model је кључ за приказ и слање. id сваког модела у изравнатој листи је референца коју избор чува; modelRefToKey(ref, gatewayEnabled) чита сачувану референцу (фиксирање сесије, везу канала, model окидача) и претвара је назад у кључ.

Подржане подпутање

Идентификатори порука протокола

messageId упита је његов положај у транскрипту. runtime поређа поруке по msg_ + 48-битном сату (Date.now() * 0x1000, доњих 48 битова) + 14 base62 знакова, а сат се враћа на почетак сваких 2^36 ms (око 2,2 године). Никада га не кодирајте ручно.

import { mintWireMessageId } from '@beeuni/sdk';

// `after`: the ids already in this session's transcript.
const messageId = mintWireMessageId({ after: transcriptIds });

Време генерисања се поставља два минута уназад, а затим помера за један корак изнад најновијег ID-а у after који је највише један сат у будућности. Позивалац који чува најновију позицију као време уместо као ID користи mintWireMessageIdAbove({ nowMs, newestKnownTime }), which returns { id, time }. newestWireIdClock(ids) проналази то време. Свако поређење се обавља на прстену, па ID-ови са обе стране преливања задржавају свој стварни редослед.

48-битни сат се прелива отприлике сваке 2,2 године, па никада не поредите два времена помоћу > или <=: ID генерисан непосредно после преливања бројчано је мањи од оног генерисаног непосредно пре њега. Користите wireIdClockDelta(clock, reference), растојање са предзнаком на прстену (позитивно када је clock испред), и maxWireIdClock(clocks) за најновији међу више њих:

import { maxWireIdClock, wireIdClockDelta } from '@beeuni/sdk/wire-message-id';

const floor = maxWireIdClock([transcriptNewest, deliveredNewest]);
const stale = floor !== null && wireIdClockDelta(clientClock, floor) <= 0n;

Изолација на страни сервера

createBeeuni чува своју конфигурацију, укључујући функцију за токен, у једној променљивој за цео процес. То је у реду за картицу прегледача, CLI или сервер за једног корисника. Није безбедно за Node сервер који обрађује истовремене захтеве различитих корисника, јер последњи позив createBeeuni важи за све захтеве који су у току. @beeuni/sdk/server то решава изолацијом по захтеву:

import { createScopedBeeuni } from '@beeuni/sdk/server';

export async function handler(req: Request) {
  const beeuni = createScopedBeeuni({ backendUrl, getToken: () => tokenFor(req) });
  return beeuni.projects.list();
}

createScopedBeeuni и runWithBeeuni изолују конфигурацију по захтеву помоћу Node механизма AsyncLocalStorage. Никада не увозите @beeuni/sdk/server из пакета за прегледач — он статички укључује node:async_hooks.

runtime() на највишем нивоу клијента са ограниченим опсегом баца изузетак (разрешио би изоловано окружење другог корисника). Приступите извршном окружењу одређене сесије преко beeuni.session(pid, sid).runtime после await s.ensureReady().

Застарели алијаси

Око двадесет старих потпутања и даље ради: /files, /turns, /session, /auth, /projects-client, /api-client, /config, /event-stream, /opencode-client, /platform-client и друге. Свака поново извози код који коренска улазна тачка @beeuni/sdk већ извози. Настављају да раде како ниједан постојећи import breaks, but new code should import from the root.

Интерни модули

@beeuni/sdk/internal/* садржи zustand складишта која извршно окружење apps/web користи интерно — стање синхронизације сесије, праћење активног извршног окружења и евиденцију поновног повезивања. Ова потпутања је изричито изван semver-а. Не увозите је у код домаћина; React hooks већ излажу стање које вам је потребно.

Размене

Обичне функције које групишу поруке сесије у размене и класификују сваки део поруке. Користите их да направите сопствени приказивач ћаскања уместо референтног у apps/web. Без React-а, без DOM-а — сваки извоз је обична функција или тип, безбедан за позивање из било ког домаћина.

import { classifyPart, classifyTurn, toolInfo, toolViewModel } from '@beeuni/sdk';

Увозите сваку функцију из коренске улазне тачке @beeuni/sdk. Потпутања @beeuni/sdk/turns и даље ради, али је застарели алијас. Нови код мора да користи коренску улазну тачку — погледајте Дистрибуција.

Класификација дела

classifyPart(part) нормализује један од 12 типова делова формата Beeuni транскрипта (beeuni.transcript.v1, BEEUNI_TRANSCRIPT_SCHEMA) у ClassifiedPart — унију са кључем kind. Свака варијанта већ разрешава поља која су приказивачу потребна: статус алата, рашчлањени JSON излаз, препознавање слике.

import { classifyPart, type ClassifiedPart } from '@beeuni/sdk';

for (const part of message.parts) {
  const classified: ClassifiedPart = classifyPart(part);
  switch (classified.kind) {
    case 'text':
      render(classified.text);
      break;
    case 'tool':
      render(classified.tool.title, classified.tool.status);
      break;
  }
}

Непрепознат део у преносном формату током извршавања прелази у unknown уместо да изазове изузетак. То омогућава старијем клијенту да комуницира са новијим сервером.

Део алата се класификује као ToolView:

interface ToolView {
  name: string;
  title: string;
  status: 'pending' | 'running' | 'done' | 'error';
  input?: Record<string, unknown>;
  output?: string;
  error?: string;
  outputParsed?: unknown; // JSON.parse(output) when it parses, capped at 256KB
  outputText?: string;    // the raw output text, always present
  kind?: ToolKind;        // toolKind(name): the action, whatever the harness calls the tool
  files?: ToolFile[];     // the files a file tool read, wrote or changed: path, patch, additions/deletions
  diff?: string;          // a unified diff of the change
  diagnostics?: Record<string, unknown[]>; // language-server diagnostics, keyed by file path
  answers?: string[][];   // the answers to a `question`, one list per question
  childSessionId?: string; // the child session a delegating call (`task`) runs
}

toToolView(part) га прави директно из дела алата. Читајте ова поља уместо сопственог state.metadata извршног окружења: иста картица тада приказује runtime edit (filePath, filediff) и pi edit (path, edits, обједињени patch).

Неки алати (web_search, image_search, позиви конектора) пријављују state.status: 'completed' чак и када њихово JSON тело садржи success: false. classifyPart то открива и поставља ToolView.status на 'error' и у том случају.

classifyTurn(message) класификује сваки део једне поруке асистента и враћа ClassifiedTurn са три поља:

• parts — сваки део, класификован
• error — из message.info.error, ако постоји
• isEmpty — тачно када потез нема грешку нити део са видљивим садржајем

Метаподаци алата

toolKind(name) је јединствена таксономија алата: пресликава назив алата из било ког извршног окружења (write из pi, oc-apply_patch из runtime, pty_spawn из додатка) у ToolKind — read, edit, write, bash, web_search, task, question, … или other. Породице нарације, модели приказа, категорије toolInfo и група контекстних алата изводе се из ње. inputPath(input) чита путању алата за датотеке из filePath, file_path или path.

toolKind('oc-apply_patch'); // 'apply_patch'
toolKind('pty_spawn');      // 'pty'
inputPath({ path: 'app.py' }); // 'app.py'

Још две функције за претрагу описују алат. Немојте их мешати.

• toolInfo(name) — без икона, враћа { label, category }. classifyPart то користи интерно. ToolCategory је 'shell' | 'files' | 'search' | 'edit' | 'web' | 'task' | 'other'.
• getToolInfo(name, input) — са подршком за иконе, враћа { icon, title, subtitle } за референтни кориснички интерфејс картице алата. Поднаслов долази из улазних података алата, на пример путање датотеке или упита за претрагу.

toolInfo('bash'); // { label: 'Shell', category: 'shell' }
getToolInfo('write', { filePath: '/workspace/main.go' });
// { icon: 'file-pen', title: 'Write', subtitle: 'main.go /workspace' }

Обе функције упарују префиксе назива алата, па се породице алата Beeuni додатака (agent_*, session_*, task_*, trigger_*, project_*, pty_*) разрешавају без ажурирања регистра. Непознат назив алата никада не изазива изузетак — користи се резервна вредност humanizeToolName(name) са категоријом 'other'.

Модели приказа алата

toolViewModel(classifiedTool) пресликава класификовани део алата у структуру направљену за једну породицу алата. Кориснички интерфејс тада може да га прикаже на посебан начин уместо као генерички JSON блок.

const vm = toolViewModel(classifiedTool);
if (vm.kind === 'shell') {
  render(vm.command, vm.stdout, vm.exitCode);
}

DiffLine је { type: 'added' | 'removed' | 'unchanged', text }. Дужина текстуалних поља је ограничена тако да један велики излаз алата никада не наруши приказ: 4000 знакова за форматирани JSON, 256KB пре израчунавања разлика.

Груписање порука у размене

Размена спаја једну корисничку поруку са порукама асистента које су на њу одговориле. То је јединица коју интерфејс ћаскања приказује као једну размену.

import { groupMessagesIntoTurns, collectTurnParts, type TurnLike } from '@beeuni/sdk';

const turns: TurnLike[] = groupMessagesIntoTurns(messages);
for (const turn of turns) {
  const parts = collectTurnParts(turn);
}

groupMessagesIntoTurns повезује сваку поруку асистента са њеном родитељском корисничком поруком. Ако родитељска веза недостаје, користи редослед порука. Такође придружује поруку асистента без родитеља — ону која претходи свим корисничким порукама — првој размени, а не последњој.

Повезане помоћне функције:

• findLastTextPart(parts) — текст коначног одговора у размени
• turnHasSteps(parts) — тачно ако постоји део tool, compaction, snapshot или patch
• isShellMode(turn) / getShellModePart(turn) — размена која се састоји од једног синтетичког упита који покреће један позив bash

Провере типа

Сузите тип дела помоћу type:

import { isTextPart, isToolPart, getPartText } from '@beeuni/sdk';

if (isTextPart(part)) {
  // part.type narrowed to 'text'
}
const text = getPartText(part); // works for 'text' and 'reasoning' parts

Доступно је и: isReasoningPart, isFilePart, isAgentPart, isCompactionPart, isSnapshotPart, isPatchPart, isStepPart (step-start и step-finish).

Статус и грешке

import { getWorkingState, getTurnStatus, formatDuration } from '@beeuni/sdk';

const status = getTurnStatus(parts, childMessages); // "Running commands..."
formatDuration(4300); // "4s" — durations under 1s return ''

getTurnStatus претражује делове размене да би пронашао последњи ред статуса. Када је последњи део делегирање task које је у току, проследите childMessages да статус приказује стварну активност подагента уместо општег реда „Делегирање…“.

import { getTurnError, getChildSessionError, unwrapError } from '@beeuni/sdk';

getTurnError(turn);                    // the first assistant error, unwrapped
getChildSessionError(childMessages);   // newest error in a sub-agent's messages
unwrapError(rawError);                 // normalizes double-JSON and mixed error shapes

Укупни трошкови и број токена

import { getTurnCost, getSessionCost, formatCost, formatTokens } from '@beeuni/sdk';

const info = getTurnCost(partsWithMessage, modelPricingLookup);
const sessionCost = getSessionCost(messages, modelPricingLookup);

formatCost(0.0032);  // "$0.003"
formatTokens(12345); // "12k"

Обе функције читају укупне трошкове и број токена из делова step-finish. Када део пријави нулу, процењују трошак на основу броја токена користећи ModelPricingLookup.

Поруке у оквиру ChatGPT/Codex претплате доприносе са $0.00, укључујући раније поруке са трошковима извршавања већим од нуле. Потрошња токена и контекста остаје видљива. Мешовите сесије задржавају накнаде за плаћене API поруке. OpenAI API модели и даље подлежу наплати, укључујући API моделе чији називи садрже codex.

Подређене сесије и захтеви на чекању

Стабло разговора сесије пројекта (корен и разговори подагената које је покренула) потиче из њене листе runtime_sessions. Ове помоћне функције је читају, дајући предност тренутним називима у односу на оне пре W4:

import { directSubsessions, projectSessionForRuntimeId, rootRuntimeSession, runtimeSessionsOf } from '@beeuni/sdk';

const root = rootRuntimeSession(projectSession);            // the root conversation id
const children = directSubsessions(projectSession);         // its subagent conversations
const owner = projectSessionForRuntimeId(projectSessions, childId); // the session a conversation belongs to

Позив алата task делегира задатак подређеној сесији. Ове помоћне функције повезују родитељску размену са порукама те подређене сесије.

import { getChildSessionId, getChildSessionToolParts } from '@beeuni/sdk';

const childId = getChildSessionId(taskToolPart);
const steps = getChildSessionToolParts(childMessages);

Повежите захтев за дозволу или питање на чекању са одговарајућим позивом алата и пронађите које делове алата треба сакрити док је такав захтев активан:

import { getPermissionForTool, getHiddenToolParts, isToolPartHidden } from '@beeuni/sdk';

const permission = getPermissionForTool(permissions, callID);
const hidden = getHiddenToolParts(activePermission, activeQuestion);

Форматирање и листе

import { getFilename, getDirectory, relativizePath, stripAnsi } from '@beeuni/sdk';

getFilename('/workspace/src/main.go');               // "main.go"
getDirectory('/workspace/src/main.go');               // "/workspace/src"
relativizePath('/workspace/src/main.go', '/workspace'); // "src/main.go"

Помоћне функције за листу сесија раде са истим подацима о сесијама:

import { sortSessions, childMapByParent, allDescendantIds } from '@beeuni/sdk';

sessions.sort(sortSessions(Date.now())); // pins sessions updated in the last 60s
const childMap = childMapByParent(sessions);
const descendants = allDescendantIds(childMap, sessionId);

Стање поновног покушаја: getRetryInfo(sessionStatus) враћа { attempt, message, next, details? } when status.type === 'retry', with message ограничен на 60 знакова. details чува структурирани омотач LLM мрежног пролаза када постоји: коначног провајдера, код мрежног пролаза, ID захтева, предлог, статус узводног сервиса и уређену листу неуспеха кандидата. Сваки неуспех кандидата садржи attempt, provider, routeModel, resolvedModel, stage, опциони status, code, и message. Стари поновни покушаји у обичном тексту враћају details: undefined. getRetryMessage(sessionStatus) враћа целу поруку без омотача. Када runtime задржи само ту поруку, сложени приказ мрежног пролаза и даље садржи ID захтева и провајдера, разрешени модел, HTTP статус, код и поруку ограничене дужине за сваког кандидата.

Структурни типови

Функције за груписање и статус прихватају минималне структурне типове — PartLike, MessageInfoLike, TurnLike, ToolStateLike, SessionStatusLike — уместо конкретних типова транскрипта. Ваши облици порука и делова пролазе непромењени све док одговарају обавезним пољима. classifyPart и classifyTurn су изузетак. Они су типизирани према Beeuni унији Part (beeuni.transcript.v1), па њихова провера исцрпности открива нови тип дела током изградње.

Дистрибуција

npm install @beeuni/sdk

Пакет се испоручује као компајлирани ESM са потпуним TypeScript декларацијама типова. react и @tanstack/react-query су опционе peer зависности. Ако користите @beeuni/sdk/react, инсталирајте обе.

import { createBeeuni } from '@beeuni/sdk'; // framework-free core
import { useSession } from '@beeuni/sdk/react'; // optional React layer
import { createScopedBeeuni } from '@beeuni/sdk/server'; // Node and Bun servers

Улазне тачке и стабилност

Коренска улазна тачка, @beeuni/sdk, је канонска. Извози цео API независан од фрејмворка и ради у прегледачима, Node 18+, Bun и edge извршним окружењима.

CDN пакети

Пакет садржи и два пакета за прегледач, изграђена помоћу tsup: ESM пакет (dist/beeuni.esm.min.js) и IIFE глобални објекат (dist/beeuni.global.js) који дефинише window.Beeuni.

<script src="https://unpkg.com/@beeuni/sdk/dist/beeuni.global.js"></script>
<script>
  const beeuni = Beeuni.createBeeuni({
    backendUrl: 'https://api.beeuni.ai/v1',
    getToken: async () => KEY,
  });
</script>

window.Beeuni излаже исту коренску улазну тачку као npm увоз: Beeuni.createBeeuni, Beeuni.classifyTurn, Beeuni.ApiError.

Погледајте и

• SDK — инсталација и ваша прва сесија.
• Сесије — животни циклус, стримовање и обрада грешака.
• React хукови — реактивни слој изграђен на овим модулима.

Приступ агента репозиторијуму

Конфигурација агента прихвата repository_access?: boolean (подразумевано true). Подесите false да бисте покретали нове сесије без репозиторијума пројекта или приступа API-ју репозиторијума. Дозволе за Git, тајне, конекторе и алате остају одвојене. Постојеће сесије задржавају своју сачувану политику. AgentConfigBlock.workspace је застарео. SDK пресликава старе вредности branch/runtime у логичко поље. Упис старе вредности read захтева изричит избор repository_access; он не омогућава приступ репозиторијуму само за читање.

Приступ провајдерима и моделима

Прочитајте beeuni.projects.modelAccess(projectId). Промените једно одредиште помоћу beeuni.projects.setModelAccess(projectId, { target: 'provider' | 'model', id, enabled }).

Користите ID провајдера beeuni за Beeuni Managed Models или ID провајдера из каталога за BYOK, Codex и прилагођене провајдере. За модел користите пун ID који се преноси преко мрежног пролаза. Онемогућавање провајдера обухвата будуће моделе и чува појединачна подешавања модела и сачуване акредитиве.

Тренутни подразумевани модел и његов провајдер захтевају замену пре онемогућавања (409 cannot_disable_default). Директни захтеви мрежном пролазу ка онемогућеним одредиштима не успевају, уз model_disabled или provider_disabled. Постојећи захтеви ка узводним сервисима који су у току завршавају се нормално. Заставица enforced у одговору има вредност false када пројекат користи изворни runtime уместо мрежног пролаза.

React клијенти користе useModelAccess(projectId) из @beeuni/sdk/react. Његова мутација setEnabled(change) освежава каталог за управљање и бирач сесија.