@beeuni/sdk 0.1.0

package/dist/core/client/session-handle.d.ts

@@ -0,0 +1,207 @@
+import type { RuntimeClient } from '../runtime/client.js';
+import type { BeeuniPlatformConfig } from '../http/config.js';
+import type { ResolvedPreviewOptions } from '../session/preview-options.js';
+import type { SessionModel } from './session-shared.js';
+export declare function session(projectId: string, sessionId: string, config: BeeuniPlatformConfig, resolvePreviewOptsForSandbox: (sandboxId: string) => ResolvedPreviewOptions): {
+    runtime: RuntimeClient;
+    messages: (options?: {
+        conversationId?: string;
+        limit?: number;
+        before?: string;
+        signal?: AbortSignal;
+    }) => Promise<import("../session/index.js").TranscriptPage>;
+    pending: () => Promise<import("../session/index.js").PendingInteractions>;
+    answerPermission: (requestId: string, reply: import("../../index.js").RuntimePermissionReply, message?: string) => Promise<void>;
+    answerQuestion: (requestId: string, answers: import("../../index.js").RuntimeQuestionAnswer[] | null) => Promise<void>;
+    compact: (model?: {
+        providerID: string;
+        modelID: string;
+    }) => Promise<{
+        providerID: string;
+        modelID: string;
+    }>;
+    files: {
+        list: (dirPath: string) => Promise<import("../../index.js").FileNode[]>;
+        read: (filePath: string) => Promise<import("../../index.js").FileContent>;
+        readBlob: (filePath: string) => Promise<Blob>;
+        status: () => Promise<import("../../index.js").GitFileStatus[]>;
+        findFiles: (query: string, options?: {
+            type?: "file" | "directory";
+            limit?: number;
+        }) => Promise<string[]>;
+        findText: (pattern: string) => Promise<import("../../index.js").FindMatch[]>;
+        upload: (file: File | Blob, targetPath?: string, filename?: string, options?: import("../../index.js").UploadFileOptions) => Promise<import("../../index.js").UploadResult[]>;
+        write: (filePath: string, content: Blob | File) => Promise<import("../../index.js").WriteFileResult>;
+        create: (filePath: string) => Promise<import("../../index.js").UploadResult[]>;
+        copy: (sourcePath: string, destPath: string) => Promise<import("../../index.js").UploadResult[]>;
+        remove: (filePath: string) => Promise<boolean>;
+        mkdir: (dirPath: string) => Promise<boolean>;
+        rename: (from: string, to: string) => Promise<boolean>;
+    };
+    abort: () => Promise<({
+        data: undefined;
+        error: unknown;
+    } | {
+        data: boolean;
+        error: undefined;
+    }) & {
+        request: Request;
+        response: Response;
+    }>;
+    rewind: (messageId: string) => Promise<({
+        data: undefined;
+        error: unknown;
+    } | {
+        data: import("../../index.js").Session;
+        error: undefined;
+    }) & {
+        request: Request;
+        response: Response;
+    }>;
+    restoreRewind: () => Promise<({
+        data: undefined;
+        error: unknown;
+    } | {
+        data: import("../../index.js").Session;
+        error: undefined;
+    }) & {
+        request: Request;
+        response: Response;
+    }>;
+    stream: (opts: {
+        onEvent: (event: import("../../index.js").RuntimeEvent) => void;
+        onGapRehydrate?: (gapMs: number) => void;
+        signal?: AbortSignal;
+    }) => Promise<import("../../index.js").EventStreamHandle>;
+    scope: () => Promise<import("../../index.js").SessionScope>;
+    providerSecretPool: {
+        list: () => Promise<{
+            pools: import("../../index.js").SessionProviderSecretPool[];
+            can_edit: boolean;
+            personal_user_id?: string | null;
+            personal_keys_reason?: "shared" | "prompted_by_another_member" | "no_person" | null;
+        }>;
+        get: (providerId: string) => Promise<import("../../index.js").SessionProviderSecretPool>;
+        set: (providerId: string, secretIds: string[] | null) => Promise<import("../../index.js").SessionProviderSecretPool>;
+    };
+    rescope: (scope: import("../../index.js").SessionScopeInput) => Promise<import("../../index.js").SessionScope>;
+    setAgent: (agent: string | undefined) => void;
+    send: (text: string, opts?: {
+        model?: SessionModel;
+        agent?: string;
+    }) => Promise<import("../../index.js").CreateSessionPromptResult>;
+    setModel: (model: SessionModel | undefined) => void;
+    changeModel: (model: string) => Promise<import("../../index.js").SessionModelChangeResult>;
+    health: (init?: RequestInit) => Promise<import("../session/index.js").SessionHealthResult>;
+    previewUrl: (port: number, path?: string) => string;
+    proxyUrl: (url?: string) => string | undefined;
+    sandboxPortUrl: (port: number) => string;
+    reminders: {
+        list: () => Promise<{
+            reminders: import("../../index.js").SessionReminder[];
+        }>;
+        create: (input: Parameters<typeof import("../../index.js").createSessionReminder>[2]) => Promise<import("../../index.js").SessionReminder>;
+        update: (reminderId: string, input: Parameters<typeof import("../../index.js").updateSessionReminder>[3]) => Promise<import("../../index.js").SessionReminder>;
+        remove: (reminderId: string) => Promise<{
+            ok: boolean;
+        }>;
+    };
+    audit: (limit?: number, options?: Parameters<typeof import("../../index.js").getSessionAudit>[3]) => Promise<import("../../index.js").SessionAudit>;
+    attachments: {
+        upload: (file: File, options?: Parameters<typeof import("../../index.js").uploadSessionAttachment>[3]) => Promise<import("../../index.js").SessionAttachment>;
+        read: (attachmentId: string, signal?: AbortSignal) => Promise<Blob>;
+    };
+    transcript: (options?: Parameters<typeof import("../../index.js").getSessionTranscript>[2]) => Promise<import("../../index.js").SessionTranscript>;
+    messageAuthors: () => Promise<import("../../index.js").SessionMessageAuthors>;
+    modelUsage: () => Promise<import("../../index.js").SessionModelUsage>;
+    transcriptSync: (options?: Parameters<typeof import("../../index.js").getSessionTranscriptSync>[2]) => Promise<import("../../index.js").SessionTranscriptSyncEnvelope>;
+    turn: () => Promise<import("../../index.js").SessionTurnStatus>;
+    prompts: {
+        create: (input: import("../../index.js").CreateSessionPromptInput) => Promise<import("../../index.js").CreateSessionPromptResult>;
+        list: () => Promise<{
+            prompts: import("../../index.js").SessionPrompt[];
+            observed_at?: string;
+        }>;
+        remove: (promptId: string) => Promise<import("../../index.js").RemovedSessionPrompt>;
+        retry: (promptId: string) => Promise<import("../../index.js").SessionPrompt>;
+        edit: (promptId: string, text: string) => Promise<import("../../index.js").SessionPrompt>;
+        interrupt: (promptId: string) => Promise<import("../../index.js").SessionPrompt>;
+        hold: (held: boolean) => Promise<{
+            prompts: import("../../index.js").SessionPrompt[];
+            observed_at?: string;
+        }>;
+    };
+    ensureReady: (opts?: {
+        readyTimeoutMs?: number;
+    }) => Promise<import("../../index.js").SessionRuntimeEntry>;
+    get: (opts?: {
+        showErrors?: boolean;
+    }) => Promise<import("../../index.js").ProjectSession>;
+    presence: (input: {
+        tab_id: string;
+        active: boolean;
+        alerts?: boolean;
+    }, options?: {
+        keepalive?: boolean;
+    }) => Promise<import("../../index.js").ApiResponse<{
+        ok: boolean;
+    }>>;
+    cost: () => Promise<import("../../index.js").SessionCostDetail>;
+    update: (input: Parameters<typeof import("../../index.js").updateProjectSession>[2]) => Promise<import("../../index.js").ProjectSession>;
+    delete: () => Promise<{
+        ok: boolean;
+    }>;
+    start: (options?: (number | {
+        waitMs?: number;
+        repositoryMode?: "previous";
+        keepStopped?: boolean;
+        intentAgeMs?: number;
+    }) | undefined) => Promise<import("../../index.js").SessionStartResult | null>;
+    startOrThrow: (options?: (number | {
+        waitMs?: number;
+        repositoryMode?: "previous";
+        keepStopped?: boolean;
+        intentAgeMs?: number;
+    }) | undefined) => Promise<import("../../index.js").SessionStartResult>;
+    restart: () => Promise<{
+        ok: boolean;
+        session_id: string;
+        status: string;
+        state_carried?: boolean | null;
+        warning?: string;
+    }>;
+    stop: () => Promise<{
+        ok: boolean;
+        session_id: string;
+        status: string;
+    }>;
+    configState: () => Promise<import("../../index.js").SessionConfigState>;
+    reloadConfig: (input?: Parameters<typeof import("../../index.js").reloadProjectSessionConfig>[2]) => Promise<import("../../index.js").SessionReloadResult>;
+    reloadConfigStream: (input: {
+        refresh_repo?: boolean;
+        force?: boolean;
+    }, onEvent: (event: import("../../index.js").SessionReloadStreamEvent) => void, options?: import("../../index.js").ApiClientOptions | undefined) => Promise<import("../../index.js").SessionReloadResult>;
+    setSharing: (intent: Parameters<typeof import("../../index.js").setProjectSessionSharing>[2]) => Promise<import("../../index.js").ProjectSession>;
+    previews: () => Promise<{
+        candidates: import("../../index.js").SessionPreviewCandidate[];
+    }>;
+    participants: () => Promise<import("../../index.js").SessionParticipants>;
+    watch: () => Promise<{
+        watching: boolean;
+    }>;
+    setWatch: (watching: boolean) => Promise<{
+        watching: boolean;
+    }>;
+    commit: (input?: Parameters<typeof import("../../index.js").commitSessionChanges>[2]) => Promise<import("../../index.js").CommitSessionResult>;
+    publicShares: {
+        list: () => Promise<{
+            shares: import("../../index.js").SessionPublicShare[];
+        }>;
+        create: (input: import("../../index.js").CreateSessionPublicShareInput) => Promise<{
+            share: import("../../index.js").SessionPublicShare;
+        }>;
+        revoke: (shareId: string) => Promise<{
+            share: import("../../index.js").SessionPublicShare;
+        }>;
+    };
+};

package/dist/core/client/session-handle.js

@@ -0,0 +1,53 @@
+import { bindSessionDefaults } from './session-defaults.js';
+import { bindSessionReadiness } from './session-readiness.js';
+import { bindSessionRuntime } from './session-runtime.js';
+import { bindSessionActionsResources } from './session-actions-resources.js';
+import { bindSessionActionsSecurity } from './session-actions-security.js';
+import { bindSessionActionsServices } from './session-actions-services.js';
+import { bindSessionFiles } from './session-files.js';
+import { bindSessionLifecycleResources } from './session-lifecycle-resources.js';
+import { bindSessionLifecycleSecurity } from './session-lifecycle-security.js';
+import { bindSessionPreview } from './session-preview.js';
+import { getClientForUrl } from '../runtime/client.js';
+export function session(projectId, sessionId, config, resolvePreviewOptsForSandbox) {
+    let _model;
+    let _agent;
+    const { persistedPromptDefaults, clearPersistedDefaults } = bindSessionDefaults(projectId, sessionId);
+    const { ensureReady, tryResolveReady, requireReady, forgetReady } = bindSessionReadiness(projectId, sessionId, config);
+    const context = {
+        projectId,
+        sessionId,
+        ensureReady,
+        tryResolveReady,
+        requireReady,
+        forgetReady,
+        resolvePreviewOptsForSandbox,
+        get model() {
+            return _model;
+        },
+        set model(value) {
+            _model = value;
+        },
+        get agent() {
+            return _agent;
+        },
+        set agent(value) {
+            _agent = value;
+        },
+        clearPersistedDefaults,
+        persistedPromptDefaults,
+    };
+    return {
+        ...bindSessionLifecycleResources(context),
+        ...bindSessionLifecycleSecurity(context),
+        ...bindSessionPreview(context),
+        ...bindSessionActionsResources(context),
+        ...bindSessionActionsSecurity(context),
+        ...bindSessionActionsServices(context),
+        files: bindSessionFiles(ensureReady),
+        ...bindSessionRuntime(context),
+        get runtime() {
+            return getClientForUrl(requireReady('runtime').runtimeUrl);
+        },
+    };
+}

package/dist/core/client/session-lifecycle-resources.d.ts

@@ -0,0 +1,76 @@
+import * as P from '../rest/projects-client/index.js';
+import type { SessionBindingContext } from './session-context.js';
+type DropFirst2<T extends unknown[]> = T extends [unknown, unknown, ...infer R] ? R : [];
+export declare function bindSessionLifecycleResources(ctx: SessionBindingContext): {
+    get: (opts?: {
+        showErrors?: boolean;
+    }) => Promise<P.ProjectSession>;
+    presence: (input: {
+        tab_id: string;
+        active: boolean;
+        alerts?: boolean;
+    }, options?: {
+        keepalive?: boolean;
+    }) => Promise<import("../../index.js").ApiResponse<{
+        ok: boolean;
+    }>>;
+    cost: () => Promise<P.SessionCostDetail>;
+    update: (input: Parameters<typeof P.updateProjectSession>[2]) => Promise<P.ProjectSession>;
+    delete: () => Promise<{
+        ok: boolean;
+    }>;
+    start: (options?: (number | {
+        waitMs?: number;
+        repositoryMode?: "previous";
+        keepStopped?: boolean;
+        intentAgeMs?: number;
+    }) | undefined) => Promise<P.SessionStartResult | null>;
+    startOrThrow: (options?: (number | {
+        waitMs?: number;
+        repositoryMode?: "previous";
+        keepStopped?: boolean;
+        intentAgeMs?: number;
+    }) | undefined) => Promise<P.SessionStartResult>;
+    restart: () => Promise<{
+        ok: boolean;
+        session_id: string;
+        status: string;
+        state_carried?: boolean | null;
+        warning?: string;
+    }>;
+    stop: () => Promise<{
+        ok: boolean;
+        session_id: string;
+        status: string;
+    }>;
+    configState: () => Promise<P.SessionConfigState>;
+    reloadConfig: (input?: Parameters<typeof P.reloadProjectSessionConfig>[2]) => Promise<P.SessionReloadResult>;
+    reloadConfigStream: (input: {
+        refresh_repo?: boolean;
+        force?: boolean;
+    }, onEvent: (event: P.SessionReloadStreamEvent) => void, options?: import("../../index.js").ApiClientOptions | undefined) => Promise<P.SessionReloadResult>;
+    setSharing: (intent: Parameters<typeof P.setProjectSessionSharing>[2]) => Promise<P.ProjectSession>;
+    previews: () => Promise<{
+        candidates: P.SessionPreviewCandidate[];
+    }>;
+    participants: () => Promise<P.SessionParticipants>;
+    watch: () => Promise<{
+        watching: boolean;
+    }>;
+    setWatch: (watching: boolean) => Promise<{
+        watching: boolean;
+    }>;
+    commit: (input?: Parameters<typeof P.commitSessionChanges>[2]) => Promise<P.CommitSessionResult>;
+    publicShares: {
+        list: () => Promise<{
+            shares: P.SessionPublicShare[];
+        }>;
+        create: (input: P.CreateSessionPublicShareInput) => Promise<{
+            share: P.SessionPublicShare;
+        }>;
+        revoke: (shareId: string) => Promise<{
+            share: P.SessionPublicShare;
+        }>;
+    };
+};
+export {};

package/dist/core/client/session-lifecycle-resources.js

@@ -0,0 +1,44 @@
+import { backendApi } from '../http/api-client.js';
+import * as P from '../rest/projects-client/index.js';
+export function bindSessionLifecycleResources(ctx) {
+    return {
+        get: (opts) => P.getProjectSession(ctx.projectId, ctx.sessionId, opts),
+        presence: (input, options) => backendApi.put(`/projects/${ctx.projectId}/sessions/${ctx.sessionId}/presence`, input, { showErrors: false, keepalive: options?.keepalive ?? !input.active }),
+        cost: () => P.getSessionCostRecord(ctx.sessionId, { projectId: ctx.projectId }),
+        update: (input) => P.updateProjectSession(ctx.projectId, ctx.sessionId, input),
+        delete: () => {
+            ctx.forgetReady();
+            return P.deleteProjectSession(ctx.projectId, ctx.sessionId);
+        },
+        start: (...a) => P.startProjectSession(ctx.projectId, ctx.sessionId, ...a),
+        startOrThrow: (...a) => P.startProjectSessionOrThrow(ctx.projectId, ctx.sessionId, ...a),
+        restart: () => {
+            ctx.forgetReady();
+            return P.restartProjectSession(ctx.projectId, ctx.sessionId);
+        },
+        stop: () => {
+            ctx.forgetReady();
+            return P.stopProjectSession(ctx.projectId, ctx.sessionId);
+        },
+        configState: () => P.getProjectSessionConfigState(ctx.projectId, ctx.sessionId),
+        reloadConfig: (input) => {
+            ctx.forgetReady();
+            return P.reloadProjectSessionConfig(ctx.projectId, ctx.sessionId, input);
+        },
+        reloadConfigStream: (...args) => {
+            ctx.forgetReady();
+            return P.reloadProjectSessionConfigStream(ctx.projectId, ctx.sessionId, ...args);
+        },
+        setSharing: (intent) => P.setProjectSessionSharing(ctx.projectId, ctx.sessionId, intent),
+        previews: () => P.getSessionPreviewCandidates(ctx.projectId, ctx.sessionId),
+        participants: () => P.getSessionParticipants(ctx.projectId, ctx.sessionId),
+        watch: () => P.getSessionWatch(ctx.projectId, ctx.sessionId),
+        setWatch: (watching) => P.setSessionWatch(ctx.projectId, ctx.sessionId, watching),
+        commit: (input) => P.commitSessionChanges(ctx.projectId, ctx.sessionId, input),
+        publicShares: {
+            list: () => P.listSessionPublicShares(ctx.projectId, ctx.sessionId),
+            create: (...a) => P.createSessionPublicShare(ctx.projectId, ctx.sessionId, ...a),
+            revoke: (...a) => P.revokeSessionPublicShare(ctx.projectId, ctx.sessionId, ...a),
+        },
+    };
+}

package/dist/core/client/session-lifecycle-security.d.ts

@@ -0,0 +1,42 @@
+import * as P from '../rest/projects-client/index.js';
+import type { SessionBindingContext } from './session-context.js';
+export declare function bindSessionLifecycleSecurity(ctx: SessionBindingContext): {
+    reminders: {
+        list: () => Promise<{
+            reminders: P.SessionReminder[];
+        }>;
+        create: (input: Parameters<typeof P.createSessionReminder>[2]) => Promise<P.SessionReminder>;
+        update: (reminderId: string, input: Parameters<typeof P.updateSessionReminder>[3]) => Promise<P.SessionReminder>;
+        remove: (reminderId: string) => Promise<{
+            ok: boolean;
+        }>;
+    };
+    audit: (limit?: number, options?: Parameters<typeof P.getSessionAudit>[3]) => Promise<P.SessionAudit>;
+    attachments: {
+        upload: (file: File, options?: Parameters<typeof P.uploadSessionAttachment>[3]) => Promise<P.SessionAttachment>;
+        read: (attachmentId: string, signal?: AbortSignal) => Promise<Blob>;
+    };
+    transcript: (options?: Parameters<typeof P.getSessionTranscript>[2]) => Promise<P.SessionTranscript>;
+    messageAuthors: () => Promise<P.SessionMessageAuthors>;
+    modelUsage: () => Promise<P.SessionModelUsage>;
+    transcriptSync: (options?: Parameters<typeof P.getSessionTranscriptSync>[2]) => Promise<P.SessionTranscriptSyncEnvelope>;
+    turn: () => Promise<P.SessionTurnStatus>;
+    prompts: {
+        create: (input: P.CreateSessionPromptInput) => Promise<P.CreateSessionPromptResult>;
+        list: () => Promise<{
+            prompts: P.SessionPrompt[];
+            observed_at?: string;
+        }>;
+        remove: (promptId: string) => Promise<P.RemovedSessionPrompt>;
+        retry: (promptId: string) => Promise<P.SessionPrompt>;
+        edit: (promptId: string, text: string) => Promise<P.SessionPrompt>;
+        interrupt: (promptId: string) => Promise<P.SessionPrompt>;
+        hold: (held: boolean) => Promise<{
+            prompts: P.SessionPrompt[];
+            observed_at?: string;
+        }>;
+    };
+    ensureReady: (opts?: {
+        readyTimeoutMs?: number;
+    }) => Promise<import("../../index.js").SessionRuntimeEntry>;
+};

package/dist/core/client/session-lifecycle-security.js

@@ -0,0 +1,31 @@
+import * as P from '../rest/projects-client/index.js';
+export function bindSessionLifecycleSecurity(ctx) {
+    return {
+        reminders: {
+            list: () => P.listSessionReminders(ctx.projectId, ctx.sessionId),
+            create: (input) => P.createSessionReminder(ctx.projectId, ctx.sessionId, input),
+            update: (reminderId, input) => P.updateSessionReminder(ctx.projectId, ctx.sessionId, reminderId, input),
+            remove: (reminderId) => P.deleteSessionReminder(ctx.projectId, ctx.sessionId, reminderId),
+        },
+        audit: (limit, options) => P.getSessionAudit(ctx.projectId, ctx.sessionId, limit, options),
+        attachments: {
+            upload: (file, options) => P.uploadSessionAttachment(ctx.projectId, ctx.sessionId, file, options),
+            read: (attachmentId, signal) => P.fetchSessionAttachment(`beeuni-attachment://${ctx.projectId}/${ctx.sessionId}/${attachmentId}`, signal),
+        },
+        transcript: (options) => P.getSessionTranscript(ctx.projectId, ctx.sessionId, options),
+        messageAuthors: () => P.getSessionMessageAuthors(ctx.projectId, ctx.sessionId),
+        modelUsage: () => P.getSessionModelUsage(ctx.projectId, ctx.sessionId),
+        transcriptSync: (options) => P.getSessionTranscriptSync(ctx.projectId, ctx.sessionId, options),
+        turn: () => P.getSessionTurn(ctx.projectId, ctx.sessionId),
+        prompts: {
+            create: (input) => P.createSessionPrompt(ctx.projectId, ctx.sessionId, input),
+            list: () => P.listSessionPrompts(ctx.projectId, ctx.sessionId),
+            remove: (promptId) => P.deleteSessionPrompt(ctx.projectId, ctx.sessionId, promptId),
+            retry: (promptId) => P.retrySessionPrompt(ctx.projectId, ctx.sessionId, promptId),
+            edit: (promptId, text) => P.editSessionPrompt(ctx.projectId, ctx.sessionId, promptId, text),
+            interrupt: (promptId) => P.interruptSessionPrompt(ctx.projectId, ctx.sessionId, promptId),
+            hold: (held) => P.holdSessionPrompts(ctx.projectId, ctx.sessionId, held),
+        },
+        ensureReady: ctx.ensureReady,
+    };
+}

package/dist/core/client/session-preview.d.ts

@@ -0,0 +1,7 @@
+import type { SessionBindingContext } from './session-context.js';
+export declare function bindSessionPreview(ctx: SessionBindingContext): {
+    health: (init?: RequestInit) => Promise<import("../session/index.js").SessionHealthResult>;
+    previewUrl: (port: number, path?: string) => string;
+    proxyUrl: (url?: string) => string | undefined;
+    sandboxPortUrl: (port: number) => string;
+};

package/dist/core/client/session-preview.js

@@ -0,0 +1,11 @@
+import { getSessionHealth } from '../session/health.js';
+import { proxyLocalhostUrl, rewriteLocalhostUrl } from '../session/url.js';
+import { getSandboxUrlForExternalId } from '../session/server-store/url-helpers.js';
+export function bindSessionPreview(ctx) {
+    return {
+        health: (init) => getSessionHealth(ctx.tryResolveReady()?.runtimeUrl ?? null, init),
+        previewUrl: (port, path = '/') => rewriteLocalhostUrl(port, path, ctx.resolvePreviewOptsForSandbox(ctx.requireReady('previewUrl').sandboxId)),
+        proxyUrl: (url) => proxyLocalhostUrl(url, ctx.resolvePreviewOptsForSandbox(ctx.requireReady('proxyUrl').sandboxId)),
+        sandboxPortUrl: (port) => getSandboxUrlForExternalId(ctx.requireReady('sandboxPortUrl').sandboxId, port),
+    };
+}

package/dist/core/client/session-readiness.d.ts

@@ -0,0 +1,10 @@
+import { type BeeuniPlatformConfig } from '../http/config.js';
+import { type SessionRuntimeEntry } from '../session/session-runtime-registry.js';
+export declare function bindSessionReadiness(projectId: string, sessionId: string, config: BeeuniPlatformConfig): {
+    ensureReady: (opts?: {
+        readyTimeoutMs?: number;
+    }) => Promise<SessionRuntimeEntry>;
+    tryResolveReady: () => SessionRuntimeEntry | null;
+    requireReady: (action: string) => SessionRuntimeEntry;
+    forgetReady: () => void;
+};

package/dist/core/client/session-readiness.js

@@ -0,0 +1,54 @@
+import { platformConfig } from '../http/config.js';
+import { loadPreviewUrlTemplate } from '../session/preview-config.js';
+import { clearSessionRuntime, getSessionRuntime, } from '../session/session-runtime-registry.js';
+import { SessionNotReadyError, inFlightSessionStarts } from './session-shared.js';
+import { bindSessionStart } from './session-start.js';
+export function bindSessionReadiness(projectId, sessionId, config) {
+    let _ready = null;
+    function tryResolveReady() {
+        if (_ready)
+            return _ready;
+        const cached = getSessionRuntime(projectId, sessionId);
+        if (cached)
+            _ready = cached;
+        return _ready;
+    }
+    const startRuntime = bindSessionStart(projectId, sessionId);
+    async function ensureReady(opts) {
+        const cached = tryResolveReady();
+        if (cached)
+            return cached;
+        const readyTimeoutMs = opts?.readyTimeoutMs ?? 180_000;
+        const previewConfig = loadPreviewUrlTemplate(platformConfig().backendUrl ?? config.backendUrl).catch(() => null);
+        const key = `${projectId}\n${sessionId}`;
+        const inFlight = inFlightSessionStarts.get(key);
+        if (inFlight) {
+            _ready = await inFlight;
+            await previewConfig;
+            return _ready;
+        }
+        const startPromise = startRuntime(readyTimeoutMs);
+        inFlightSessionStarts.set(key, startPromise);
+        try {
+            _ready = await startPromise;
+            await previewConfig;
+            return _ready;
+        }
+        finally {
+            if (inFlightSessionStarts.get(key) === startPromise) {
+                inFlightSessionStarts.delete(key);
+            }
+        }
+    }
+    function requireReady(action) {
+        const ready = tryResolveReady();
+        if (!ready)
+            throw new SessionNotReadyError(action);
+        return ready;
+    }
+    function forgetReady() {
+        _ready = null;
+        clearSessionRuntime(projectId, sessionId);
+    }
+    return { ensureReady, tryResolveReady, requireReady, forgetReady };
+}

package/dist/core/client/session-runtime.d.ts

@@ -0,0 +1,21 @@
+import { type PendingInteractions, type TranscriptPage } from '../session/runtime-verbs.js';
+import type { RuntimePermissionReply, RuntimeQuestionAnswer } from '../runtime/transcript-types.js';
+import type { SessionBindingContext } from './session-context.js';
+export declare function bindSessionRuntime(ctx: SessionBindingContext): {
+    messages: (options?: {
+        conversationId?: string;
+        limit?: number;
+        before?: string;
+        signal?: AbortSignal;
+    }) => Promise<TranscriptPage>;
+    pending: () => Promise<PendingInteractions>;
+    answerPermission: (requestId: string, reply: RuntimePermissionReply, message?: string) => Promise<void>;
+    answerQuestion: (requestId: string, answers: RuntimeQuestionAnswer[] | null) => Promise<void>;
+    compact: (model?: {
+        providerID: string;
+        modelID: string;
+    }) => Promise<{
+        providerID: string;
+        modelID: string;
+    }>;
+};

package/dist/core/client/session-runtime.js

@@ -0,0 +1,15 @@
+import { authenticatedFetch } from '../http/auth.js';
+import { createRuntimeVerbs, } from '../session/runtime-verbs.js';
+export function bindSessionRuntime(ctx) {
+    async function sessionVerbs() {
+        const { runtimeSessionId, runtimeUrl } = await ctx.ensureReady();
+        return createRuntimeVerbs({ runtimeUrl, rootId: runtimeSessionId, fetch: authenticatedFetch });
+    }
+    return {
+        messages: async (options) => (await sessionVerbs()).messages(options),
+        pending: async () => (await sessionVerbs()).pending(),
+        answerPermission: async (requestId, reply, message) => (await sessionVerbs()).answerPermission(requestId, reply, message),
+        answerQuestion: async (requestId, answers) => (await sessionVerbs()).answerQuestion(requestId, answers),
+        compact: async (model) => (await sessionVerbs()).compact(model),
+    };
+}

package/dist/core/client/session-shared.d.ts

@@ -0,0 +1,20 @@
+import type { SessionRuntimeEntry } from '../session/session-runtime-registry.js';
+export type SessionModel = {
+    providerID: string;
+    modelID: string;
+};
+export declare const inFlightSessionStarts: Map<string, Promise<SessionRuntimeEntry>>;
+export declare function runtimeNotReadyMessage(started: {
+    stage?: string;
+    reason?: string;
+    failure?: {
+        category?: string;
+        message?: string;
+        evidence?: {
+            error?: string | null;
+        } | null;
+    } | null;
+} | null | undefined): string;
+export declare class SessionNotReadyError extends Error {
+    constructor(action: string);
+}

package/dist/core/client/session-shared.js

@@ -0,0 +1,22 @@
+export const inFlightSessionStarts = new Map();
+export function runtimeNotReadyMessage(started) {
+    const base = `Session runtime not ready (stage: ${started?.stage ?? 'unknown'})`;
+    const failure = started?.failure;
+    const parts = [];
+    if (failure?.category)
+        parts.push(failure.category);
+    if (failure?.message)
+        parts.push(failure.message);
+    const providerError = failure?.evidence?.error;
+    if (providerError && providerError !== failure?.message)
+        parts.push(providerError);
+    if (parts.length === 0 && started?.reason)
+        parts.push(started.reason);
+    return parts.length > 0 ? `${base}: ${parts.join(' — ')}` : base;
+}
+export class SessionNotReadyError extends Error {
+    constructor(action) {
+        super(`Session runtime not ready — call \`await session.ensureReady()\` (it drives \`start()\` to completion and resolves this session's own sandbox runtime) before calling \`${action}\`.`);
+        this.name = 'SessionNotReadyError';
+    }
+}

package/dist/core/client/session-start.d.ts

@@ -0,0 +1,2 @@
+import type { SessionRuntimeEntry } from '../session/session-runtime-registry.js';
+export declare function bindSessionStart(projectId: string, sessionId: string): (readyTimeoutMs: number) => Promise<SessionRuntimeEntry>;