SDK-Referenz

Die vollständige @beeuni/sdk-API-Oberfläche – Clientmethoden, Module, Turns und Distribution.

Diese Seite beschreibt die vollständige API-Oberfläche von @beeuni/sdk: alle Client-Methoden, die Framework-unabhängigen Module, die Turn-Hilfsfunktionen und die Auslieferung des Pakets. Nutze SDK für den Einstieg und Sitzungen für eine ausführliche Beschreibung des Sitzungslebenszyklus.

Der Client

createBeeuni(config) gibt einen Client zurück. Jede Methode ist ein typisierter Aufruf der Plattform-API. Die Handles project(id) und session(pid, sid) binden IDs, sodass du sie nie wiederholen musst.

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

Konten — beeuni.accounts

accounts.tokens erstellt kontobezogene API-Schlüssel (beeuni_pat_...). Siehe SDK-Authentifizierung für das vollständige Token-Modell.

accounts.audit ist das Rekonstruktionsprotokoll für Enterprise. Es kombiniert authentifizierte API-Anfragen mit semantischen Sitzungs-, Connector-, Genehmigungs- und Computerereignissen.

Jedes Ereignis enthält project_id, session_id, actor_type, source, outcome, request_id, trace_id und correlation_id, wenn die Aktion diese bereitstellt. Die API speichert keine Anfrageinhalte, Prompts, Geheimnisse, Zugangsdaten oder unverarbeiteten Connector-Argumente im zentralisierten Ereignis. Connector-Ereignisse können eine begrenzte Argumentvorschau enthalten, die Felder mit Zugangsdatenstruktur und opake Daten unkenntlich macht.

Zugriffszuweisungen

Beeuni hat einen einzigen Datensatztyp für Berechtigungsvergaben: eine Zuweisung. Sie bindet einen Prinzipal (user, group, service_account oder pending) an eine Rolle in einem Geltungsbereich (account oder einem project), optional auf ein Objekt eingeschränkt (agent, skill, secret, app oder trigger) und optional mit einem expires_at. Gruppenzugriff, ressourcenspezifischer Zugriff und Bindungen benutzerdefinierter Rollen sind allesamt Zuweisungen. Siehe Konten & Zugriff für das Modell.

Die kanonische REST-Oberfläche ist:

Das SDK stellt sie als listAssignments, createAssignment, revokeAssignment und listPermissions bereit. Eine Katalogzeile enthält action, scope_type, resource_type, delegable, description, area, level und implies — lies sie aus, statt Aktionsstrings fest zu codieren.

Das Zuweisen einer benutzerdefinierten Rolle erfordert die rbac-Berechtigung des Kontos; ohne sie antwortet die Route mit 402 und code: "entitlement_required".

Kontoeinladungen — beeuni.accountInvites

Allein über das Einladungstoken erreichbar — die eingeladene Person ist möglicherweise noch kein Mitglied.

Projekte — beeuni.projects

provision erstellt ein neues Projekt; es startet nicht die Sandbox eines bestehenden Projekts. Starte stattdessen eine Sitzung — siehe Sitzungen.

Sende idempotency_key, wenn eine Wiederholung möglich ist — ein Neuladen, ein zweiter Tab oder eine Zeitüberschreitung, nach der du es erneut versuchst. provision erstellt bei jedem Aufruf ein ganz neues verwaltetes Repo; ohne Schlüssel entstehen dadurch echte Projektduplikate. Verwende denselben Schlüssel für jeden Versuch eines einzigen logischen Erstellungsvorgangs. Wiederholungen geben dann das Projekt zurück, das der erste Versuch erstellt hat (201, identisches project_id, push_token: null). Der Schlüssel identifiziert den Versuch, nicht die Nutzdaten — wird er mit einem anderen name wiederverwendet, wird das erste Projekt zurückgegeben und der neue Wert ignoriert. Erstelle daher für jeden eigenständigen Erstellungsvorgang einen neuen Schlüssel. Ein zweites Projekt mit demselben Namen und ohne Schlüssel lässt sich weiterhin erstellen.

Eine Wiederholung, die eintrifft, während der erste Aufruf noch Ressourcen bereitstellt, erhält 409 mit code: 'provision_in_flight' statt eines project_id, das dieser Aufruf möglicherweise noch zurückrollt. Versuche es mit demselben Schlüssel erneut.

project(id).sessions.list({ scope: 'project' }) ist eine Lebenszyklus-Bestandsübersicht für einen Aufrufer mit Projektmanager-Berechtigungen. Sie ergänzt zugängliche nicht verfügbare, warme und soft-gelöschte Sitzungen mit Metadaten zu Eigentümerschaft und Laufzeitstatus. Beide Listengeltungsbereiche lassen alle Sitzungen aus, die der Aufrufer nicht öffnen kann.

sessions.list und sessions.listPage akzeptieren auch die Hierarchie- und Zuordnungsfilter. Ohne diese bleibt die Liste flach und unverändert.

Jede Sitzungszeile enthält parent_session_id und initiator ({ type: 'member' | 'trigger' | 'channel' | 'api' | 'system', id, label }). initiator gibt an, wer den gesamten Lauf gestartet hat; eine untergeordnete Sitzung übernimmt den Wert ihrer übergeordneten Sitzung. sessionParentId(session) liest parent_session_id, danach das ältere metadata.spawned_by_session. Ein Cursor ist nur für den Filtersatz gültig, mit dem er ausgegeben wurde.

GitHub — beeuni.github

Kontobezogene Installation der GitHub App und Repo-Verknüpfung, nicht projektbezogen.

Diese Liste enthält nur tatsächliche Kontoverbindungen. „Beeuni managed“ gehört nicht dazu — es ist das unten beschriebene Instanz-Backend.

Git-Backend der Instanz — beeuni.gitBackend

Ein für die gesamte Bereitstellung geltender Eigentümer samt Zugangsdaten, verwendet für von Beeuni verwaltete Repositories. Dies ist niemals eine Kontoverbindung und erscheint nie in beeuni.github.listInstallations.

Abrechnung — beeuni.billing

Liest Guthaben, Abonnement, Tarif und Transaktionsverlauf. Nutze Beeuni Checkout und die Abrechnungsverwaltung für Zahlungen und Guthabenkäufe.

sessionCosts.list() akzeptiert accountId, projectId, limit und offset. Jede Zeile kombiniert endgültige LLM-Kosten und abgerechnete Sandbox-Rechenkosten. sessionCosts.get() ergänzt die Modellnutzung und das nach LLM/Rechenleistung unterschiedene Buch. Die Liste enthält eine Abgleichsumme für Kosten ohne Sitzung.

Sandbox-Freigaben — beeuni.sandboxShares

Öffentliche Freigabelinks für einen zugänglich gemachten Sandbox-Port. Auf die Sandbox beschränkt, nicht auf das Projekt.

Marketplace-Katalog — beeuni.marketplace

Öffentliches Durchsuchen des Katalogs, schreibgeschützt — im Unterschied zu project(id).marketplace, das ein Element in einem Projekt installiert.

Benachrichtigungen — beeuni.notifications

Die Benachrichtigungen des Aufrufers über alle Konten und Projekte hinweg. Jede angemeldete Person hat einen Posteingang, einen Einstellungsdatensatz und Web-Push-Abonnements für ihre Browser. Jede Methode benötigt die Zugangsdaten einer Person: Ein Dienstkonto erhält 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 } } });

Arten (InboxNotificationKind, aufgeführt in INBOX_NOTIFICATION_KINDS):

DEFAULT_NOTIFICATION_PREFERENCES enthält diese Standardwerte. Die Posteingangszeile wird immer geschrieben; die Einstellungen bestimmen nur Push und E-Mail. Eine Zusammenfassungs-E-Mail listet die Zeilen auf, die 15 Minuten nach ihrem Eingang noch ungelesen sind, mit höchstens einer Zusammenfassung pro Stunde. Blenden Sie die E-Mail-Spalte aus, wenn email_available gleich false ist.

Das url jeder Zeile öffnet ihren Gegenstand. Sein Abfrageparameter ?notification=<id> ermöglicht es der Seite, die Zeile als gelesen zu markieren.

Das Sitzungs-Handle enthält den Beobachtungsstatus des Aufrufers für eine Sitzung:

Das Projekt-Handle — beeuni.project(id)

Bindet die Projekt-ID; jede Unterressource hängt davon ab.

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

p.tokens — projektgebundene API-Schlüssel

Werden beim Erstellen einer Sitzung automatisch als BEEUNI_TOKEN erzeugt; können auch manuell erzeugt werden.

p.setupLinks — von Agenten erzeugte Einrichtungslinks

Ein Link, den eine Person öffnet, um ein Secret einzugeben oder eine App zu verbinden, ohne vollständigen Projektzugriff.

p.apps — Apps (Releases, Maschinen, Volumes)

Über die Projektfunktion apps verfügbar. Anleitung: SDK → Apps.

p.secrets — Projekt-Secrets

runtime mit Consumer sandbox ist Umgebungs-Exposition — der Standard und die einzige Richtlinie, die einen Klartextwert in die Sitzung legt. egress mit Consumer network ist Egress-erzwungene Exposition: Die Sitzung enthält ein Handle, und Beeuni setzt den tatsächlichen Wert außerhalb der Sandbox ein, genau für die HTTPS- Hosts, die in der Richtlinie aufgeführt sind. Egress-erzwungene Exposition ist experimentell; sie benötigt das Feature-Flag secrets_egress (Settings → Feature flags). Bei deaktiviertem Flag geben setStrategy(identifier, 'egress', …) und upsert(...) mit einer Egress-Richtlinie 403 feature_disabled zurück. Jeder broker-Consumer ist in der Sitzung überhaupt nicht präsent. Siehe Secrets. Die Methode broker(...) erfordert ein sitzungsgebundenes Token und ein aktives Sitzungs-Handle.

p.access — Projektzuweisungen, Einladungen, Anfragen

Jede Methode hier liest oder schreibt eine auf dieses Projekt beschränkte Zuweisung. Die Projektrollen sind manager und member.

p.access.resourceGrants ist die Ansicht für Objektzuweisungen: Sie beschränkt einen Principal auf ein Objekt im Projekt statt auf das gesamte Projekt. Beeuni setzt Objektzuweisungen derzeit für Agenten und Skills durch. Ein Agent ist standardmäßig nicht zugänglich — ein Mitglied erhält nur Zugriff, wenn eine Zuweisung es oder eine seiner Gruppen nennt. Eine Objektzuweisung enthält keine eigenen Berechtigungen und schränkt einen Projektmanager genauso ein wie ein Mitglied.

p.connector(slug) — ein Konnektor

options: account, approvalContext, timeoutMs (Standard 90 000), signal. Mit der Datei aus beeuni connectors types sind Argumente und Ausgabe typisiert.

p.connectors — Tool-Konnektoren

p.connectors.discover durchsucht den Katalog direkter Konnektoren. Die Funktion ist experimentell und standardmäßig deaktiviert — aktivieren Sie sie pro Projekt unter Settings → Feature flags → “Connectors API Discover”. Easy Connect bleibt der Standard-Marktplatz für Konnektoren.

p.connectors.pipedream ist der Kompatibilitätsweg für älteres verwaltetes OAuth; listApps liefert nur OAuth-Apps zurück. Nutze Easy Connect für neue verwaltete Integrationen. Verbinde Apps mit API-Schlüssel direkt.

Ein Connector definiert das Tool, die Anbieter-App und die Richtlinien. connections speichert seine verbundenen Konten — ein Connector kann mehrere nebeneinander enthalten. Eine Sitzung kann mit connector_bindings: { alias: { connection_id } } eines für jeden Aufruf festlegen, oder ein einzelner Aufruf kann mit call(tool, args, { account }) eines angeben. Zugangsdaten bleiben verschlüsselt und werden pro Anfrage aufgelöst.

connections ist die einzige aktive Autorisierungsfassade. Die ausgemusterten Namen authorizations und profiles gehören nicht zur aktuellen SDK-Oberfläche.

Konten und die Zugriffsprüfung beim Aufruf

Jede Verbindung hat ein owner_type: project (geteilt — zugänglich für alle, denen der Connector freigegeben wurde, ob Person oder Dienstkonto) oder member (privat — nur für den eigenen Eigentümer zugänglich, und nur in einer privaten Sitzung; niemals für ein Dienstkonto). Ein geteiltes Konto kann auf Gruppen und Personen eingeschränkt werden: connections.list() liefert seine Freigaben in shared_with zurück, und connectionSharedWithEveryone(connection) gibt an, ob alle im Projekt es verwenden dürfen. Ein eingeschränktes Konto folgt für die benannten Personen den Regeln für private Konten, und usable: false kennzeichnet eines, das der Aufrufer nur zur Verwaltung sieht. Freigaben erteilen oder widerrufen mit createAssignment / revokeAssignment (object: { type: 'connection', id }) — siehe Festlegen, wer ein geteiltes Konto verwenden darf. p.connectors.accounts(slug) listet alle Konten auf, auf die dieser Aufrufer zugreifen darf, das Standardkonto zuerst:

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

Ein Aufruf ohne angegebenes Konto verwendet zuerst das eigene private Standardkonto des Aufrufers, dann das geteilte Standardkonto des Projekts. Ein angegebenes Konto, das nicht aufgelöst werden kann, wird mit connector_not_connected abgelehnt — niemals stillschweigend ersetzt — und die Ablehnung listet requested_account und available_accounts auf. Jeder erfolgreiche Aufruf gibt zurück, unter welchem Konto er ausgeführt wurde: result.account = { connection_id, label, owner_type }.

Es gibt keine Connector-Zugriffsprüfung beim Erstellen einer Sitzung mehr. Früher wurde eine Sitzung mit 409 CONNECTOR_CONNECTION_REQUIRED abgelehnt, wenn ein erforderlicher Connector keine nutzbare Verbindung hatte; diese Ablehnung entfällt (require_connectors ist wirkungslos — siehe p.sessions). Die Prüfung erfolgt jetzt beim Aufruf: Ein abgelehntes connector_not_connected enthält connect_url, einen gehosteten Autorisierungslink, sofern einer für den Aufrufer erzeugt werden kann — die gesamte Abhilfe besteht aus einem Klick über die Verbindungsschaltfläche im Transkript.

p.policies — Projektrichtlinien

p.triggers — Cron-, Webhook-, Monitor- und Ereignisautomatisierungen

Ein Trigger startet eine Agentenaktion nach Zeitplan, durch einen eingehenden Webhook, einen überwachten Befehl oder ein App-Ereignis an einem Connector. Siehe Trigger für Sitzungsstrategie und Payload- Vorlagen.

create(input) akzeptiert { 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 sind erforderlich. cron/run_at schließen sich gegenseitig aus (type: 'cron'); secret_env (das Webhook-HMAC-Geheimnis) gilt für type: 'webhook'.

Ein event-Trigger benötigt connector (einen Connector-Slug) und event (eine Typ-ID aus eventTypes). event_account ist optional: die Bezeichnung eines geteilten Kontos dieses Connectors; null oder das Weglassen verwendet das geteilte Standardkonto des Connectors. event_source ist optional: die ID des Ereignisquellen-Adapters, etwa composio. null oder das Weglassen verwendet den Anbieter des Connectors. Die Typ-ID gehört zu diesem Adapter. Die Struktur von event_config wird durch config_schema dieses Typs bestimmt. eventTypes und eventApps geben den Adapter als source an; provider ist ein veralteter Alias. Jeder aufgeführte Trigger enthält event: { connector, account, connected_as, type, config, source, provider, app, status: 'active' | 'needs_connection' | 'error' | 'pending', error, last_event_at } | null. Prompt-Vorlagen lesen das Ereignis als {{ event.data.<field> }} sowie event.id, event.type, event.app, event.connector und event.occurred_at.

session_access steuert, wer vom Trigger erstellte Sitzungen öffnen kann. Es ist { mode: 'private' | 'members' | 'project', memberIds: string[], groupIds: string[] } and defaults to private. Diese Richtlinie ist kontolokaler Laufzeit- zustand. Sie wird nicht in das portable beeuni.yaml-Manifest aufgenommen. Wird nur session_access aktualisiert, entsteht kein Git-Commit. Eine fest zugeordnete Sitzung behält ihre eigenen Freigabe- einstellungen. Ein Projektmanager kann vom Trigger erstellte Sitzungen immer öffnen, auch Sitzungen mit private oder Zugriff für ausgewählte Mitglieder.

session_access ist eine ressourcenspezifische Sichtbarkeitseinstellung zusätzlich zum Rollenmodell, keine Rolle. Sie bestimmt, wer die Sitzungen eines Triggers öffnen kann. Sie gewährt keine Berechtigung, die die Rollenentscheidung verweigert. Siehe Konten & Zugriff.

p.marketplace / p.registry — installierte Elemente

Installiert die Dateien eines Katalogelements im Standardbranch des Projekts. registry.* ist ein identischer Alias von marketplace.*.

p.files — Repo-Dateien (lesen)

Schreibgeschützter Zugriff auf den Git-Baum des Projekts. Zum Lesen und Schreiben von Dateien innerhalb einer laufenden Sitzung die Dateioperationen der Sitzung verwenden — siehe Dateien unter Module weiter unten.

p.git — Verlauf

p.changeRequests — Lebenszyklus und Merge

Über einen Change Request (CR) wird die Arbeit einer Sitzung in den Standardbranch zusammengeführt.

p.sessions — und das Sitzungs-Handle

Der Sitzungshandle ist das Herzstück der Laufzeitumgebung — siehe Sessions.

create(input) akzeptiert connector_bindings, die nach dem Connector-Connection-Slug indiziert sind. Jeder Wert bezeichnet eine connection_id. Außerdem wird secrets für die Einschränkung von Secrets aus dem Backend akzeptiert. require_connectors ist veraltet und inaktiv: Das Feld wird weiterhin akzeptiert (ein alter Client wird niemals abgelehnt, weil er es sendet), aber nichts liest es — eine Sitzung wird beim Erstellen niemals wegen eines Connectors ohne nutzbares Konto abgelehnt. Siehe Accounts und das Gate zur Aufrufzeit.

p.approvals — der Posteingang für Connector-Genehmigungen

Ausstehende, von Connectors abhängige Aktionen, die auf eine Entscheidung warten — dies bildet die UX für Genehmigungsberechtigungen ab (APPROVE / ASK / BLOCK).

p.gateway — LLM-Observability

Anforderungsprotokolle, Kosten-/Latenzaggregationen, Budgets und Gateway-API-Schlüssel für den Modellverkehr dieses Projekts.

Eine Routing-Richtlinie enthält ein Standardmodell, ein Vision-Modell und eine geordnete Fallback-Kette, wobei jedes Modell höchstens einmal versucht wird; fallbackOn ist transient oder any-error.

Das Gateway wechselt nur dann zum nächsten Fallback-Modell, wenn das aktuelle Modell fehlgeschlagen ist, bevor es eine Ausgabe zurückgegeben hat:

• transient: ein Netzwerkfehler, ein Timeout, beliebige 5xx oder 402, 403, 429.
• any-error: jeder Fehler, einschließlich eines 400.

Ein Fehler, nachdem die Ausgabe begonnen hat, bleibt bei diesem Modell. Eine Anforderung mit dem eigenen Provider-Schlüssel (BYOK) fällt niemals auf ein von Beeuni abgerechnetes Modell zurück. Jedes Fallback-Modell erhält eigene Generierungsstandards.

p.channels — Slack / E-Mail / Sprache

Connector-Oberflächen, über die ein Agent als Slack-App oder E-Mail-Adresse agieren oder einem Echtzeit-Sprachanruf beitreten kann.

p.modelDefaults — Standardmodelleinstellungen

Standardmodelle auf Konto-, Agent- und Projektebene, die vom Gateway aufgelöst werden.

p.setDefaultAgent — Standard-Agent des Projekts

p.setDefaultAgent(agentName) prüft, ob der Agent deklariert und aktiviert ist, und legt ihn dann als default_agent in beeuni.yaml des Projekts fest. Neue Sitzungen bevorzugen diesen Agenten, sofern ein Benutzer keinen anderen auswählt.

p.updateFeatureFlag — Feature-Flags

p.updateFeatureFlag(feature, enabled) schaltet ein Feature-Flag für das Projekt ein oder aus. Übergeben Sie enabled: null, um die Überschreibung zu löschen und auf den Plattformstandard zurückzufallen. Es ruft PATCH /v1/projects/:id/features auf.

feature ist eines von FEATURE_FLAG_KEYS (exportiert aus @beeuni/sdk, typisiert als FeatureFlagKey). Der Aufrufer benötigt die Berechtigung project.settings.write des Projekts; andernfalls antwortet die Route mit 403.

Jede Route, die von einem Flag abhängt, lehnt auf dieselbe Weise ab, solange das Flag deaktiviert ist: HTTP 403 mit { error, code: "feature_disabled", feature }. Verwenden Sie isFeatureDisabledError(error), um darauf zu verzweigen, und featureDisabledKey(error), um den Flag-Schlüssel zu lesen — gleichen Sie niemals den Nachrichtentext ab.

p.updateExperimentalFeature(feature, enabled) ist der veraltete Alias. Er ruft weiterhin den veralteten Routenalias PATCH /v1/projects/:id/experimental auf, damit Verbraucher, die an eine ältere bereitgestellte API gebunden sind, weiter funktionieren. Verwenden Sie in neuem Code p.updateFeatureFlag.

p.sandbox — Vorlagen und Snapshot-Builds

Sandbox-Build-Konfiguration über sandboxHealth/sandboxTemplates am Projekthandle hinaus: Dockerfile-/Image-/Warm-Pool-Vorlagen und deren Snapshot-Builds.

Plattform-Admin-Hooks (@beeuni/sdk/react)

Diese Hooks bedienen die Admin-Konsole. Die API antwortet nur für einen Plattformadministrator darauf. Jede Mutation invalidiert die Abfragen ['admin', 'accounts'].

Ausweichmöglichkeit

beeuni.runtime() gibt den typisierten runtime-REST-Client für die aktive Sandbox zurück. Bei einem von createScopedBeeuni (@beeuni/sdk/server) erstellten Client wirft es einen Fehler — die prozessglobale „aktive“ Laufzeitumgebung ist auf einem mandantenfähigen Server die Sandbox der Anfrage eines anderen Mandanten, also ein mandantenübergreifendes Datenleck. Verwenden Sie stattdessen die sitzungsbezogene beeuni.session(pid, sid).runtime (rufen Sie zuerst ensureReady() auf), die die eigene Sandbox dieser Sitzung auflöst.

Module

Die frameworkfreien Module hinter der Client--Fassade und den React-Hooks. Verwenden Sie sie, wenn Sie eine einzelne Operation ohne die Fassade, einen reinen Helfer oder eine reine Node-Isolationsschicht benötigen. Jedes Modul verfügt über eine Stabilitätsstufe, damit Sie wissen, worauf Sie aufbauen können.

Der Root-Einstiegspunkt ist kanonisch. Jeder frameworkfreie Name unten kann direkt aus @beeuni/sdk importiert werden:

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

Kanonische Module

Files

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

Uploads mit mehr als 64 KiB überqueren die Sandbox-Grenze in verifizierten Blöcken. Der Fortschritts-Callback wird ausgeführt, nachdem jeder Block das Sitzungsdateisystem erreicht hat.

uploadNativeFile({ uri, name, type? }, targetPath, baseUrl) lädt eine Gerätedatei aus React Native in einer einzigen Anfrage hoch. Die Laufzeit streamt die Bytes aus uri, sodass sie nie in den JS-Heap gelangen. Dabei werden dieselbe Authentifizierung, Deadline und 401-Wiederholung wie bei files.upload verwendet. Es wird nicht in Blöcke aufgeteilt.

fetchProjectArchive, fetchCostExportCsv und die Sandbox-Versionsaufrufe werden über denselben Transport gesendet. Ein Fehler löst ein ApiError mit status aus.

files.write(path, blob) ersetzt die Datei unter path und schlägt fehl, wenn path ein Ordner ist. files.create(path) erstellt eine leere Datei und überschreibt niemals: Wenn unter path bereits eine Datei oder ein Ordner existiert, wird FileExistsError (status 409, code 'FILE_EXISTS') ausgelöst.

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 zielt auf die global aktive Sandbox. Wenn dein Host mehr als eine Sitzung gleichzeitig ausführt, rufe stattdessen s.files für das Sitzungshandle auf. Dadurch wird immer die eigene Sandbox dieser Sitzung angesprochen. Siehe Sessions.

Hilfsfunktionen der Sitzungs-Laufzeit

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

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

getSessionHealth löst bei einem Nicht-2xx-Status niemals einen Fehler aus. Es gibt { status, ok, health, body } zurück und überlässt dir die Entscheidung, was ein Status bedeutet. Dasselbe Modul exportiert die URL-Hilfsfunktionen, die die localhost-Ausgabe eines Agenten in eine erreichbare Proxy-URL umschreiben: detectLocalhostUrls, rewriteLocalhostUrl, proxyLocalhostUrl, parseLocalhostUrl und buildWebProxyUrl.

runtime-Client

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

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

getClient() gibt den typisierten Runtime-Kompatibilitätsclient für die aktive Sandbox zurück, wobei die Authentifizierung bereits eingefügt ist. Bevorzuge beeuni.session(pid, sid).runtime, denselben auf eine Sitzung beschränkten Client, gegenüber dem globalen getClient(), wenn dein Host mehr als eine Sitzung ausführt.

Auth-Hilfsfunktionen

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

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

Das Token stammt aus der getToken-Funktion, die du an createBeeuni übergeben hast. Der meiste Anwendungscode benötigt dieses Modul nicht — die Datei-, Sitzungs- und Fassadenschichten authentifizieren dich bereits.

API-Client

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

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

backendApi ist der typisierte HTTP-Client, auf dem jede REST-Funktion aufbaut. Verwende ihn nur für einen Endpunkt, für den es noch keinen typisierten Wrapper gibt.

Composer-Listen für Agenten und Modelle

Erstelle die Agenten- und Modellauswahl eines Session-Composers nach denselben Regeln wie die Beeuni-Web-App. Jede Funktion ist rein: Rufe die Eingaben mit dem Client ab und übergib sie anschließend.

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 gibt explicit: undefined zurück, wenn der Composer seine Standardeinstellung verwendet. model ist der anzuzeigende und zu sendende Schlüssel. Der id jedes abgeflachten Modells ist die Referenz, die eine Auswahl speichert; modelRefToKey(ref, gatewayEnabled) liest eine gespeicherte Referenz (eine Sitzungsfixierung, eine Kanalbindung, das model eines Triggers) wieder in einen Schlüssel ein.

Unterstützte Unterpfade

Wire-Nachrichten-IDs

Das messageId eines Prompts ist seine Position im Transkript. runtime ordnet Nachrichten nach msg_ + einer 48-Bit-Uhr (Date.now() * 0x1000, niedrige 48 Bits) + 14 Base62-Zeichen, und die Uhr läuft alle 2^36 ms (etwa 2,2 Jahre) über. Niemals von Hand codieren.

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

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

Der Mint-Zeitpunkt liegt zwei Minuten zurück und wird dann um einen Tick über die neueste ID in after angehoben, die höchstens eine Stunde vorausliegt. Ein Aufrufer, der die neueste Position als Uhr statt als IDs speichert, verwendet mintWireMessageIdAbove({ nowMs, newestKnownTime }), which returns { id, time }. newestWireIdClock(ids), um diese Uhr zu ermitteln. Jeder Vergleich erfolgt auf dem Ring, sodass IDs auf beiden Seiten eines Überlaufs ihre tatsächliche Reihenfolge behalten.

Die 48-Bit-Uhr läuft etwa alle 2,2 Jahre über. Vergleiche daher niemals zwei Uhren mit > oder <=: Eine direkt nach einem Überlauf erzeugte ID ist numerisch kleiner als eine direkt davor erzeugte. Verwende wireIdClockDelta(clock, reference), den vorzeichenbehafteten Abstand auf dem Ring (positiv, wenn clock vorausliegt), und maxWireIdClock(clocks) für die neueste von mehreren IDs:

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

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

Serverseitige Isolation

createBeeuni speichert seine Konfiguration, einschließlich der Token-Funktion, in einer einzigen prozessweiten Variable. Das ist für einen Browser-Tab, eine CLI oder einen Single-Tenant-Server unproblematisch. Für einen Node-Server, der gleichzeitige Anfragen verschiedener Benutzer verarbeitet, ist es unsicher, da der letzte Aufruf von createBeeuni für jede laufende Anfrage gilt. @beeuni/sdk/server behebt dies durch Isolation pro Anfrage:

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

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

createScopedBeeuni und runWithBeeuni isolieren die Konfiguration pro Anfrage mit Nodes AsyncLocalStorage. Importiere @beeuni/sdk/server niemals aus einem Browser-Bundle — dadurch wird statisch node:async_hooks eingebunden.

Das oberste runtime() eines eingeschränkten Clients löst einen Fehler aus (andernfalls würde die Sandbox eines anderen Tenants aufgelöst). Greife nach await s.ensureReady() über beeuni.session(pid, sid).runtime auf die Laufzeit einer bestimmten Sitzung zu.

Veraltete Aliase

Etwa zwanzig alte Unterpfade funktionieren weiterhin: /files, /turns, /session, /auth, /projects-client, /api-client, /config, /event-stream, /opencode-client, /platform-client und weitere. Jeder exportiert den Code des bereits vorhandenen Root-Einstiegspunkts @beeuni/sdk erneut. Sie bleiben funktionsfähig, damit kein bestehender import breaks, but new code should import from the root.

Interne Module

@beeuni/sdk/internal/* enthält die Zustand-Stores, die die interne Laufzeit von apps/web verwendet — Sitzungs-Synchronisierungsstatus, Verfolgung der aktiven Laufzeit und Verwaltung der Wiederverbindung. Dieser Unterpfad liegt ausdrücklich außerhalb von Semver. Nicht in Host-Code importieren; die React hooks stellen den benötigten Status bereits bereit.

Turns

Einfache Funktionen, die Sitzungsnachrichten in Turns gruppieren und jeden Nachrichtenteil klassifizieren. Verwende sie, um einen benutzerdefinierten Chat-Renderer anstelle des Referenz-Renderers in apps/web zu erstellen. Kein React, kein DOM — jeder Export ist eine einfache Funktion oder ein Typ und kann sicher von jedem Host aus aufgerufen werden.

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

Importiere jede Funktion aus dem Root-Einstiegspunkt @beeuni/sdk. Der Unterpfad @beeuni/sdk/turns funktioniert weiterhin, ist aber ein veralteter Alias. Neuer Code muss den Root-Einstiegspunkt verwenden — siehe Distribution.

Einen Teil klassifizieren

classifyPart(part) normalisiert einen der 12 Teiltypen des Beeuni- Transkriptformats (beeuni.transcript.v1, BEEUNI_TRANSCRIPT_SCHEMA) zu einem ClassifiedPart — einem Union-Typ mit kind als Schlüssel. Jede Variante löst bereits die Felder auf, die ein Renderer benötigt: Tool-Status, geparste JSON-Ausgabe, Bilderkennung.

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

Ein unbekannter übertragener Teil wird zur Laufzeit zu unknown, statt eine Exception auszulösen. So kann ein älterer Client mit einem neueren Server kommunizieren.

Ein Tool-Teil wird als ToolView klassifiziert:

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) erstellt einen solchen direkt aus einem Tool-Teil. Lesen Sie diese Felder statt des harness-eigenen state.metadata: Dieselbe Karte stellt dann sowohl ein runtime-edit (filePath, filediff) als auch ein pi-edit (path, edits, ein einheitliches patch) dar.

Einige Tools (web_search, image_search, Connector-Aufrufe) melden state.status: 'completed', selbst wenn ihr JSON-Body success: false enthält. classifyPart erkennt dies und setzt ToolView.status auch in diesem Fall auf 'error'.

classifyTurn(message) klassifiziert jeden Teil einer Assistentennachricht und gibt ein ClassifiedTurn mit drei Feldern zurück:

• parts — jeder Teil, klassifiziert
• error — aus message.info.error, falls vorhanden
• isEmpty — true, wenn der Turn keinen Fehler und keinen Teil mit sichtbarem Inhalt enthält

Tool-Metadaten

toolKind(name) ist die zentrale Tool-Taxonomie: Sie ordnet den Tool-Namen jedes Harness (write von pi, oc-apply_patch von runtime, pty_spawn eines Plugins) einem ToolKind zu — read, edit, write, bash, web_search, task, question, … oder other. Narrationsfamilien, View-Modelle, toolInfo- Kategorien und die Kontext-Tool-Gruppe leiten sich alle daraus ab. inputPath(input) liest den Pfad eines Datei-Tools aus filePath, file_path oder path.

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

Zwei weitere Lookup-Funktionen beschreiben jeweils ein Tool. Verwechseln Sie sie nicht.

• toolInfo(name) — ohne Symbole, gibt { label, category } zurück. classifyPart verwendet dies intern. ToolCategory ist 'shell' | 'files' | 'search' | 'edit' | 'web' | 'task' | 'other'.
• getToolInfo(name, input) — mit Symbolen, gibt { icon, title, subtitle } für die Referenz-UI der Tool-Karten zurück. Der Untertitel stammt aus der Tool-Eingabe, zum Beispiel einem Dateipfad oder einer Suchanfrage.

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

Beide Funktionen gleichen Präfixe von Tool-Namen ab, sodass Beeunis Plugin-Tool-Familien (agent_*, session_*, task_*, trigger_*, project_*, pty_*) ohne Registry-Update aufgelöst werden. Ein unbekannter Tool-Name löst nie eine Exception aus — er fällt auf humanizeToolName(name) mit der Kategorie 'other' zurück.

Tool-View-Modelle

toolViewModel(classifiedTool) bildet einen klassifizierten Tool-Teil auf eine Struktur ab, die für eine Tool-Familie ausgelegt ist. Eine UI kann ihn dann speziell darstellen, statt als generischen JSON-Block.

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

DiffLine ist { type: 'added' | 'removed' | 'unchanged', text }. String- Felder sind begrenzt, damit eine große Tool-Ausgabe nie die Darstellung beeinträchtigt: 4000 Zeichen für formatiertes JSON, 256 KB vor der Ausführung eines Diffs.

Nachrichten zu Turns gruppieren

Ein Turn verbindet eine Benutzernachricht mit den Assistentennachrichten, die sie beantwortet haben. Er ist die Einheit, die eine Chat-UI als einen Austausch darstellt.

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

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

groupMessagesIntoTurns verknüpft jede Assistentennachricht mit ihrer übergeordneten Benutzernachricht. Fehlt diese Verknüpfung, greift die Funktion auf die Nachrichtenreihenfolge zurück. Sie ordnet auch eine verwaiste Assistentennachricht — eine ohne übergeordnete Nachricht, die vor allen Benutzernachrichten steht — dem ersten Turn zu, nicht dem letzten.

Verwandte Hilfsfunktionen:

• findLastTextPart(parts) — der abschließende Antworttext des Turns
• turnHasSteps(parts) — true, wenn ein tool-, compaction-, snapshot- oder patch-Teil vorhanden ist
• isShellMode(turn) / getShellModePart(turn) — ein Turn, der aus einem synthetischen Prompt besteht, der einen bash-Aufruf steuert

Type Guards

Grenzen Sie den Typ eines Teils anhand von type ein:

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

Ebenfalls verfügbar: isReasoningPart, isFilePart, isAgentPart, isCompactionPart, isSnapshotPart, isPatchPart, isStepPart (step-start und step-finish).

Status und Fehler

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

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

getTurnStatus durchsucht die Teile eines Turns nach der letzten Statuszeile. Wenn der letzte Teil eine laufende task-Delegation ist, übergeben Sie childMessages, damit der Status die tatsächliche Aktivität des Subagenten statt einer generischen Zeile „Wird delegiert …“ anzeigt.

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

Kosten- und Token-Summen

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"

Beide Funktionen lesen Kosten- und Token-Summen aus step-finish-Teilen. Wenn ein Teil null meldet, schätzen sie die Kosten anhand der Token-Anzahl mithilfe eines ModelPricingLookup.

Nachrichten aus ChatGPT/Codex-Abonnements tragen $0.00 bei, einschließlich älterer Nachrichten mit Laufzeitkosten ungleich null. Token- und Kontextnutzung bleiben sichtbar. Gemischte Sitzungen behalten die Gebühren für kostenpflichtige API-Nachrichten bei. OpenAI-API-Modelle bleiben kostenpflichtig, einschließlich API-Modellen, deren Namen codex enthalten.

Untergeordnete Sitzungen und ausstehende Anfragen

Der Konversationsbaum einer Projektsitzung (die Wurzel und die von ihr gestarteten Subagenten-Konversationen) stammt aus ihrer runtime_sessions-Liste. Diese Hilfsfunktionen lesen ihn und bevorzugen dabei die aktuellen Namen gegenüber denen vor 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

Ein task-Tool-Aufruf delegiert an eine untergeordnete Sitzung. Diese Hilfsfunktionen verbinden einen übergeordneten Turn mit den Nachrichten dieser untergeordneten Sitzung.

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

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

Ordnen Sie eine ausstehende Berechtigungs- oder Frageanfrage ihrem Tool-Aufruf zu und ermitteln Sie, welche Tool-Teile ausgeblendet werden sollen, solange eine solche Anfrage aktiv ist:

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

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

Formatierung und Listen

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"

Hilfsfunktionen für Sitzungslisten arbeiten mit denselben Sitzungsdaten:

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

Wiederholungsstatus: getRetryInfo(sessionStatus) gibt { attempt, message, next, details? } when status.type === 'retry', with message zurück, begrenzt auf 60 Zeichen. details bewahrt eine strukturierte LLM-Gateway-Hülle, sofern vorhanden: den endgültigen Anbieter, Gateway-Code, die Anfrage-ID, den Vorschlag, den Upstream-Status und die geordneten Kandidatenfehler. Jeder Kandidatenfehler enthält attempt, provider, routeModel, resolvedModel, stage, optional status, code und message. Ältere Wiederholungen im Klartextformat geben details: undefined zurück. getRetryMessage(sessionStatus) gibt die vollständige Nachricht ohne Hülle zurück. Wenn runtime nur diese Nachricht beibehält, enthält die zusammengesetzte Gateway-Nachricht weiterhin die Anfrage-ID sowie für jeden Kandidaten den Anbieter, das aufgelöste Modell, den HTTP-Status, den Code und die längenbegrenzte Nachricht.

Strukturtypen

Die Gruppierungs- und Statusfunktionen akzeptieren minimale strukturelle Typen — PartLike, MessageInfoLike, TurnLike, ToolStateLike, SessionStatusLike — statt der konkreten Transkripttypen. Ihre eigenen Nachrichten- und Part-Strukturen werden unverändert durchgereicht, solange sie den erforderlichen Feldern entsprechen. classifyPart und classifyTurn sind die Ausnahme. Sie verwenden die Beeuni-Union Part (beeuni.transcript.v1) als Typ, sodass ihre Vollständigkeitsprüfung einen neuen Part-Typ zur Build-Zeit erkennt.

Distribution

npm install @beeuni/sdk

Das Paket wird als kompiliertes ESM mit vollständigen TypeScript-Typdeklarationen ausgeliefert. react und @tanstack/react-query sind optionale Peer-Abhängigkeiten. Wenn Sie @beeuni/sdk/react verwenden, installieren Sie beide.

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

Einstiegspunkte und Stabilität

Der Haupteinstiegspunkt @beeuni/sdk ist kanonisch. Er exportiert die gesamte frameworkunabhängige API und läuft in Browsern, Node 18+, Bun und Edge- Laufzeitumgebungen.

CDN-Bundles

Das Paket enthält außerdem zwei Browser-Bundles, die mit tsup erstellt werden: ein ESM-Bundle (dist/beeuni.esm.min.js) und ein globales IIFE-Bundle (dist/beeuni.global.js), das window.Beeuni definiert.

<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 stellt denselben Haupteinstiegspunkt bereit wie der npm-Import: Beeuni.createBeeuni, Beeuni.classifyTurn, Beeuni.ApiError.

Siehe auch

• SDK — Installation und Ihre erste Sitzung.
• Sitzungen — Lebenszyklus, Streaming und Fehlerbehandlung.
• React-Hooks — die auf diesen Modulen aufbauende reaktive Schicht.

Repository-Zugriff für Agenten

Die Agentenkonfiguration akzeptiert repository_access?: boolean (Standard: true). Setzen Sie false, um neue Sitzungen ohne das Projekt-Repository oder Zugriff auf die Repository-API auszuführen. Berechtigungen für Git, Secrets, Konnektoren und Tools bleiben getrennt. Bestehende Sitzungen behalten ihre gespeicherte Richtlinie. AgentConfigBlock.workspace ist veraltet. Das SDK ordnet die älteren Werte branch/runtime dem booleschen Feld zu. Ein Schreibzugriff über das ältere read erfordert eine explizite Auswahl von repository_access; er aktiviert keinen schreibgeschützten Repository-Zugriff.

Anbieter- und Modellzugriff

Lesen Sie beeuni.projects.modelAccess(projectId). Ändern Sie ein einzelnes Ziel mit beeuni.projects.setModelAccess(projectId, { target: 'provider' | 'model', id, enabled }).

Verwenden Sie die Anbieter-ID beeuni für Beeuni Managed Models oder eine Anbieter-ID aus dem Katalog für BYOK, Codex und benutzerdefinierte Anbieter. Verwenden Sie für ein Modell die vollständige Gateway-Wire-ID. Das Deaktivieren eines Anbieters umfasst auch zukünftige Modelle und bewahrt individuelle Modelleinstellungen und gespeicherte Zugangsdaten.

Das aktuelle Standardmodell und sein Anbieter benötigen vor der Deaktivierung einen Ersatz (409 cannot_disable_default). Direkte Gateway-Anfragen an deaktivierte Ziele schlagen mit model_disabled oder provider_disabled fehl. Bereits laufende Upstream-Anfragen werden normal abgeschlossen. Das Flag enforced der Antwort ist false, wenn das Projekt natives runtime statt des Gateways verwendet.

React-Nutzer verwenden useModelAccess(projectId) aus @beeuni/sdk/react. Die Mutation setEnabled(change) aktualisiert den Verwaltungskatalog und die Sitzungsauswahl.