@sentry/junior 0.110.0 → 0.111.0

package/dist/build/virtual-config.d.ts

@@ -8,6 +8,7 @@ export interface RuntimePluginModule {
 }
 /** Render the virtual config module consumed by createApp(). */
 export declare function renderVirtualConfig(options: {
+    functionMaxDurationSeconds?: number;
     dashboard?: JuniorDashboardOptions;
     plugins?: PluginCatalogConfig;
     pluginModule?: RuntimePluginModule;
@@ -15,6 +16,7 @@ export declare function renderVirtualConfig(options: {
 }): string;
 /** Inject a virtual module so createApp() can read the plugin list at runtime. */
 export declare function injectVirtualConfig(nitro: Nitro, options?: {
+    functionMaxDurationSeconds?: number;
     loadPluginSet?: () => Promise<JuniorPluginSet | undefined>;
     pluginModule?: RuntimePluginModule;
     plugins?: PluginCatalogConfig;

package/dist/{catalog-runtime-4GI22PXK.js → catalog-runtime-D22W6QEJ.js}

@@ -1,15 +1,15 @@
 import {
   pluginCatalogRuntime
-} from "./chunk-3TV7OEHL.js";
-import "./chunk-Y3H2DN6F.js";
+} from "./chunk-WSRBFHPX.js";
+import "./chunk-XQAYFRWT.js";
 import "./chunk-C4MZ3GP5.js";
-import "./chunk-IYKPU7H6.js";
+import "./chunk-J7APPQIJ.js";
 import "./chunk-42WRQLJ6.js";
 import "./chunk-6GWA276C.js";
 import "./chunk-B3IT5END.js";
 import "./chunk-3V7OFJZC.js";
-import "./chunk-W75ZPAGG.js";
-import "./chunk-ZKIOWEFL.js";
+import "./chunk-MPVES2IC.js";
+import "./chunk-Z4G3WCP3.js";
 import "./chunk-MLKGABMK.js";
 export {
   pluginCatalogRuntime

package/dist/chat/agent/request.d.ts

@@ -13,7 +13,7 @@ import type { ConversationPrivacy } from "@/chat/conversation-privacy";
 import type { CredentialContext } from "@/chat/credentials/context";
 import type { PiMessage } from "@/chat/pi/messages";
 import type { Actor } from "@/chat/actor";
-import type { SandboxAcquiredState } from "@/chat/sandbox/sandbox";
+import type { SandboxRef } from "@/chat/sandbox/ref";
 import type { SandboxEgressTracePropagationConfig } from "@/chat/sandbox/egress/tracing";
 import type { AuthorizationFlowMode } from "@/chat/services/auth-pause";
 import type { AssistantStatusSpec } from "@/chat/slack/assistant-thread/status";
@@ -105,10 +105,7 @@ export interface AgentRunState {
     artifactState?: ThreadArtifactsState;
     pendingAuth?: ConversationPendingAuthState;
     /** Persisted sandbox reuse state from prior slices of this conversation. */
-    sandbox?: {
-        sandboxId?: string;
-        sandboxDependencyProfileHash?: string;
-    };
+    sandboxRef?: SandboxRef;
 }
 /**
  * Carries notification-only callbacks for streaming UI and status surfaces;
@@ -142,7 +139,7 @@ export interface AgentRunDurability {
     shouldYield?: () => boolean;
     drainSteeringMessages?: (accept: (messages: AgentRunSteeringMessage[]) => Promise<void>) => Promise<AgentRunSteeringMessage[]>;
     recordPendingAuth?: (pendingAuth: ConversationPendingAuthState | undefined) => void | Promise<void>;
-    onSandboxAcquired?: (sandbox: SandboxAcquiredState) => void | Promise<void>;
+    onSandboxRefChanged?: (sandboxRef: SandboxRef) => void | Promise<void>;
     onArtifactStateUpdated?: (artifactState: ThreadArtifactsState) => void | Promise<void>;
 }
 /** Groups the per-slice run request by the runtime role each field serves. */

package/dist/chat/agent/sandbox.d.ts

@@ -1,15 +1,40 @@
 /**
- * Run-scoped sandbox workspace.
+ * Agent-facing sandbox adaptation.
  *
- * Exposes a stable workspace port to tools while deferring the actual
- * sandbox boot until a tool first touches the filesystem or runs a command,
- * and rebinding when the executor's sandbox identity changes mid-run.
+ * The sandbox module owns provider lifecycle and recovery. This module adds
+ * agent-specific preparation, durable reference propagation, custom command
+ * routing, and generated-artifact materialization.
  */
-import { type LogContext } from "@/chat/logging";
-import type { SandboxExecutor } from "@/chat/sandbox/sandbox";
+import type { FileUpload } from "chat";
+import { type Actor } from "@/chat/actor";
+import type { ChannelConfigurationService } from "@/chat/configuration/types";
+import type { CredentialContext } from "@/chat/credentials/context";
+import type { LogContext } from "@/chat/logging";
+import type { SandboxEgressTracePropagationConfig } from "@/chat/sandbox/egress/tracing";
+import type { SandboxRef } from "@/chat/sandbox/ref";
+import { type SandboxTools } from "@/chat/sandbox/sandbox";
 import type { SandboxWorkspace } from "@/chat/sandbox/workspace";
-/** Create a lazy-boot workspace port bound to the run's sandbox executor. */
-export declare function createLazySandboxWorkspace(args: {
-    executor: SandboxExecutor;
-    spanContext: LogContext;
-}): SandboxWorkspace;
+import type { Skill, SkillMetadata } from "@/chat/skills";
+import type { GeneratedArtifactFileRef } from "@/chat/tools/sandbox/file-uploads";
+export interface AgentSandboxOptions {
+    sandboxRef?: SandboxRef;
+    skills: SkillMetadata[];
+    traceContext: LogContext;
+    tracePropagation?: SandboxEgressTracePropagationConfig;
+    credentialEgress?: CredentialContext;
+    actor?: Actor;
+    channelConfiguration?: ChannelConfigurationService;
+    configurationValues: Record<string, unknown>;
+    getActiveSkill(): Skill | null;
+    prepareSandbox(workspace: SandboxWorkspace): void | Promise<void>;
+    onSandboxRefChanged(sandboxRef: SandboxRef): void;
+    persistSandboxRef?(sandboxRef: SandboxRef): void | Promise<void>;
+}
+export interface AgentSandbox {
+    readonly tools: SandboxTools;
+    readonly workspace: SandboxWorkspace;
+    sandboxRef(): SandboxRef | undefined;
+    writeGeneratedArtifacts(files: FileUpload[]): Promise<GeneratedArtifactFileRef[]>;
+}
+/** Create run-scoped sandbox capabilities adapted to the current agent context. */
+export declare function createAgentSandbox(options: AgentSandboxOptions): AgentSandbox;

package/dist/chat/agent/tools.d.ts

@@ -2,7 +2,7 @@
  * Run tool wiring.
  *
  * Builds everything the agent can act through for one run slice: the sandbox
- * executor and lazy workspace, MCP and plugin auth orchestration, MCP
+ * access, MCP and plugin auth orchestration, MCP
  * provider restoration from durable history, and the Pi-facing tool surfaces
  * (main-agent tools plus runtime control tools). Auth pauses raised while
  * restoring providers are thrown here so the run parks before prompting.
@@ -16,11 +16,11 @@ import { McpToolManager } from "@/chat/mcp/tool-manager";
 import type { AnyToolDefinition } from "@/chat/tools/definition";
 import type { ToolRuntimeContext } from "@/chat/tools/types";
 import { type ActiveMcpCatalogSummary } from "@/chat/tool-support/skill/mcp-tool-summary";
-import { type SandboxExecutor } from "@/chat/sandbox/sandbox";
+import type { SandboxRef } from "@/chat/sandbox/ref";
 import type { PiMessage } from "@/chat/pi/messages";
 import type { LogContext } from "@/chat/logging";
 import type { ConversationPrivacy } from "@/chat/conversation-privacy";
-import { type Actor } from "@/chat/actor";
+import type { Actor } from "@/chat/actor";
 import type { ThreadArtifactsState } from "@/chat/state/artifacts";
 import type { AuthorizationPauseError } from "@/chat/services/auth-pause";
 import type { AgentTurnSurface } from "@/chat/state/turn-session";
@@ -41,10 +41,7 @@ interface ToolWiringArgs {
     generatedFiles: FileUpload[];
     invokedSkill: SkillMetadata | null;
     observers: AgentRunObservers;
-    onSandboxMetadataChanged: (sandbox: {
-        sandboxId?: string;
-        sandboxDependencyProfileHash?: string;
-    }) => void;
+    onSandboxRefChanged: (sandboxRef: SandboxRef) => void;
     policy: AgentRunPolicy;
     preAgentPromptMessages: () => PiMessage[];
     priorPiMessages: PiMessage[] | undefined;
@@ -68,7 +65,7 @@ export interface ToolWiring {
     getPendingAuthPause: () => AuthorizationPauseError | undefined;
     mcpToolManager: McpToolManager;
     pluginHooks: PluginHookRunner;
-    sandboxExecutor: SandboxExecutor;
+    getSandboxRef: () => SandboxRef | undefined;
     toolGuidance: Array<{
         name: string;
         promptGuidelines: AnyToolDefinition["promptGuidelines"];

package/dist/chat/config.d.ts

@@ -5,9 +5,12 @@ import { type ExecutionProfileConfig } from "@/chat/model-profile";
  * Junior can abort, persist, and schedule continuation before host teardown.
  */
 export declare const FUNCTION_TIMEOUT_BUFFER_SECONDS = 20;
+/** Additional buffer that makes conversation work yield before the hard request deadline. */
+export declare const CONVERSATION_WORK_SOFT_YIELD_BUFFER_SECONDS = 40;
 export interface BotConfig {
     embeddingModelId: string;
     fastModelId: string;
+    imageGenerationModelId: string;
     loadingMessages: string[];
     profiles: Readonly<Record<string, ExecutionProfileConfig>>;
     reasoningLevel?: TurnReasoningLevel;
@@ -16,11 +19,13 @@ export interface BotConfig {
     maxSlicesPerTurn: number;
     turnTimeoutMs: number;
     userName: string;
+    webSearchModelId: string;
 }
 export type SqlDriver = "neon" | "postgres";
 export interface ChatConfig {
     bot: BotConfig;
     functionMaxDurationSeconds: number;
+    conversationWorkSoftYieldAfterMs: number;
     sql: {
         databaseUrl: string;
         driver: SqlDriver;
@@ -41,7 +46,9 @@ export interface ChatConfig {
     };
 }
 /** Parse all chat configuration from environment variables. */
-export declare function readChatConfig(env?: NodeJS.ProcessEnv): ChatConfig;
+export declare function readChatConfig(env?: NodeJS.ProcessEnv, functionMaxDurationSeconds?: number): ChatConfig;
+/** Apply the host execution budget injected by juniorNitro(). */
+export declare function configureFunctionMaxDurationSeconds(functionMaxDurationSeconds: number): void;
 /** Return the chat configuration (parsed once at startup). */
 export declare function getChatConfig(): ChatConfig;
 /** Bot configuration derived from environment at module load. */

package/dist/chat/pi/sdk.d.ts

@@ -3,5 +3,5 @@
  * are re-exported here so tests can mock a single Junior-owned path instead
  * of Pi's internal subpath layout, which changes across SDK versions.
  */
-export { completeSimple, getEnvApiKey, getModels, registerApiProvider, type Message, type Model, type ThinkingLevel, } from "@earendil-works/pi-ai/compat";
+export { completeSimple, getEnvApiKey, getModel, getModels, isRetryableAssistantError, registerApiProvider, type Message, type Model, type ThinkingLevel, } from "@earendil-works/pi-ai/compat";
 export { stream as streamAnthropic, streamSimple as streamSimpleAnthropic, } from "@earendil-works/pi-ai/api/anthropic-messages";

package/dist/chat/plugins/agent-hooks.d.ts

@@ -2,7 +2,7 @@ import type { PluginRoute, PluginOperationalReport, PluginRouteApp, ResourceEven
 import type { PluginPromptContributionContext } from "@/chat/plugins/prompt";
 import type { AnyToolDefinition } from "@/chat/tools/definition";
 import type { ToolRuntimeContext } from "@/chat/tools/types";
-import type { SandboxInstance } from "@/chat/sandbox/workspace";
+import type { SandboxWorkspace } from "@/chat/sandbox/workspace";
 import type { Actor } from "@/chat/actor";
 /** Signal that a plugin intentionally denied a tool execution. */
 export declare class PluginHookDeniedError extends Error {
@@ -25,7 +25,7 @@ export interface PluginApiRouteRegistration {
 }
 export interface PluginHookRunner {
     beforeToolExecute(input: ToolHookInput): Promise<ToolHookResult>;
-    prepareSandbox(sandbox: SandboxInstance): Promise<void>;
+    prepareSandbox(workspace: SandboxWorkspace): Promise<void>;
 }
 /** Validate plugin identity before it can affect process-wide hooks. */
 export declare function validatePlugins(plugins: PluginRegistration[]): void;

package/dist/chat/runtime/agent-continue-runner.d.ts

@@ -11,14 +11,18 @@ export interface AgentContinueRunnerOptions {
         sessionId: string;
     }) => Promise<void>;
 }
+/** Per-worker controls for one continued run. */
+export interface AgentContinueRunOptions {
+    shouldYield?: () => boolean;
+}
 /**
  * Continue one paused Slack agent run from durable conversation state.
  *
  * Returns false when the session became stale before generation began.
  */
-export declare function continueSlackAgentRun(payload: AgentContinueRequest, options: AgentContinueRunnerOptions): Promise<boolean>;
+export declare function continueSlackAgentRun(payload: AgentContinueRequest, options: AgentContinueRunnerOptions, runOptions?: AgentContinueRunOptions): Promise<boolean>;
 /** Resume the first valid paused Slack session for an idle conversation. */
-export declare function resumeAwaitingSlackContinuation(conversationId: string, options: AgentContinueRunnerOptions): Promise<boolean>;
+export declare function resumeAwaitingSlackContinuation(conversationId: string, options: AgentContinueRunnerOptions, runOptions?: AgentContinueRunOptions): Promise<boolean>;
 /**
  * Retry agent continuation when the normal Slack thread lock is briefly busy.
  *
@@ -26,4 +30,4 @@ export declare function resumeAwaitingSlackContinuation(conversationId: string,
  * lock that is rescheduled still returns true because runnable work remains
  * durable.
  */
-export declare function continueSlackAgentRunWithLockRetry(payload: AgentContinueRequest, options: AgentContinueRunnerOptions): Promise<boolean>;
+export declare function continueSlackAgentRunWithLockRetry(payload: AgentContinueRequest, options: AgentContinueRunnerOptions, runOptions?: AgentContinueRunOptions): Promise<boolean>;

package/dist/chat/runtime/slack-runtime.d.ts

@@ -21,13 +21,12 @@ export interface AssistantLifecycleEvent {
     userId?: string;
 }
 export interface SteeringCandidateMessage {
-    activeRequest: boolean;
     inboundMessageId: string;
     message: Message;
 }
 export interface ReplyHooks {
     beforeFirstResponsePost?: () => Promise<void>;
-    drainSteeringMessages?: (accept: (messages: SteeringCandidateMessage[]) => Promise<readonly string[] | void>) => Promise<void>;
+    drainSteeringMessages?: (accept: (messages: SteeringCandidateMessage[]) => Promise<readonly string[]>) => Promise<void>;
     messageContext?: MessageContext;
     ack?: () => Promise<void>;
     onToolInvocation?: (invocation: TurnToolInvocation) => void;

package/dist/chat/runtime/thread-state.d.ts

@@ -2,19 +2,15 @@ import type { Thread } from "chat";
 import type { ChannelConfigurationService } from "@/chat/configuration/types";
 import type { ThreadConversationState } from "@/chat/state/conversation";
 import { type ThreadArtifactsState } from "@/chat/state/artifacts";
+import type { SandboxRef } from "@/chat/sandbox/ref";
 export interface ThreadStatePatch {
     artifacts?: ThreadArtifactsState;
     conversation?: ThreadConversationState;
-    sandboxId?: string;
-    sandboxDependencyProfileHash?: string;
-}
-export interface PersistedSandboxState {
-    sandboxDependencyProfileHash?: string;
-    sandboxId?: string;
+    sandboxRef?: SandboxRef | null;
 }
 export declare function mergeArtifactsState(artifacts: ThreadArtifactsState, patch: Partial<ThreadArtifactsState> | undefined): ThreadArtifactsState;
 /** Extract persisted sandbox metadata from thread state payload. */
-export declare function getPersistedSandboxState(state: Record<string, unknown>): PersistedSandboxState;
+export declare function getPersistedSandboxState(state: Record<string, unknown>): SandboxRef | undefined;
 /** Persist a thread-state patch through the Chat SDK thread interface. */
 export declare function persistThreadState(thread: Thread, patch: ThreadStatePatch): Promise<void>;
 /** Persist only the Redis-backed runtime scratch in a thread-state patch. */

package/dist/chat/runtime/turn-preparation.d.ts

@@ -1,4 +1,5 @@
 import type { ThreadConversationState } from "@/chat/state/conversation";
+import type { SandboxRef } from "@/chat/sandbox/ref";
 import { type ThreadArtifactsState } from "@/chat/state/artifacts";
 import type { ChannelConfigurationService } from "@/chat/configuration/types";
 import type { PrepareTurnStateInput, TurnContext } from "@/chat/runtime/turn-input";
@@ -8,8 +9,7 @@ export interface PreparedTurnState {
     channelConfiguration?: ChannelConfigurationService;
     conversation: ThreadConversationState;
     conversationContext?: string;
-    sandboxId?: string;
-    sandboxDependencyProfileHash?: string;
+    sandboxRef?: SandboxRef;
     userMessageAlreadyReplied?: boolean;
     userMessageId?: string;
 }

package/dist/chat/sandbox/command-result.d.ts

@@ -0,0 +1,91 @@
+import type { SandboxEgressAuthRequiredSignal, SandboxEgressPermissionDeniedSignal } from "@/chat/sandbox/egress/session";
+export interface SandboxCommandOutcome {
+    ok: boolean;
+    command: string;
+    cwd: string;
+    exit_code: number;
+    signal: null;
+    timed_out: boolean;
+    aborted?: boolean;
+    stdout: string;
+    stderr: string;
+    stdout_truncated: boolean;
+    stderr_truncated: boolean;
+    auth_required?: SandboxEgressAuthRequiredSignal;
+    permission_denied?: SandboxEgressPermissionDeniedSignal;
+}
+/** Format one shell command outcome as Junior's structured tool result. */
+export declare function formatSandboxCommandResult(params: SandboxCommandOutcome): import("@/chat/tool-support/structured-result").JuniorTextToolResultEnvelope<{
+    permission_denied?: {
+        grant: {
+            access: "read" | "write";
+            name: string;
+            leaseScope?: string | undefined;
+            reason?: string | undefined;
+            requirements?: string[] | undefined;
+        };
+        message: string;
+        provider: string;
+        source: "upstream";
+        status: number;
+        upstreamHost: string;
+        upstreamPath: string;
+        createdAtMs: number;
+        account?: {
+            id: string;
+            label?: string | undefined;
+            url?: string | undefined;
+        } | undefined;
+        acceptedPermissions?: string | undefined;
+        sso?: string | undefined;
+    } | undefined;
+    auth_required?: {
+        grant: {
+            access: "read" | "write";
+            name: string;
+            leaseScope?: string | undefined;
+            reason?: string | undefined;
+            requirements?: string[] | undefined;
+        };
+        kind: "unavailable" | "auth_required";
+        provider: string;
+        createdAtMs: number;
+        authorization?: {
+            provider: string;
+            type: "oauth";
+            scope?: string | undefined;
+        } | undefined;
+        message?: string | undefined;
+    } | undefined;
+    command: string;
+    cwd: string;
+    exit_code: number;
+    signal: null;
+    timed_out: boolean;
+    aborted: boolean;
+    stdout: string;
+    stderr: string;
+    stdout_truncated: boolean;
+    stderr_truncated: boolean;
+    error?: {
+        kind: string;
+        message: string;
+        retryable: boolean;
+    } | undefined;
+    ok: boolean;
+    status: "error" | "success";
+    target: string;
+    data: {
+        command: string;
+        cwd: string;
+        exit_code: number;
+        signal: null;
+        timed_out: boolean;
+        aborted: boolean;
+        stdout: string;
+        stderr: string;
+        stdout_truncated: boolean;
+        stderr_truncated: boolean;
+    };
+    truncated: boolean;
+}>;

package/dist/chat/sandbox/errors.d.ts

@@ -1,7 +1,9 @@
 /** Detect sandbox filesystem operations that can safely ignore existing directories. */
 export declare function isAlreadyExistsError(error: unknown): boolean;
-/** Detect when a cached sandbox can no longer be reused and must be recreated. */
+/** Detect when the current sandbox session is unavailable and must be reacquired. */
 export declare function isSandboxUnavailableError(error: unknown): boolean;
+/** Detect a durable sandbox reference that can no longer be restored. */
+export declare function isSandboxMissingError(error: unknown): boolean;
 /** Detect transient snapshot boot races so sandbox creation can retry. */
 export declare function isSnapshottingError(error: unknown): boolean;
 /** Detect interrupted command streams where no reliable exit status is available. */

package/dist/chat/sandbox/ref.d.ts

@@ -0,0 +1,5 @@
+/** Durable opaque handle used to reopen a conversation's sandbox. */
+export interface SandboxRef {
+    id: string;
+    profileHash?: string;
+}

package/dist/chat/sandbox/sandbox.d.ts

@@ -1,60 +1,33 @@
 import { type LogContext } from "@/chat/logging";
-import { type SandboxEgressAuthRequiredSignal, type SandboxEgressPermissionDeniedSignal } from "@/chat/sandbox/egress/session";
 import type { SandboxEgressTracePropagationConfig } from "@/chat/sandbox/egress/tracing";
 import type { CredentialContext } from "@/chat/credentials/context";
-import type { PluginHookRunner } from "@/chat/plugins/agent-hooks";
-import type { SandboxInstance } from "@/chat/sandbox/workspace";
+import type { SandboxRef } from "@/chat/sandbox/ref";
+import type { SandboxWorkspace } from "@/chat/sandbox/workspace";
 import type { SkillMetadata } from "@/chat/skills";
-interface SandboxExecutionInput {
+export interface SandboxToolCall {
     toolName: string;
     input: unknown;
     signal?: AbortSignal;
 }
-export interface SandboxExecutionEnvelope<T = unknown> {
-    result: T;
+export interface SandboxTools {
+    supports(toolName: string): boolean;
+    execute(params: SandboxToolCall): Promise<unknown>;
 }
-export interface BashCustomCommandResult {
-    ok: boolean;
-    command: string;
-    cwd: string;
-    exit_code: number;
-    signal: null;
-    timed_out: boolean;
-    aborted?: boolean;
-    stdout: string;
-    stderr: string;
-    stdout_truncated: boolean;
-    stderr_truncated: boolean;
-    auth_required?: SandboxEgressAuthRequiredSignal;
-    permission_denied?: SandboxEgressPermissionDeniedSignal;
+export interface SandboxAccess {
+    readonly tools: SandboxTools;
+    readonly workspace: SandboxWorkspace;
+    sandboxRef(): SandboxRef | undefined;
 }
-export interface SandboxAcquiredState {
-    sandboxId: string;
-    sandboxDependencyProfileHash?: string;
-}
-export interface SandboxExecutor {
-    configureSkills(skills: SkillMetadata[]): void;
-    configureReferenceFiles(files: string[]): void;
-    getSandboxId(): string | undefined;
-    getDependencyProfileHash(): string | undefined;
-    canExecute(toolName: string): boolean;
-    createSandbox(): Promise<SandboxInstance>;
-    execute<T>(params: SandboxExecutionInput): Promise<SandboxExecutionEnvelope<T>>;
-    dispose(): Promise<void>;
-}
-/** Create one sandbox-backed tool executor facade for the current turn. */
-export declare function createSandboxExecutor(options?: {
-    sandboxId?: string;
-    sandboxDependencyProfileHash?: string;
+export interface SandboxOptions {
+    sandboxRef?: SandboxRef;
+    skills: SkillMetadata[];
+    referenceFiles: string[];
     timeoutMs?: number;
     traceContext?: LogContext;
     tracePropagation?: SandboxEgressTracePropagationConfig;
     credentialEgress?: CredentialContext;
-    agentHooks?: PluginHookRunner;
-    onSandboxAcquired?: (sandbox: SandboxAcquiredState) => void | Promise<void>;
-    runBashCustomCommand?: (command: string) => Promise<{
-        handled: boolean;
-        result?: BashCustomCommandResult;
-    }>;
-}): SandboxExecutor;
-export {};
+    prepare?: (workspace: SandboxWorkspace) => void | Promise<void>;
+    onSandboxRefChanged?: (sandboxRef: SandboxRef) => void | Promise<void>;
+}
+/** Create lazy run-scoped access to a conversation's durable sandbox. */
+export declare function createSandbox(options: SandboxOptions): SandboxAccess;

package/dist/chat/sandbox/session.d.ts

@@ -1,8 +1,10 @@
 import { type NetworkPolicy } from "@vercel/sandbox";
 import { type LogContext, type TracePropagationHeaders } from "@/chat/logging";
-import { type SandboxFileSystem, type SandboxInstance } from "@/chat/sandbox/workspace";
+import { type SandboxFileSystem, type SandboxSession } from "@/chat/sandbox/workspace";
 import type { SkillMetadata } from "@/chat/skills";
+import type { SandboxRef } from "@/chat/sandbox/ref";
 interface SandboxToolExecutors {
+    sessionId: string;
     bash: (input: {
         command: string;
         env?: Record<string, string>;
@@ -30,29 +32,23 @@ interface SandboxToolExecutors {
     }>;
     fs: SandboxFileSystem;
 }
-interface SandboxSessionManager {
-    configureSkills(skills: SkillMetadata[]): void;
-    configureReferenceFiles(files: string[]): void;
-    getSandboxId(): string | undefined;
-    getSandboxEgressId(): string | undefined;
-    getDependencyProfileHash(): string | undefined;
-    createSandbox(): Promise<SandboxInstance>;
-    ensureToolExecutors(): Promise<SandboxToolExecutors>;
+interface SandboxRuntime {
+    sandboxRef(): SandboxRef | undefined;
+    acquire(): Promise<SandboxSession>;
+    tools(): Promise<SandboxToolExecutors>;
     refreshNetworkPolicy(traceHeaders?: TracePropagationHeaders): Promise<void>;
-    dispose(): Promise<void>;
 }
-/** Manage sandbox lifecycle, sync, keepalive, and tool executor caching for one executor instance. */
-export declare function createSandboxSessionManager(options?: {
-    sandboxId?: string;
-    sandboxDependencyProfileHash?: string;
+interface SandboxRuntimeOptions {
+    sandboxRef?: SandboxRef;
+    skills: SkillMetadata[];
+    referenceFiles: string[];
     timeoutMs?: number;
     traceContext?: LogContext;
     commandEnv?: () => Promise<Record<string, string>>;
     createNetworkPolicy?: (egressId: string, traceHeaders?: TracePropagationHeaders) => NetworkPolicy | undefined;
-    onSandboxPrepare?: (sandbox: SandboxInstance) => void | Promise<void>;
-    onSandboxAcquired?: (sandbox: {
-        sandboxId: string;
-        sandboxDependencyProfileHash?: string;
-    }) => void | Promise<void>;
-}): SandboxSessionManager;
+    onSandboxPrepare?: (sandbox: SandboxSession) => void | Promise<void>;
+    onSandboxRefChanged?: (sandboxRef: SandboxRef) => void | Promise<void>;
+}
+/** Own sandbox acquisition, preparation, and session-scoped tool caching. */
+export declare function createSandboxRuntime(options: SandboxRuntimeOptions): SandboxRuntime;
 export {};

package/dist/chat/sandbox/skill-sync.d.ts

@@ -1,4 +1,4 @@
-import type { SandboxInstance } from "@/chat/sandbox/workspace";
+import type { SandboxSession } from "@/chat/sandbox/workspace";
 import type { SkillMetadata } from "@/chat/skills";
 /** Resolve a virtual sandbox skill path back to the host filesystem when no sandbox exists yet. */
 export declare function resolveHostSkillPath(availableSkills: SkillMetadata[], sandboxPath: string): string | null;
@@ -8,7 +8,7 @@ export declare function resolveHostDataPath(referenceFiles: string[], sandboxPat
 export declare function isHostFileMissingError(error: unknown): boolean;
 /** Copy the current skill set and reference files into a sandbox. */
 export declare function syncSkillsToSandbox(params: {
-    sandbox: SandboxInstance;
+    sandbox: SandboxSession;
     skills: SkillMetadata[];
     referenceFiles?: string[];
     withSpan: <T>(name: string, op: string, attributes: Record<string, unknown>, callback: () => Promise<T>) => Promise<T>;

package/dist/chat/sandbox/workspace.d.ts

@@ -1,8 +1,8 @@
-import type { NetworkPolicy, Sandbox as VercelSandbox } from "@vercel/sandbox";
+import { type NetworkPolicy, type Sandbox as VercelSandbox } from "@vercel/sandbox";
 export interface SandboxCommandResult {
     exitCode: number;
-    stderr(): Promise<string>;
-    stdout(): Promise<string>;
+    stderr: string;
+    stdout: string;
 }
 export interface SandboxCommandInput {
     args?: string[];
@@ -31,10 +31,15 @@ export interface SandboxWorkspace {
         path: string;
     }): Promise<Buffer | null | undefined>;
     runCommand(input: SandboxCommandInput): Promise<SandboxCommandResult>;
+    writeFiles(files: Array<{
+        content: string | Uint8Array;
+        mode?: number;
+        path: string;
+    }>): Promise<void>;
 }
-export interface SandboxInstance extends SandboxWorkspace {
+export interface SandboxSession extends SandboxWorkspace {
     readonly sandboxId: string;
-    readonly sandboxEgressId: string;
+    readonly sessionId: string;
     readonly fs: SandboxFileSystem;
     extendTimeout(duration: number): Promise<void>;
     mkDir(path: string): Promise<void>;
@@ -45,11 +50,8 @@ export interface SandboxInstance extends SandboxWorkspace {
     update(params: {
         networkPolicy?: NetworkPolicy;
     }): Promise<void>;
-    writeFiles(files: Array<{
-        content: string | Uint8Array;
-        mode?: number;
-        path: string;
-    }>): Promise<void>;
 }
-/** Adapt the Vercel SDK object once so the rest of Junior sees one sandbox contract. */
-export declare function createSandboxInstance(sandbox: VercelSandbox): SandboxInstance;
+/** Pin Junior's sandbox contract to one Vercel session without SDK replay. */
+export declare function createSandboxSession(sandbox: VercelSandbox, options?: {
+    onUnavailable?: (sessionId: string) => void;
+}): SandboxSession;