@beeuni/sdk 0.1.0

package/dist/core/runtime/runtime-types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/runtime/transcript-types.d.ts

@@ -0,0 +1,507 @@
+export declare const BEEUNI_TRANSCRIPT_SCHEMA: "beeuni.transcript.v1";
+export declare const TURN_ERROR_CODES: readonly ["auth", "rate_limit", "credits", "context_length", "output_length", "aborted", "unknown"];
+export type TurnErrorCode = (typeof TURN_ERROR_CODES)[number];
+export declare function isTurnErrorCode(value: unknown): value is TurnErrorCode;
+export type BeeuniProviderAuthError = {
+    code?: TurnErrorCode;
+    name: 'ProviderAuthError';
+    data: {
+        providerID: string;
+        message: string;
+    };
+};
+export type BeeuniUnknownError = {
+    code?: TurnErrorCode;
+    name: 'UnknownError';
+    data: {
+        message: string;
+        ref?: string;
+        statusCode?: number;
+    };
+};
+export type BeeuniOutputLengthError = {
+    code?: TurnErrorCode;
+    name: 'MessageOutputLengthError';
+    data: {
+        [key: string]: unknown;
+    };
+};
+export type BeeuniAbortedError = {
+    code?: TurnErrorCode;
+    name: 'MessageAbortedError';
+    data: {
+        message: string;
+    };
+};
+export type BeeuniStructuredOutputError = {
+    code?: TurnErrorCode;
+    name: 'StructuredOutputError';
+    data: {
+        message: string;
+        retries: number;
+    };
+};
+export type BeeuniContextOverflowError = {
+    code?: TurnErrorCode;
+    name: 'ContextOverflowError';
+    data: {
+        message: string;
+        responseBody?: string;
+    };
+};
+export type BeeuniContentFilterError = {
+    code?: TurnErrorCode;
+    name: 'ContentFilterError';
+    data: {
+        message: string;
+    };
+};
+export type BeeuniApiError = {
+    code?: TurnErrorCode;
+    name: 'APIError';
+    data: {
+        message: string;
+        statusCode?: number;
+        isRetryable: boolean;
+        responseHeaders?: {
+            [key: string]: string;
+        };
+        responseBody?: string;
+        metadata?: {
+            [key: string]: string;
+        };
+    };
+};
+export type BeeuniMessageError = BeeuniProviderAuthError | BeeuniUnknownError | BeeuniOutputLengthError | BeeuniAbortedError | BeeuniStructuredOutputError | BeeuniContextOverflowError | BeeuniContentFilterError | BeeuniApiError;
+export type BeeuniFileDiff = {
+    file?: string;
+    patch?: string;
+    additions: number;
+    deletions: number;
+    status?: 'added' | 'deleted' | 'modified';
+};
+export type BeeuniTokenUsage = {
+    total?: number;
+    input: number;
+    output: number;
+    reasoning: number;
+    cache: {
+        read: number;
+        write: number;
+    };
+};
+export type BeeuniUserMessageInfo = {
+    id: string;
+    sessionID: string;
+    role: 'user';
+    time: {
+        created: number;
+    };
+    format?: unknown;
+    summary?: {
+        title?: string;
+        body?: string;
+        diffs: BeeuniFileDiff[];
+    };
+    agent: string;
+    model: {
+        providerID: string;
+        modelID: string;
+        variant?: string;
+    };
+    system?: string;
+    tools?: {
+        [key: string]: boolean;
+    };
+};
+export type BeeuniAssistantMessageInfo = {
+    id: string;
+    sessionID: string;
+    role: 'assistant';
+    time: {
+        created: number;
+        completed?: number;
+    };
+    error?: BeeuniMessageError;
+    parentID?: string;
+    modelID: string;
+    providerID: string;
+    mode: string;
+    agent: string;
+    path: {
+        cwd: string;
+        root: string;
+    };
+    summary?: boolean;
+    cost: number;
+    tokens: BeeuniTokenUsage;
+    structured?: unknown;
+    variant?: string;
+    finish?: string;
+};
+export type BeeuniMessageInfo = BeeuniUserMessageInfo | BeeuniAssistantMessageInfo;
+export type BeeuniMessage = {
+    info: BeeuniMessageInfo;
+    parts: BeeuniPart[];
+};
+export type BeeuniTextPart = {
+    id: string;
+    sessionID: string;
+    messageID: string;
+    type: 'text';
+    text: string;
+    synthetic?: boolean;
+    ignored?: boolean;
+    time?: {
+        start: number;
+        end?: number;
+    };
+    metadata?: {
+        [key: string]: unknown;
+    };
+};
+export type BeeuniReasoningPart = {
+    id: string;
+    sessionID: string;
+    messageID: string;
+    type: 'reasoning';
+    text: string;
+    metadata?: {
+        [key: string]: unknown;
+    };
+    time: {
+        start: number;
+        end?: number;
+    };
+};
+export type BeeuniFilePartSourceText = {
+    value: string;
+    start: number;
+    end: number;
+};
+export type BeeuniFilePartSource = {
+    type: 'file';
+    path: string;
+    text: BeeuniFilePartSourceText;
+} | {
+    type: 'symbol';
+    path: string;
+    text: BeeuniFilePartSourceText;
+    range: {
+        start: {
+            line: number;
+            character: number;
+        };
+        end: {
+            line: number;
+            character: number;
+        };
+    };
+    name: string;
+    kind: number;
+} | {
+    type: 'resource';
+    clientName: string;
+    uri: string;
+    text: BeeuniFilePartSourceText;
+};
+export type BeeuniFilePart = {
+    id: string;
+    sessionID: string;
+    messageID: string;
+    type: 'file';
+    mime: string;
+    filename?: string;
+    url: string;
+    source?: BeeuniFilePartSource;
+};
+export type BeeuniToolStatePending = {
+    status: 'pending';
+    input: {
+        [key: string]: unknown;
+    };
+    raw: string;
+};
+export type BeeuniToolStateRunning = {
+    status: 'running';
+    input: {
+        [key: string]: unknown;
+    };
+    title?: string;
+    metadata?: {
+        [key: string]: unknown;
+    };
+    time: {
+        start: number;
+    };
+};
+export type BeeuniToolStateCompleted = {
+    status: 'completed';
+    input: {
+        [key: string]: unknown;
+    };
+    output: string;
+    title: string;
+    metadata: {
+        [key: string]: unknown;
+    };
+    time: {
+        start: number;
+        end: number;
+        compacted?: number;
+    };
+    attachments?: BeeuniFilePart[];
+};
+export type BeeuniToolStateError = {
+    status: 'error';
+    input: {
+        [key: string]: unknown;
+    };
+    error: string;
+    metadata?: {
+        [key: string]: unknown;
+    };
+    time: {
+        start: number;
+        end: number;
+    };
+};
+export type BeeuniToolState = BeeuniToolStatePending | BeeuniToolStateRunning | BeeuniToolStateCompleted | BeeuniToolStateError;
+export type BeeuniToolPart = {
+    id: string;
+    sessionID: string;
+    messageID: string;
+    type: 'tool';
+    callID: string;
+    tool: string;
+    state: BeeuniToolState;
+    metadata?: {
+        [key: string]: unknown;
+    };
+};
+export type BeeuniStepStartPart = {
+    id: string;
+    sessionID: string;
+    messageID: string;
+    type: 'step-start';
+    snapshot?: string;
+};
+export type BeeuniStepFinishPart = {
+    id: string;
+    sessionID: string;
+    messageID: string;
+    type: 'step-finish';
+    reason: string;
+    snapshot?: string;
+    cost: number;
+    tokens: BeeuniTokenUsage;
+};
+export type BeeuniSnapshotPart = {
+    id: string;
+    sessionID: string;
+    messageID: string;
+    type: 'snapshot';
+    snapshot: string;
+};
+export type BeeuniPatchPart = {
+    id: string;
+    sessionID: string;
+    messageID: string;
+    type: 'patch';
+    hash: string;
+    files: string[];
+};
+export type BeeuniAgentPart = {
+    id: string;
+    sessionID: string;
+    messageID: string;
+    type: 'agent';
+    name: string;
+    source?: {
+        value: string;
+        start: number;
+        end: number;
+    };
+};
+export type BeeuniRetryPart = {
+    id: string;
+    sessionID: string;
+    messageID: string;
+    type: 'retry';
+    attempt: number;
+    error: BeeuniApiError;
+    time: {
+        created: number;
+    };
+};
+export type BeeuniCompactionPart = {
+    id: string;
+    sessionID: string;
+    messageID: string;
+    type: 'compaction';
+    auto: boolean;
+    overflow?: boolean;
+    tail_start_id?: string;
+};
+export type BeeuniSubtaskPart = {
+    id: string;
+    sessionID: string;
+    messageID: string;
+    type: 'subtask';
+    prompt: string;
+    description: string;
+    agent: string;
+    model?: {
+        providerID: string;
+        modelID: string;
+    };
+    command?: string;
+};
+export type BeeuniPart = BeeuniTextPart | BeeuniSubtaskPart | BeeuniReasoningPart | BeeuniFilePart | BeeuniToolPart | BeeuniStepStartPart | BeeuniStepFinishPart | BeeuniSnapshotPart | BeeuniPatchPart | BeeuniAgentPart | BeeuniRetryPart | BeeuniCompactionPart;
+export type BeeuniPartType = BeeuniPart['type'];
+export type RuntimeToolRef = {
+    messageID: string;
+    callID: string;
+};
+export type RuntimeQuestionOption = {
+    label: string;
+    description: string;
+};
+export type RuntimeQuestion = {
+    question: string;
+    header: string;
+    options: RuntimeQuestionOption[];
+    multiple?: boolean;
+    custom?: boolean;
+};
+export type RuntimeQuestionRequest = {
+    id: string;
+    sessionID: string;
+    questions: RuntimeQuestion[];
+    tool?: RuntimeToolRef;
+};
+export type RuntimeQuestionAnswer = string[];
+export type RuntimePermissionRequest = {
+    id: string;
+    sessionID: string;
+    permission: string;
+    patterns: string[];
+    metadata: {
+        [key: string]: unknown;
+    };
+    always: string[];
+    tool?: RuntimeToolRef;
+};
+export declare const RUNTIME_PERMISSION_REPLIES: readonly ["once", "always", "reject"];
+export type RuntimePermissionReply = (typeof RUNTIME_PERMISSION_REPLIES)[number];
+export declare const RUNTIME_PERMISSION_CAPABILITIES: readonly ["read", "edit", "glob", "grep", "list", "bash", "task", "external_directory", "todowrite", "question", "webfetch", "websearch", "lsp", "doom_loop", "skill"];
+export type RuntimePermissionCapability = (typeof RUNTIME_PERMISSION_CAPABILITIES)[number];
+export type BeeuniSessionStatus = {
+    type: 'idle';
+} | {
+    type: 'retry';
+    attempt: number;
+    message: string;
+    action?: {
+        reason: string;
+        provider: string;
+        title: string;
+        message: string;
+        label: string;
+        link?: string;
+    };
+    next: number;
+} | {
+    type: 'busy';
+};
+export type BeeuniTodo = {
+    content: string;
+    status: string;
+    priority: string;
+};
+export type BeeuniSessionEvent = {
+    type: 'message.updated';
+    properties: {
+        sessionID: string;
+        info: BeeuniMessageInfo;
+    };
+} | {
+    type: 'message.removed';
+    properties: {
+        sessionID: string;
+        messageID: string;
+    };
+} | {
+    type: 'message.part.updated';
+    properties: {
+        sessionID: string;
+        part: BeeuniPart;
+        time: number;
+    };
+} | {
+    type: 'message.part.removed';
+    properties: {
+        sessionID: string;
+        messageID: string;
+        partID: string;
+    };
+} | {
+    type: 'message.part.delta';
+    properties: {
+        sessionID: string;
+        messageID: string;
+        partID: string;
+        field: string;
+        delta: string;
+    };
+} | {
+    type: 'session.status';
+    properties: {
+        sessionID: string;
+        status: BeeuniSessionStatus;
+    };
+} | {
+    type: 'session.idle';
+    properties: {
+        sessionID: string;
+    };
+} | {
+    type: 'session.error';
+    properties: {
+        sessionID?: string;
+        error?: BeeuniMessageError;
+    };
+} | {
+    type: 'permission.asked';
+    properties: RuntimePermissionRequest;
+} | {
+    type: 'permission.replied';
+    properties: {
+        sessionID: string;
+        requestID: string;
+        reply: RuntimePermissionReply;
+    };
+} | {
+    type: 'question.asked';
+    properties: RuntimeQuestionRequest;
+} | {
+    type: 'question.replied';
+    properties: {
+        sessionID: string;
+        requestID: string;
+        answers: RuntimeQuestionAnswer[];
+    };
+} | {
+    type: 'question.rejected';
+    properties: {
+        sessionID: string;
+        requestID: string;
+    };
+} | {
+    type: 'todo.updated';
+    properties: {
+        sessionID: string;
+        todos: BeeuniTodo[];
+    };
+};
+export type BeeuniSessionEventType = BeeuniSessionEvent['type'];

package/dist/core/runtime/transcript-types.js

@@ -0,0 +1,31 @@
+export const BEEUNI_TRANSCRIPT_SCHEMA = 'beeuni.transcript.v1';
+export const TURN_ERROR_CODES = [
+    'auth',
+    'rate_limit',
+    'credits',
+    'context_length',
+    'output_length',
+    'aborted',
+    'unknown',
+];
+export function isTurnErrorCode(value) {
+    return typeof value === 'string' && TURN_ERROR_CODES.includes(value);
+}
+export const RUNTIME_PERMISSION_REPLIES = ['once', 'always', 'reject'];
+export const RUNTIME_PERMISSION_CAPABILITIES = [
+    'read',
+    'edit',
+    'glob',
+    'grep',
+    'list',
+    'bash',
+    'task',
+    'external_directory',
+    'todowrite',
+    'question',
+    'webfetch',
+    'websearch',
+    'lsp',
+    'doom_loop',
+    'skill',
+];

package/dist/core/runtime/triggers.d.ts

@@ -0,0 +1 @@
+export declare function triggersRequest<T>(baseUrl: string, path: string, init?: RequestInit): Promise<T>;

package/dist/core/runtime/triggers.js

@@ -0,0 +1,18 @@
+import { authenticatedFetch } from '../http/auth.js';
+export async function triggersRequest(baseUrl, path, init) {
+    let base = baseUrl;
+    while (base.endsWith('/'))
+        base = base.slice(0, -1);
+    const response = await authenticatedFetch(`${base}/beeuni/triggers${path}`, {
+        ...init,
+        headers: {
+            'Content-Type': 'application/json',
+            ...init?.headers,
+        },
+    });
+    const body = await response.json();
+    if (!response.ok) {
+        throw new Error(body?.error || body?.message || `Request failed with ${response.status}`);
+    }
+    return body;
+}

package/dist/core/session/compaction.d.ts

@@ -0,0 +1,10 @@
+export declare const OPTIMISTIC_COMPACTION_MAX_MS = 60000;
+export interface CompactionInputs {
+    optimisticAtMs: number | null;
+    serverCompactingAtMs: number | null;
+    nowMs: number;
+}
+export declare function projectCompacting(inputs: CompactionInputs): boolean;
+export declare function compactionExpiryAtMs(inputs: CompactionInputs): number | null;
+export declare const SERVER_COMPACTION_REVALIDATE_MS = 90000;
+export declare function serverCompactionRevalidateAtMs(inputs: CompactionInputs): number | null;

package/dist/core/session/compaction.js

@@ -0,0 +1,22 @@
+export const OPTIMISTIC_COMPACTION_MAX_MS = 60_000;
+export function projectCompacting(inputs) {
+    if (inputs.serverCompactingAtMs !== null)
+        return true;
+    if (inputs.optimisticAtMs === null)
+        return false;
+    return inputs.nowMs - inputs.optimisticAtMs < OPTIMISTIC_COMPACTION_MAX_MS;
+}
+export function compactionExpiryAtMs(inputs) {
+    if (inputs.serverCompactingAtMs !== null)
+        return null;
+    if (inputs.optimisticAtMs === null)
+        return null;
+    const deadline = inputs.optimisticAtMs + OPTIMISTIC_COMPACTION_MAX_MS;
+    return deadline > inputs.nowMs ? deadline : null;
+}
+export const SERVER_COMPACTION_REVALIDATE_MS = 90_000;
+export function serverCompactionRevalidateAtMs(inputs) {
+    if (inputs.serverCompactingAtMs === null)
+        return null;
+    return inputs.serverCompactingAtMs + SERVER_COMPACTION_REVALIDATE_MS;
+}

package/dist/core/session/connection.d.ts

@@ -0,0 +1,20 @@
+import { type SessionHealthResult } from './health.js';
+export type SessionConnection = 'unknown' | 'waking' | 'connecting' | 'live' | 'unreachable';
+export type SandboxLifecycle = 'queued' | 'branching' | 'provisioning' | 'running' | 'stopped' | 'archived' | 'failed' | 'completed' | null;
+export interface SessionConnectionInputs {
+    sandbox: SandboxLifecycle;
+    runtimeReady: boolean;
+    unreachable?: boolean;
+    stalled?: boolean;
+    activityFresh?: boolean;
+}
+export declare function projectSessionConnection(input: SessionConnectionInputs): SessionConnection;
+export declare function connectionIsFaulted(connection: SessionConnection): boolean;
+export declare function connectionFromHealth(result: SessionHealthResult | null): SessionConnection;
+export declare const CONNECTION_FAULT_GRACE_MS = 10000;
+export interface SettledConnection {
+    connection: SessionConnection;
+    faultSinceMs: number | null;
+}
+export declare const INITIAL_SETTLED_CONNECTION: SettledConnection;
+export declare function settleSessionConnection(prev: SettledConnection, observed: SessionConnection, nowMs: number, graceMs?: number): SettledConnection;

package/dist/core/session/connection.js

@@ -0,0 +1,52 @@
+import { isRuntimeReady } from './health.js';
+export function projectSessionConnection(input) {
+    if (input.activityFresh)
+        return 'live';
+    if (input.runtimeReady)
+        return 'live';
+    if (input.unreachable || input.stalled)
+        return 'unreachable';
+    if (input.sandbox === 'stopped' || input.sandbox === 'archived')
+        return 'waking';
+    if (input.sandbox === 'provisioning' ||
+        input.sandbox === 'queued' ||
+        input.sandbox === 'branching') {
+        return 'waking';
+    }
+    if (input.sandbox === 'completed')
+        return 'unknown';
+    if (input.sandbox === 'failed')
+        return 'unreachable';
+    if (input.sandbox === 'running')
+        return 'connecting';
+    return 'unknown';
+}
+export function connectionIsFaulted(connection) {
+    return connection === 'unreachable';
+}
+export function connectionFromHealth(result) {
+    if (!result || result.status === 0)
+        return 'unknown';
+    if (result.ok && isRuntimeReady(result.health))
+        return 'live';
+    if (result.hop === 'control_plane')
+        return 'waking';
+    if (result.ok || result.health?.status === 'starting')
+        return 'connecting';
+    return 'unreachable';
+}
+export const CONNECTION_FAULT_GRACE_MS = 10_000;
+export const INITIAL_SETTLED_CONNECTION = { connection: 'unknown', faultSinceMs: null };
+export function settleSessionConnection(prev, observed, nowMs, graceMs = CONNECTION_FAULT_GRACE_MS) {
+    if (observed === 'unknown')
+        return prev;
+    if (observed === 'live' || observed === 'waking')
+        return { connection: observed, faultSinceMs: null };
+    const faultSinceMs = prev.faultSinceMs ?? nowMs;
+    const persisted = nowMs - faultSinceMs >= graceMs;
+    if (!persisted) {
+        const held = prev.connection === 'unknown' ? 'connecting' : prev.connection;
+        return { connection: held, faultSinceMs };
+    }
+    return { connection: observed, faultSinceMs };
+}