Riferimento SDK

L'intera superficie API di @beeuni/sdk — metodi client, moduli, turni e distribuzione.

Questa pagina descrive l’intera superficie API di @beeuni/sdk: tutti i metodi del client, i moduli indipendenti dai framework, gli helper per i turni e le modalità di distribuzione del pacchetto. Usa SDK per iniziare e Sessioni per approfondire il ciclo di vita delle sessioni.

Il client

createBeeuni(config) restituisce un client. Ogni metodo è una chiamata tipizzata all’API della piattaforma. Gli handle project(id) e session(pid, sid) associano gli ID così non devi mai ripeterli.

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

Account — beeuni.accounts

accounts.tokens genera chiavi API con ambito account (beeuni_pat_...). Vedi Autenticazione SDK per il modello completo dei token.

accounts.audit è il registro di ricostruzione aziendale. Combina le richieste API autenticate con gli eventi semantici di sessioni, connettori, approvazioni e computer.

Ogni evento include project_id, session_id, actor_type, source, outcome, request_id, trace_id e correlation_id quando l’azione li fornisce. L’API non memorizza corpi delle richieste, prompt, segreti, credenziali o argomenti non elaborati dei connettori nell’evento centralizzato. Gli eventi dei connettori possono includere un’anteprima limitata degli argomenti che oscura i campi riconducibili a credenziali e i dati opachi.

Assegnazioni di accesso

Beeuni ha un unico tipo di record di concessione: un’assegnazione. Associa un principal (user, group, service_account o pending) a un ruolo, in un ambito (account o un project), eventualmente limitato a un oggetto (agent, skill, secret, app o trigger) ed eventualmente contenente un expires_at. L’accesso di gruppo, l’accesso per risorsa e le associazioni a ruoli personalizzati sono tutte assegnazioni. Vedi Account e accesso per il modello.

La superficie REST canonica è:

L’SDK le espone come listAssignments, createAssignment, revokeAssignment e listPermissions. Una riga del catalogo contiene action, scope_type, resource_type, delegable, description, area, level e implies — leggila invece di codificare le stringhe delle azioni direttamente nel codice.

L’assegnazione di un ruolo personalizzato richiede l’abilitazione rbac dell’account; in sua assenza, la route risponde 402 con code: "entitlement_required".

Inviti all’account — beeuni.accountInvites

Accessibili con il solo token di invito — la persona invitata potrebbe non essere ancora un membro.

Progetti — beeuni.projects

provision crea un nuovo progetto; non avvia la sandbox di un progetto esistente. Avvia invece una sessione — vedi Sessioni.

Invia idempotency_key quando è possibile un nuovo tentativo — un ricaricamento, una seconda scheda, un timeout dopo il quale hai riprovato. provision genera un repository gestito completamente nuovo a ogni chiamata, quindi senza una chiave tutti questi casi creano progetti duplicati reali. Riutilizza una chiave per ogni tentativo di un’unica creazione logica e le ripetizioni restituiscono il progetto creato dal primo tentativo (201, stessi project_id, push_token: null). La chiave identifica il tentativo, non il payload — riutilizzarla con un name diverso restituisce il primo progetto e ignora il nuovo valore, quindi genera una nuova chiave per ogni creazione distinta. Creare un secondo progetto con lo stesso nome e senza chiave funziona comunque.

Una ripetizione che arriva mentre la prima chiamata sta ancora effettuando il provisioning riceve 409 con code: 'provision_in_flight' anziché un project_id che quella chiamata potrebbe ancora annullare. Riprova con la stessa chiave.

project(id).sessions.list({ scope: 'project' }) è un inventario del ciclo di vita per un chiamante con autorizzazioni di gestione del progetto. Aggiunge le sessioni accessibili non disponibili, warm e con eliminazione logica, con metadati sulla proprietà e sullo stato di esecuzione. Entrambi gli ambiti di elenco escludono tutte le sessioni che il chiamante non può aprire.

sessions.list e sessions.listPage accettano anche i filtri di gerarchia e attribuzione. Senza di essi, l’elenco rimane piatto e invariato.

Ogni riga di sessione ha parent_session_id e initiator ({ type: 'member' | 'trigger' | 'channel' | 'api' | 'system', id, label }). initiator indica chi ha avviato l’intera esecuzione; una sessione figlia copia quello della sessione padre. sessionParentId(session) legge parent_session_id, poi il precedente metadata.spawned_by_session. Un cursore è valido solo per l’insieme di filtri che lo ha generato.

GitHub — beeuni.github

Installazione della GitHub App e collegamento dei repository con ambito account, non con ambito progetto.

Questo elenco contiene solo connessioni reali degli account. “Beeuni managed” non è una di queste — è il backend dell’istanza descritto di seguito.

Backend git dell’istanza — beeuni.gitBackend

Un unico proprietario con credenziale per l’intero deployment, usato per i repository gestiti da Beeuni. Non è mai una connessione di account e non compare mai in beeuni.github.listInstallations.

Fatturazione — beeuni.billing

Legge crediti, abbonamento, piano e cronologia delle transazioni. Usa il pagamento e la gestione della fatturazione Beeuni per i pagamenti e gli acquisti di crediti.

sessionCosts.list() accetta accountId, projectId, limit e offset. Ogni riga combina il costo LLM definitivo e il costo di calcolo della sandbox fatturato. sessionCosts.get() aggiunge l’utilizzo dei modelli e il registro con distinzione tra LLM e calcolo. L’elenco include un totale di riconciliazione per i costi senza sessione.

Condivisioni della sandbox — beeuni.sandboxShares

Link di condivisione pubblici per una porta esposta della sandbox. Limitati alla sandbox, non al progetto.

Catalogo del marketplace — beeuni.marketplace

Consultazione del catalogo pubblico, in sola lettura — distinta da project(id).marketplace, che installa un elemento in un progetto.

Notifiche — beeuni.notifications

Le notifiche del chiamante, per tutti gli account e i progetti. Ogni persona che ha effettuato l’accesso ha una casella di posta, un record di preferenze e sottoscrizioni Web Push per i propri browser. Ogni metodo richiede la credenziale di una persona: un account di servizio riceve 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 } } });

Tipi (InboxNotificationKind, elencati in INBOX_NOTIFICATION_KINDS):

DEFAULT_NOTIFICATION_PREFERENCES contiene questi valori predefiniti. La riga nella casella di posta viene sempre scritta; le preferenze determinano solo push ed email. Un’email di riepilogo elenca le righe ancora non lette 15 minuti dopo il loro arrivo, con al massimo un riepilogo all’ora. Nascondi la colonna email quando email_available è false.

Il url di ogni riga ne apre l’oggetto. Il suo parametro di query ?notification=<id> consente alla pagina di segnare la riga come letta.

L’handle della sessione contiene lo stato con cui il chiamante segue una sessione:

L’handle del progetto — beeuni.project(id)

Associa l’ID del progetto; tutte le sottorisorse dipendono da esso.

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

p.tokens — chiavi API con ambito di progetto

Generate automaticamente alla creazione della sessione come BEEUNI_TOKEN; possono anche essere generate manualmente.

p.setupLinks — link di configurazione generati dall’agente

Un link che una persona apre per inserire un segreto o collegare un’app, senza accesso completo al progetto.

p.apps — Apps (release, macchine, volumi)

Richiede la funzionalità di progetto apps. Guida: SDK → Apps.

p.secrets — segreti del progetto

runtime con consumer sandbox è l’esposizione environment — quella predefinita, e l’unica policy che inserisce un valore in chiaro nella sessione. egress con consumer network è l’esposizione egress-enforced: la sessione contiene un handle e Beeuni sostituisce il valore reale fuori dalla sandbox, per gli esatti host HTTPS elencati dalla policy. L’esposizione egress-enforced è sperimentale; richiede il flag di funzionalità secrets_egress (Settings → Feature flags). Con il flag disattivato, setStrategy(identifier, 'egress', …) e upsert(...) con una policy egress restituiscono 403 feature_disabled. Nessun consumer broker è presente nella sessione. Vedi Segreti. Il metodo broker(...) richiede un token con ambito di sessione e un handle di sessione attivo.

p.access — assegnazioni, inviti e richieste del progetto

Ogni metodo qui legge o scrive un’assegnazione con ambito limitato a questo progetto. I ruoli del progetto sono manager e member.

p.access.resourceGrants è la vista assegnazione di oggetti: limita un soggetto a un solo oggetto nel progetto anziché all’intero progetto. Beeuni applica attualmente le assegnazioni di oggetti ad agenti e skill. Un agente è chiuso per impostazione predefinita — un membro vi accede solo quando un’assegnazione indica lui o uno dei suoi gruppi. Un’assegnazione di oggetti non conferisce autorizzazioni proprie e limita un responsabile di progetto tanto quanto un membro.

p.connector(slug) — un connettore

options: account, approvalContext, timeoutMs (valore predefinito 90 000), signal. Con il file di beeuni connectors types, gli argomenti e l’output sono tipizzati.

p.connectors — connettori di strumenti

p.connectors.discover esplora il catalogo dei connettori diretti. È sperimentale e disattivato per impostazione predefinita — abilitalo per ciascun progetto in Settings → Feature flags → “Connectors API Discover”. Easy Connect resta il marketplace predefinito dei connettori.

p.connectors.pipedream è il percorso di compatibilità OAuth gestito precedente; listApps restituisce solo le app OAuth. Usa Easy Connect per le nuove integrazioni gestite. Collega direttamente le app con chiave API.

Un connettore definisce lo strumento, l’app del provider e i criteri. connections memorizza i suoi account collegati: un connettore può contenerne diversi affiancati. Una sessione può fissarne uno per ogni chiamata con connector_bindings: { alias: { connection_id } }, oppure una singola chiamata può specificarne uno con call(tool, args, { account }). Le credenziali restano crittografate e vengono risolte per richiesta.

connections è l’unica facciata di autorizzazione attiva. I nomi ritirati authorizations e profiles non fanno parte della superficie dell’SDK attuale.

Account e controllo al momento della chiamata

Ogni connessione ha un owner_type: project (condiviso — raggiungibile da chiunque abbia accesso al connettore, persona o account di servizio) oppure member (privato — raggiungibile solo dal relativo proprietario e solo in una sessione privata; mai da un account di servizio). Un account condiviso può essere limitato a gruppi e persone: connections.list() restituisce le autorizzazioni in shared_with e connectionSharedWithEveryone(connection) indica se tutti gli utenti del progetto possono usarlo. Un account limitato segue le regole private per le persone indicate e usable: false contrassegna quello che il chiamante vede solo per amministrarlo. Concedi o revoca l’accesso con createAssignment / revokeAssignment (object: { type: 'connection', id }) — vedi Chi può usare un account condiviso. p.connectors.accounts(slug) elenca ogni account raggiungibile da questo chiamante, con quello predefinito per primo:

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`
);

Una chiamata che non specifica alcun account risolve prima l’account privato predefinito del chiamante, poi l’account condiviso predefinito del progetto. Un account specificato che non viene risolto è negato con connector_not_connected — non viene mai sostituito automaticamente — e il rifiuto elenca requested_account e available_accounts. Ogni chiamata riuscita indica con quale account è stata eseguita: result.account = { connection_id, label, owner_type }.

Non esiste più un controllo del connettore al momento della creazione della sessione. In precedenza una sessione veniva rifiutata con 409 CONNECTOR_CONNECTION_REQUIRED quando un connettore richiesto non aveva una connessione utilizzabile; quel rifiuto è stato rimosso (require_connectors è inattivo — vedi p.sessions). Il controllo è stato spostato sulla chiamata: un connector_not_connected negato include connect_url, un link di autorizzazione ospitato, ogni volta che è possibile generarlo per il chiamante — l’intero rimedio richiede un solo clic ed è esposto dal pulsante di collegamento della trascrizione.

p.policies — criteri del progetto

p.triggers — automazioni cron, webhook, monitor ed eventi

Un trigger avvia un’azione dell’agente in base a una pianificazione, a un webhook in ingresso, a un comando monitorato o a un evento dell’app su un connettore. Vedi Trigger per la strategia della sessione e la modellazione del payload.

create(input) accetta { 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 sono obbligatori. cron/run_at sono mutuamente esclusivi (type: 'cron'); secret_env (il segreto HMAC del webhook) si applica a type: 'webhook'.

Un trigger event richiede connector (uno slug del connettore) e event (un ID del tipo da eventTypes). event_account è opzionale: l’etichetta di un account condiviso di quel connettore; null o l’omissione usa l’account condiviso predefinito del connettore. event_source è opzionale: l’ID dell’adattatore della sorgente di eventi, ad esempio composio. null o l’omissione usa il provider del connettore. L’ID del tipo appartiene a quell’adattatore. event_config segue la struttura definita da config_schema del tipo. eventTypes e eventApps riportano l’adattatore come source; provider è un alias deprecato. Ogni trigger elencato contiene event: { connector, account, connected_as, type, config, source, provider, app, status: 'active' | 'needs_connection' | 'error' | 'pending', error, last_event_at } | null. I modelli di prompt leggono l’evento come {{ event.data.<field> }} più event.id, event.type, event.app, event.connector e event.occurred_at.

session_access controlla chi può aprire le sessioni create dal trigger. È { mode: 'private' | 'members' | 'project', memberIds: string[], groupIds: string[] } and defaults to private. Questo criterio è uno stato di runtime locale all’account. Non entra nel manifest portabile beeuni.yaml. L’aggiornamento del solo session_access non crea alcun commit Git. Una sessione fissata mantiene le proprie impostazioni di condivisione. Un responsabile del progetto può sempre aprire le sessioni create dai trigger, comprese quelle che usano private o l’accesso a membri selezionati.

session_access è un’impostazione di visibilità per risorsa che si aggiunge al modello dei ruoli, non un ruolo. Decide chi può aprire le sessioni di un trigger. Non concede alcuna autorizzazione negata dal verdetto del ruolo. Vedi Account e accesso.

p.marketplace / p.registry — elementi installati

Installa i file di un elemento del catalogo nel branch predefinito del progetto. registry.* è un alias identico di marketplace.*.

p.files — file del repository (lettura)

Accesso in sola lettura all’albero git del progetto. Per leggere e scrivere file all’interno di una sessione in esecuzione, usa le operazioni sui file della sessione — vedi File nella sezione Moduli.

p.git — cronologia

p.changeRequests — ciclo di vita e merge

Una richiesta di modifica (CR) è il modo in cui il lavoro di una sessione viene unito al branch predefinito.

p.sessions — e l’handle della sessione

L’handle della sessione è il cuore del runtime — vedi Sessioni.

create(input) accetta connector_bindings con lo slug della connessione del connettore come chiave. Ogni valore identifica un connection_id. Accetta anche secrets per limitare i segreti provenienti dal backend. require_connectors è deprecato e inattivo: il campo è ancora accettato (un vecchio client non viene mai rifiutato perché lo invia), ma nulla lo legge — una sessione non viene mai rifiutata al momento della creazione per un connettore senza un account utilizzabile. Vedi Account e controllo al momento della chiamata.

p.approvals — la casella delle approvazioni dei connettori

Azioni soggette al controllo dei connettori in attesa di una decisione — supporta la UX di approvazione delle autorizzazioni (APPROVE / ASK / BLOCK).

p.gateway — osservabilità degli LLM

Log delle richieste, aggregazioni di costi/latenza, budget e chiavi API del gateway per il traffico verso i modelli di questo progetto.

Una politica di instradamento contiene un modello predefinito, un modello per la visione e una catena ordinata di fallback; ogni modello viene tentato al massimo una volta; fallbackOn è transient o any-error.

Il gateway passa al modello di fallback successivo solo quando il modello corrente ha fallito prima di restituire qualsiasi output:

• transient: un errore di rete, un timeout, qualsiasi 5xx oppure 402, 403, 429.
• any-error: ogni errore, incluso un 400.

Un errore dopo l’inizio dell’output resta associato a quel modello. Una richiesta con la propria chiave del provider (BYOK) non passa mai a un modello fatturato da Beeuni. Ogni modello di fallback riceve i propri valori predefiniti di generazione.

p.channels — Slack / email / voce

Interfacce dei connettori che consentono a un agente di agire come app Slack, come indirizzo email o di partecipare a una chiamata vocale in tempo reale.

p.modelDefaults — preferenze del modello predefinito

Valori predefiniti dei modelli a livello di account, agente e progetto, risolti dal gateway.

p.setDefaultAgent — agente predefinito del progetto

p.setDefaultAgent(agentName) verifica che l’agente sia dichiarato e abilitato, poi lo imposta come default_agent nel beeuni.yaml del progetto. Le nuove sessioni preferiscono questo agente, a meno che un utente non ne scelga un altro.

p.updateFeatureFlag — flag di funzionalità

p.updateFeatureFlag(feature, enabled) attiva o disattiva un flag di funzionalità per il progetto. Passa enabled: null per cancellare la sovrascrittura e tornare al valore predefinito della piattaforma. Chiama il PATCH /v1/projects/:id/features canonico.

feature è uno dei FEATURE_FLAG_KEYS (esportati da @beeuni/sdk, con tipo FeatureFlagKey). Il chiamante deve avere l’autorizzazione project.settings.write del progetto; altrimenti la route risponde con 403.

Ogni route controllata da un flag rifiuta le richieste allo stesso modo quando il flag è disattivato: HTTP 403 con { error, code: "feature_disabled", feature }. Usa isFeatureDisabledError(error) per gestire il caso e featureDisabledKey(error) per leggere la chiave del flag — non basarti mai sul testo del messaggio.

p.updateExperimentalFeature(feature, enabled) è l’alias deprecato. Continua a chiamare l’alias deprecato della route PATCH /v1/projects/:id/experimental così i consumer vincolati a una versione precedente dell’API distribuita continuano a funzionare. Usa p.updateFeatureFlag nel nuovo codice.

p.sandbox — template e build degli snapshot

Configurazione delle build delle sandbox oltre a sandboxHealth/sandboxTemplates sull’handle del progetto: template Dockerfile/immagine/warm pool e relative build degli snapshot.

Hook di amministrazione della piattaforma (@beeuni/sdk/react)

Questi hook servono la console di amministrazione. L’API risponde solo agli amministratori della piattaforma. Ogni mutazione invalida le query ['admin', 'accounts'].

Via di uscita

beeuni.runtime() restituisce il client REST runtime tipizzato per la sandbox attiva. Su un client creato da createScopedBeeuni (@beeuni/sdk/server), genera un’eccezione — il runtime “attivo” globale del processo è la sandbox di un’altra richiesta in un server multi-tenant, una fuga di dati tra tenant. Usa invece beeuni.session(pid, sid).runtime con ambito di sessione (chiama prima ensureReady()), che risolve la sandbox della sessione stessa.

Moduli

I moduli indipendenti dal framework alla base della facciata del client e degli hook React. Usali quando ti serve una singola operazione senza la facciata, un helper puro o un livello di isolamento solo per Node. Ogni modulo indica un livello di stabilità, così sai su cosa basarti.

Il punto di ingresso radice è canonico. Ogni nome indipendente dai framework elencato sotto è importabile direttamente da @beeuni/sdk:

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

Moduli canonici

File

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}`);
  },
});

I caricamenti superiori a 64 KiB attraversano il confine della sandbox in blocchi verificati. La callback di avanzamento viene eseguita dopo che ogni blocco raggiunge il filesystem della sessione.

uploadNativeFile({ uri, name, type? }, targetPath, baseUrl) carica un file del dispositivo da React Native in un’unica richiesta. Il runtime trasmette i byte in streaming da uri, quindi non entrano mai nell’heap JS. Usa la stessa autenticazione, scadenza e ripetizione 401 di files.upload. Non suddivide in blocchi.

fetchProjectArchive, fetchCostExportCsv e le chiamate alla versione della sandbox inviano tramite lo stesso trasporto. Un errore genera un’eccezione ApiError con status.

files.write(path, blob) sostituisce il file in path e fallisce se path è una cartella. files.create(path) crea un file vuoto e non sovrascrive mai: quando un file o una cartella esiste già in path, genera 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 opera sulla sandbox attiva a livello globale. Se il tuo host esegue più di una sessione alla volta, chiama invece s.files sull’handle della sessione. Opera sempre sulla sandbox di quella sessione. Vedi Sessioni.

Funzioni ausiliarie del runtime di sessione

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

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

getSessionHealth non genera mai eccezioni per uno stato non 2xx. Restituisce { status, ok, health, body } e ti lascia decidere cosa significa uno stato. Lo stesso modulo esporta le funzioni ausiliarie per gli URL che riscrivono l’output localhost di un agente in un URL proxy raggiungibile: detectLocalhostUrls, rewriteLocalhostUrl, proxyLocalhostUrl, parseLocalhostUrl e buildWebProxyUrl.

Client runtime

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

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

getClient() restituisce il client di compatibilità runtime tipizzato per la sandbox attiva, con l’autenticazione già inserita. Preferisci beeuni.session(pid, sid).runtime, lo stesso client limitato a una sessione, al globale getClient() quando il tuo host esegue più di una sessione.

Funzioni ausiliarie di autenticazione

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

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

Il token proviene dalla funzione getToken che hai passato a createBeeuni. La maggior parte del codice dell’app non ha bisogno di questo modulo: i livelli dei file, delle sessioni e della facciata eseguono già l’autenticazione per te.

Client API

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

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

backendApi è il client HTTP tipizzato su cui si basa ogni funzione REST. Usalo solo per un endpoint che non ha ancora un wrapper tipizzato.

Elenchi di agenti e modelli del compositore

Crea i selettori di agenti e modelli di un compositore di sessione con le stesse regole usate dall’app web Beeuni. Ogni funzione è pura: recupera gli input con il client, poi passali alla funzione.

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 restituisce explicit: undefined quando il compositore usa l’impostazione predefinita. model è la chiave da visualizzare e inviare. Il id di ogni modello appiattito è il riferimento memorizzato da una selezione; modelRefToKey(ref, gatewayEnabled) riconverte un riferimento memorizzato (un elemento fissato alla sessione, un’associazione di canale, il model di un trigger) in una chiave.

Sottopercorsi supportati

ID dei messaggi del protocollo

Il messageId di un prompt è la sua posizione nella trascrizione. runtime ordina i messaggi per msg_ + un orologio a 48 bit (Date.now() * 0x1000, i 48 bit meno significativi) + 14 caratteri base62, e l’orologio riparte da zero ogni 2^36 ms (circa 2,2 anni). Non codificarlo mai a mano.

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

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

La generazione viene retrodatata di due minuti, poi portata un tick oltre l’ID più recente in after che sia al massimo un’ora avanti. Un chiamante che conserva la posizione più recente come orologio anziché come ID usa mintWireMessageIdAbove({ nowMs, newestKnownTime }), which returns { id, time }. newestWireIdClock(ids) per trovare quell’orologio. Ogni confronto avviene sull’anello, quindi gli ID ai due lati di un ritorno a zero mantengono il loro ordine effettivo.

L’orologio a 48 bit riparte da zero ogni ~2,2 anni, quindi non confrontare mai due orologi con > o <=: un ID generato subito dopo un ritorno a zero è numericamente inferiore a uno generato subito prima. Usa wireIdClockDelta(clock, reference), la distanza con segno sull’anello (positiva quando clock è avanti), e maxWireIdClock(clocks) per il più recente tra diversi valori:

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

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

Isolamento lato server

createBeeuni memorizza la propria configurazione, inclusa la funzione del token, in una variabile globale del processo. Va bene per una scheda del browser, una CLI o un server single-tenant. Non è sicuro per un server Node che gestisce richieste simultanee per utenti diversi, perché l’ultima chiamata a createBeeuni prevale per ogni richiesta in corso. @beeuni/sdk/server risolve il problema con l’isolamento per richiesta:

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

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

createScopedBeeuni e runWithBeeuni isolano la configurazione per richiesta con AsyncLocalStorage di Node. Non importare mai @beeuni/sdk/server da un bundle per il browser: include staticamente node:async_hooks.

Il runtime() di primo livello di un client con ambito limitato genera un’eccezione (risolverebbe la sandbox di un altro tenant). Accedi al runtime di una sessione specifica tramite beeuni.session(pid, sid).runtime dopo await s.ensureReady().

Alias deprecati

Circa venti vecchi sottopercorsi funzionano ancora: /files, /turns, /session, /auth, /projects-client, /api-client, /config, /event-stream, /opencode-client, /platform-client e altri. Ognuno riesporta codice già esportato dal punto di ingresso radice @beeuni/sdk. Restano funzionanti affinché nessun elemento esistente import breaks, but new code should import from the root.

Moduli interni

@beeuni/sdk/internal/* contiene gli store zustand che il runtime di apps/web usa internamente: stato di sincronizzazione della sessione, monitoraggio del runtime attivo e gestione delle riconnessioni. Questo sottopercorso è esplicitamente fuori da semver. Non importarlo nel codice host; gli Hook React espongono già lo stato di cui hai bisogno.

Turni

Funzioni semplici che raggruppano i messaggi di sessione in turni e classificano ogni parte di messaggio. Usale per creare un renderer di chat personalizzato anziché quello di riferimento in apps/web. Niente React, niente DOM: ogni esportazione è una semplice funzione o un tipo, richiamabile in sicurezza da qualsiasi host.

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

Importa ogni funzione dal punto di ingresso radice @beeuni/sdk. Il sottopercorso @beeuni/sdk/turns funziona ancora, ma è un alias deprecato. Il nuovo codice deve usare il punto di ingresso radice — vedi Distribuzione.

Classificare una parte

classifyPart(part) normalizza uno dei 12 tipi di parte del formato di trascrizione Beeuni (beeuni.transcript.v1, BEEUNI_TRANSCRIPT_SCHEMA) in un ClassifiedPart — un’unione indicizzata da kind. Ogni variante risolve già i campi necessari a un renderer: stato dello strumento, output JSON analizzato, rilevamento delle immagini.

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;
  }
}

Una parte wire non riconosciuta viene degradata a unknown in fase di runtime invece di lanciare un’eccezione. Questo consente a un client meno recente di comunicare con un server più recente.

Una parte di strumento viene classificata in 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) ne crea una direttamente da una parte di strumento. Leggi questi campi invece del personale state.metadata dell’harness: la stessa scheda restituisce quindi un edit di runtime (filePath, filediff) e un edit di pi (path, edits, un patch unificato).

Alcuni strumenti (web_search, image_search, chiamate ai connector) segnalano state.status: 'completed' anche quando il loro corpo JSON contiene success: false. classifyPart lo rileva e imposta ToolView.status su 'error' anche in questo caso.

classifyTurn(message) classifica ogni parte di un messaggio dell’assistente e restituisce un ClassifiedTurn con tre campi:

• parts — ogni parte, classificata
• error — da message.info.error, se presente
• isEmpty — true quando il turno non contiene errori né parti con contenuto visibile

Metadati degli strumenti

toolKind(name) è l’unica tassonomia degli strumenti: associa il nome dello strumento di qualsiasi harness (write di pi, oc-apply_patch di runtime, pty_spawn di un plugin) a un ToolKind — read, edit, write, bash, web_search, task, question, … oppure other. Le famiglie di narrazione, i view model, le categorie toolInfo e il gruppo degli strumenti di contesto derivano tutti da essa. inputPath(input) legge il percorso di uno strumento file da filePath, file_path o path.

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

Altre due lookup descrivono entrambe uno strumento. Non confonderle.

• toolInfo(name) — senza icona, restituisce { label, category }. classifyPart la usa internamente. ToolCategory è 'shell' | 'files' | 'search' | 'edit' | 'web' | 'task' | 'other'.
• getToolInfo(name, input) — consapevole dell’icona, restituisce { icon, title, subtitle } per l’interfaccia di riferimento delle schede degli strumenti. Il sottotitolo deriva dall’input dello strumento, ad esempio un percorso file o una query di ricerca.

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

Entrambe le funzioni verificano i prefissi dei nomi degli strumenti, quindi le famiglie di strumenti plugin di Beeuni (agent_*, session_*, task_*, trigger_*, project_*, pty_*) vengono risolte senza aggiornare il registro. Un nome di strumento sconosciuto non genera mai un’eccezione: ricade su humanizeToolName(name) con categoria 'other'.

View model degli strumenti

toolViewModel(classifiedTool) associa una parte di strumento classificata a una forma costruita per una famiglia di strumenti. L’interfaccia può quindi visualizzarla in modo specifico anziché come un generico blob JSON.

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

DiffLine è { type: 'added' | 'removed' | 'unchanged', text }. I campi stringa sono limitati, così un singolo output di strumento molto grande non interrompe il rendering: 4000 caratteri per il JSON formattato, 256 KB prima dell’esecuzione di un diff.

Raggruppare i messaggi in turni

Un turno associa un messaggio dell’utente ai messaggi dell’assistente che vi hanno risposto. È l’unità che un’interfaccia chat visualizza come un unico scambio.

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

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

groupMessagesIntoTurns collega ogni messaggio dell’assistente al relativo messaggio dell’utente. Se manca un collegamento al genitore, usa l’ordine dei messaggi. Collega inoltre un messaggio dell’assistente orfano — uno senza genitore che precede ogni messaggio dell’utente — al primo turno, non all’ultimo.

Helper correlati:

• findLastTextPart(parts) — il testo della risposta finale del turno
• turnHasSteps(parts) — true se esiste una parte tool, compaction, snapshot o patch
• isShellMode(turn) / getShellModePart(turn) — un turno costituito da un prompt sintetico che esegue una chiamata bash

Type guard

Riduci il tipo di una parte tramite 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

Sono disponibili anche: isReasoningPart, isFilePart, isAgentPart, isCompactionPart, isSnapshotPart, isPatchPart, isStepPart (step-start e step-finish).

Stato ed errori

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

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

getTurnStatus analizza le parti di un turno alla ricerca dell’ultima riga di stato. Quando l’ultima parte è una delega task in esecuzione, passa childMessages affinché lo stato mostri l’attività effettiva del sottoagente anziché una riga generica “Delegating…”.

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

Totali di costi e token

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"

Entrambe le funzioni leggono i totali di costi e token dalle parti step-finish. Quando una parte segnala zero, stimano il costo dai conteggi dei token usando un ModelPricingLookup.

I messaggi degli abbonamenti ChatGPT/Codex contribuiscono $0.00, inclusi i messaggi storici con costi runtime diversi da zero. L’utilizzo di token e contesto resta visibile. Le sessioni miste conservano gli addebiti per i messaggi API a pagamento. I modelli API OpenAI restano fatturabili, inclusi i modelli API i cui nomi contengono codex.

Sessioni figlie e richieste in sospeso

L’albero delle conversazioni di una sessione di progetto (la radice e le conversazioni degli sottoagenti che ha creato) proviene dal suo elenco runtime_sessions. Questi helper lo leggono, preferendo i nomi attuali a quelli precedenti a 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

Una chiamata allo strumento task delega a una sessione figlia. Questi helper collegano un turno padre ai messaggi propri di quella sessione figlia.

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

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

Abbina una richiesta di autorizzazione o domanda in sospeso alla relativa chiamata dello strumento e individua quali parti dello strumento nascondere mentre è attiva:

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

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

Formattazione ed elenchi

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"

Gli helper degli elenchi di sessioni operano sugli stessi dati di sessione:

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);

Stato del nuovo tentativo: getRetryInfo(sessionStatus) restituisce { attempt, message, next, details? } when status.type === 'retry', with message limitato a 60 caratteri. details conserva, quando presente, un envelope strutturato del gateway LLM: il provider finale, il codice del gateway, l’ID della richiesta, il suggerimento, lo stato upstream e gli errori candidati ordinati. Ogni errore candidato contiene attempt, provider, routeModel, resolvedModel, stage, status opzionale, code, e message. I nuovi tentativi in testo semplice legacy restituiscono details: undefined. getRetryMessage(sessionStatus) restituisce il messaggio completo senza envelope. Quando runtime conserva solo quel messaggio, il composito del gateway include comunque l’ID della richiesta e il provider, il modello risolto, lo stato HTTP, il codice e il messaggio limitato di ciascun candidato.

Tipi strutturali

Le funzioni di raggruppamento e stato accettano tipi strutturali minimi — PartLike, MessageInfoLike, TurnLike, ToolStateLike, SessionStatusLike — invece dei tipi concreti delle trascrizioni. Le forme del tuo messaggio e delle tue parti passano senza modifiche, purché corrispondano ai campi richiesti. classifyPart e classifyTurn fanno eccezione. Sono tipizzati rispetto all’unione Beeuni Part (beeuni.transcript.v1), quindi il loro controllo di esaustività rileva un nuovo tipo di parte in fase di compilazione.

Distribuzione

npm install @beeuni/sdk

Il pacchetto viene distribuito come ESM compilato con dichiarazioni di tipo TypeScript complete. react e @tanstack/react-query sono dipendenze peer facoltative. Se usi @beeuni/sdk/react, installale entrambe.

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

Punti di ingresso e stabilità

Il punto di ingresso principale, @beeuni/sdk, è quello canonico. Esporta l’intera superficie indipendente dai framework ed è eseguibile nei browser, in Node 18+, Bun e negli ambienti edge.

Bundle CDN

Il pacchetto include anche due bundle per browser, compilati da tsup: un bundle ESM (dist/beeuni.esm.min.js) e un globale IIFE (dist/beeuni.global.js) che definisce 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 espone lo stesso punto di ingresso principale dell’import npm: Beeuni.createBeeuni, Beeuni.classifyTurn, Beeuni.ApiError.

Vedi anche

• SDK — installazione e prima sessione.
• Sessioni — ciclo di vita, streaming e gestione degli errori.
• Hook React — il livello reattivo basato su questi moduli.

Accesso al repository dell’agente

La configurazione dell’agente accetta repository_access?: boolean (predefinito true). Imposta false per eseguire nuove sessioni senza il repository del progetto o l’accesso all’API del repository. Le autorizzazioni Git, per i segreti, per i connettori e per gli strumenti restano separate. Le sessioni esistenti conservano i criteri salvati. AgentConfigBlock.workspace è deprecato. L’SDK mappa branch/runtime legacy al campo booleano. Una scrittura legacy di read richiede una scelta esplicita di repository_access; non abilita l’accesso in sola lettura al repository.

Accesso a provider e modelli

Leggi beeuni.projects.modelAccess(projectId). Modifica un singolo target con beeuni.projects.setModelAccess(projectId, { target: 'provider' | 'model', id, enabled }).

Usa l’ID provider beeuni per i modelli gestiti da Beeuni, oppure l’ID di un provider del catalogo per BYOK, Codex e i provider personalizzati. Usa l’ID wire completo del gateway per un modello. La disabilitazione di un provider si applica ai modelli futuri e conserva le preferenze dei singoli modelli e le credenziali salvate.

Il modello predefinito corrente e il relativo provider richiedono una sostituzione prima della disabilitazione (409 cannot_disable_default). Le richieste dirette al gateway verso target disabilitati non vanno a buon fine con model_disabled o provider_disabled. Le richieste upstream già in corso terminano normalmente. Il flag enforced della risposta è false quando il progetto usa runtime nativo invece del gateway.

I consumer React usano useModelAccess(projectId) da @beeuni/sdk/react. La sua mutazione setEnabled(change) aggiorna il catalogo di gestione e il selettore delle sessioni.