@tangle-network/agent-app 0.22.0 → 0.24.0

package/dist/sandbox/index.d.ts

@@ -4,6 +4,188 @@ import { a as AppToolName, c as ToolHeaderNames } from '../auth-BlS9GWfL.js';
 import { b as AppToolContext } from '../types-2rOJo8Hc.js';
 import { Harness } from '../harness/index.js';
 
+interface WorkspaceSandboxInstanceLike {
+    id: string;
+    name?: string;
+    status?: string;
+    connection?: {
+        runtimeUrl?: string;
+        sidecarUrl?: string;
+        authToken?: string;
+        sidecarToken?: string;
+        authTokenExpiresAt?: string;
+    } | null;
+}
+interface WorkspaceSandboxEnsureContext {
+    workspaceId: string;
+    userId: string;
+}
+interface WorkspaceSandboxManagerOptions<TClient, TBox extends WorkspaceSandboxInstanceLike, TEnsureOptions = void> {
+    getClient: (ctx: WorkspaceSandboxEnsureContext) => Promise<TClient> | TClient;
+    nameForWorkspace: (workspaceId: string, ctx: WorkspaceSandboxEnsureContext) => string;
+    listSandboxes: (client: TClient, ctx: WorkspaceSandboxEnsureContext) => Promise<TBox[]>;
+    createSandbox: (args: {
+        client: TClient;
+        ctx: WorkspaceSandboxEnsureContext;
+        name: string;
+        options: TEnsureOptions;
+        listError?: unknown;
+    }) => Promise<TBox>;
+    waitForRunning?: (box: TBox, ctx: WorkspaceSandboxEnsureContext) => Promise<void>;
+    prepareExisting?: (box: TBox, ctx: WorkspaceSandboxEnsureContext, options: TEnsureOptions) => Promise<TBox | void>;
+    prepareCreated?: (box: TBox, ctx: WorkspaceSandboxEnsureContext, options: TEnsureOptions) => Promise<TBox | void>;
+    onListError?: (error: unknown, ctx: WorkspaceSandboxEnsureContext) => void;
+}
+interface WorkspaceSandboxManager<TBox extends WorkspaceSandboxInstanceLike, TEnsureOptions = void> {
+    ensureWorkspaceSandbox: (workspaceId: string, userId: string, options?: TEnsureOptions) => Promise<TBox>;
+}
+declare function createWorkspaceSandboxManager<TClient, TBox extends WorkspaceSandboxInstanceLike, TEnsureOptions = void>(opts: WorkspaceSandboxManagerOptions<TClient, TBox, TEnsureOptions>): WorkspaceSandboxManager<TBox, TEnsureOptions>;
+interface SandboxTerminalTokenOptions {
+    secret?: string;
+    prefix?: string;
+    expiresInMs?: number;
+    now?: () => number;
+}
+interface SandboxTerminalTokenSubject {
+    userId: string;
+    workspaceId: string;
+    sandboxId: string;
+}
+interface SandboxTerminalTokenResult {
+    token: string;
+    expiresAt: Date;
+}
+declare function createSandboxTerminalToken(subject: SandboxTerminalTokenSubject, opts: SandboxTerminalTokenOptions): Promise<SandboxTerminalTokenResult>;
+declare function verifySandboxTerminalToken(token: string, expected: SandboxTerminalTokenSubject, opts: SandboxTerminalTokenOptions): Promise<boolean>;
+interface AuthenticatedSandboxUser {
+    id: string;
+}
+interface WorkspaceSandboxConnectionHandlerOptions<TBox extends WorkspaceSandboxInstanceLike> {
+    requireUser: (request: Request) => Promise<AuthenticatedSandboxUser>;
+    requireWorkspaceAccess: (args: {
+        request: Request;
+        userId: string;
+        workspaceId: string;
+    }) => Promise<void>;
+    ensureWorkspaceSandbox: (workspaceId: string, userId: string) => Promise<TBox>;
+    tokenSecret: string | (() => string | undefined);
+    tokenExpiresInMs?: number;
+    tokenPrefix?: string;
+    proxyRuntimeUrl?: (args: {
+        request: Request;
+        workspaceId: string;
+        sandboxId: string;
+        box: TBox;
+    }) => string;
+    exposeDirectSidecar?: boolean;
+}
+interface WorkspaceSandboxConnectionArgs {
+    request: Request;
+    params: {
+        workspaceId?: string;
+    };
+}
+declare function createWorkspaceSandboxConnectionHandler<TBox extends WorkspaceSandboxInstanceLike>(opts: WorkspaceSandboxConnectionHandlerOptions<TBox>): ({ request, params }: WorkspaceSandboxConnectionArgs) => Promise<Response>;
+interface SandboxApiCredentials {
+    baseUrl: string;
+    apiKey: string;
+}
+interface SandboxRuntimeConnection {
+    runtimeUrl: string;
+    authToken?: string;
+}
+interface WorkspaceSandboxRuntimeProxyHandlerOptions {
+    requireUser: (request: Request) => Promise<AuthenticatedSandboxUser>;
+    requireWorkspaceAccess: (args: {
+        request: Request;
+        userId: string;
+        workspaceId: string;
+        sandboxId: string;
+    }) => Promise<void>;
+    getSandboxApiCredentials: (args: {
+        request: Request;
+        userId: string;
+        workspaceId: string;
+        sandboxId: string;
+    }) => Promise<SandboxApiCredentials>;
+    getSandboxRuntimeConnection?: (args: {
+        request: Request;
+        userId: string;
+        workspaceId: string;
+        sandboxId: string;
+    }) => Promise<SandboxRuntimeConnection | null | undefined>;
+    tokenSecret: string | (() => string | undefined);
+    tokenPrefix?: string;
+    fetch?: typeof fetch;
+    forwardHeaders?: string[];
+}
+interface WorkspaceSandboxRuntimeProxyArgs {
+    request: Request;
+    params: {
+        workspaceId?: string;
+        sandboxId?: string;
+        '*'?: string;
+    };
+}
+declare function createWorkspaceSandboxRuntimeProxyHandler(opts: WorkspaceSandboxRuntimeProxyHandlerOptions): ({ request, params }: WorkspaceSandboxRuntimeProxyArgs) => Promise<Response>;
+interface SandboxTerminalWsMatch {
+    workspaceId: string;
+    sandboxId: string;
+    subPath: string;
+}
+/**
+ * Parse a same-origin terminal-WS pathname into its parts, or `null` when the
+ * path is not a sandbox terminal WebSocket. Matches the default `runtimeUrl`
+ * convention emitted by {@link createWorkspaceSandboxConnectionHandler}
+ * (`/api/workspaces/:workspaceId/sandbox/runtime/:sandboxId`) with a canonical
+ * `terminals/:id/ws` sub-path. `subPath` is left URL-encoded for re-use in the
+ * upstream URL; the ids are decoded for auth checks.
+ */
+declare function matchSandboxTerminalWsPath(pathname: string): SandboxTerminalWsMatch | null;
+/** True when `request` is a WebSocket upgrade for a sandbox terminal path. */
+declare function isSandboxTerminalWsUpgrade(request: Request): boolean;
+interface WorkspaceSandboxTerminalUpgradeHandlerOptions {
+    requireUser: (request: Request) => Promise<AuthenticatedSandboxUser>;
+    requireWorkspaceAccess: (args: {
+        request: Request;
+        userId: string;
+        workspaceId: string;
+        sandboxId: string;
+    }) => Promise<void>;
+    getSandboxApiCredentials: (args: {
+        request: Request;
+        userId: string;
+        workspaceId: string;
+        sandboxId: string;
+    }) => Promise<SandboxApiCredentials>;
+    getSandboxRuntimeConnection?: (args: {
+        request: Request;
+        userId: string;
+        workspaceId: string;
+        sandboxId: string;
+    }) => Promise<SandboxRuntimeConnection | null | undefined>;
+    tokenSecret: string | (() => string | undefined);
+    tokenPrefix?: string;
+    fetch?: typeof fetch;
+}
+/**
+ * Build a Worker-entry handler that proxies a sandbox terminal WebSocket
+ * upgrade to the sandbox API runtime proxy. Returns `null` when the request is
+ * not a terminal WS upgrade, so the caller can fall through to its normal
+ * request handler:
+ *
+ * ```ts
+ * const handled = await handleSandboxTerminalUpgrade(request)
+ * if (handled) return handled
+ * ```
+ */
+declare function createWorkspaceSandboxTerminalUpgradeHandler(opts: WorkspaceSandboxTerminalUpgradeHandlerOptions): (request: Request) => Promise<Response | null>;
+declare function buildSandboxRuntimeProxyHeaders(source: Headers, sandboxApiKey: string, forwardHeaders?: string[]): Headers;
+declare function encodeSandboxRuntimePath(runtimePath: string): string | null;
+declare function bearerToken(value: string | null): string | null;
+declare function bearerSubprotocolToken(value: string | null): string | null;
+declare function terminalTokenFromRequest(headers: Headers): string | null;
+
 type Outcome<T> = {
     succeeded: true;
     value: T;
@@ -194,4 +376,4 @@ declare function classifySeveredStream(event: unknown): SandboxStepTransition |
 declare function isTerminalPromptEvent(event: unknown): boolean;
 declare function detectInteractiveQuestion(event: unknown): string | null;
 
-export { type AppToolDescriptor, type BuildAppToolMcpServersOptions, DEFAULT_SANDBOX_RESOURCES, type EnsureWorkspaceSandboxOptions, type LivenessProbeConfig, type MemberSyncSeam, type Outcome, type ProfileComposeOptions, type ProviderResolutionConfig, type ResolvedModel, type SandboxBuildContext, type SandboxClientCredentials, type SandboxPermissionLevel, type SandboxResourceConfig, type SandboxRestoreSpec, type SandboxRuntimeConfig, type SandboxScope, type SandboxStepTransition, type ScopedTokenResult, type SecretStore, type StreamSandboxPromptOptions, type TerminalProxyIdentity, attachReasoningEffort, buildAppToolMcpServers, classifySeveredStream, deleteSecret, detectInteractiveQuestion, driveSandboxTurn, ensureWorkspaceSandbox, flattenHistory, getClient, isTerminalPromptEvent, mergeExtraMcp, mintSandboxScopedToken, mintTerminalProxyToken, readSecret, resetClientCache, resolveModel, runSandboxPrompt, secretStoreFromClient, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, verifyTerminalProxyToken };
+export { type AppToolDescriptor, type AuthenticatedSandboxUser, type BuildAppToolMcpServersOptions, DEFAULT_SANDBOX_RESOURCES, type EnsureWorkspaceSandboxOptions, type LivenessProbeConfig, type MemberSyncSeam, type Outcome, type ProfileComposeOptions, type ProviderResolutionConfig, type ResolvedModel, type SandboxApiCredentials, type SandboxBuildContext, type SandboxClientCredentials, type SandboxPermissionLevel, type SandboxResourceConfig, type SandboxRestoreSpec, type SandboxRuntimeConfig, type SandboxRuntimeConnection, type SandboxScope, type SandboxStepTransition, type SandboxTerminalTokenOptions, type SandboxTerminalTokenResult, type SandboxTerminalTokenSubject, type SandboxTerminalWsMatch, type ScopedTokenResult, type SecretStore, type StreamSandboxPromptOptions, type TerminalProxyIdentity, type WorkspaceSandboxConnectionArgs, type WorkspaceSandboxConnectionHandlerOptions, type WorkspaceSandboxEnsureContext, type WorkspaceSandboxInstanceLike, type WorkspaceSandboxManager, type WorkspaceSandboxManagerOptions, type WorkspaceSandboxRuntimeProxyArgs, type WorkspaceSandboxRuntimeProxyHandlerOptions, type WorkspaceSandboxTerminalUpgradeHandlerOptions, attachReasoningEffort, bearerSubprotocolToken, bearerToken, buildAppToolMcpServers, buildSandboxRuntimeProxyHeaders, classifySeveredStream, createSandboxTerminalToken, createWorkspaceSandboxConnectionHandler, createWorkspaceSandboxManager, createWorkspaceSandboxRuntimeProxyHandler, createWorkspaceSandboxTerminalUpgradeHandler, deleteSecret, detectInteractiveQuestion, driveSandboxTurn, encodeSandboxRuntimePath, ensureWorkspaceSandbox, flattenHistory, getClient, isSandboxTerminalWsUpgrade, isTerminalPromptEvent, matchSandboxTerminalWsPath, mergeExtraMcp, mintSandboxScopedToken, mintTerminalProxyToken, readSecret, resetClientCache, resolveModel, runSandboxPrompt, secretStoreFromClient, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, terminalTokenFromRequest, verifySandboxTerminalToken, verifyTerminalProxyToken };