@sentry/junior 0.109.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-D22W6QEJ.js

@@ -0,0 +1,16 @@
+import {
+  pluginCatalogRuntime
+} from "./chunk-WSRBFHPX.js";
+import "./chunk-XQAYFRWT.js";
+import "./chunk-C4MZ3GP5.js";
+import "./chunk-J7APPQIJ.js";
+import "./chunk-42WRQLJ6.js";
+import "./chunk-6GWA276C.js";
+import "./chunk-B3IT5END.js";
+import "./chunk-3V7OFJZC.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/resume.d.ts

@@ -15,6 +15,7 @@ import type { AgentRunOutcome } from "@/chat/runtime/agent-run-outcome";
 import type { AgentTurnSurface } from "@/chat/state/turn-session";
 import type { Actor } from "@/chat/actor";
 import { loadTurnSessionRecord, persistRunningSessionRecord } from "@/chat/services/turn-session-record";
+import { type AuthorizationPauseError } from "@/chat/services/auth-pause";
 import { type AgentTurnUsage } from "@/chat/usage";
 import { type AgentRunDurability } from "@/chat/agent/request";
 type LoadedSessionRecordState = Awaited<ReturnType<typeof loadTurnSessionRecord>>;
@@ -36,15 +37,14 @@ interface ResumeStateArgs {
     startedAtMs: number;
     surface: AgentTurnSurface;
 }
-interface ExpectedEndingTranslation {
-    outcome?: AgentRunOutcome;
-}
+type AuthPauseOutcome = Extract<AgentRunOutcome, {
+    status: "awaiting_auth";
+}>;
 /** Create the run's resume state: checkpoints, snapshots, and ending translation. */
 export declare function createResumeState(args: ResumeStateArgs): {
     readonly inputCommitted: boolean;
     readonly beforeMessageCount: number;
     readonly timedOut: boolean;
-    readonly cooperativeYieldError: CooperativeTurnYieldError | undefined;
     setTurnStartMessageIndex(index: number | undefined): void;
     setBeforeMessageCount(count: number): void;
     /** Adopt an already committed epoch replacement as every resume baseline. */
@@ -55,16 +55,15 @@ export declare function createResumeState(args: ResumeStateArgs): {
     commitInput(): Promise<void>;
     persistSafeBoundary(messages: PiMessage[], trailingMessageProvenance?: ConversationMessageProvenance[]): Promise<boolean>;
     requireDurableInputCheckpoint(messages: PiMessage[], trailingMessageProvenance?: ConversationMessageProvenance[]): Promise<boolean>;
-    yieldAtSafeBoundaryIfDue(currentMessages: PiMessage[]): void;
-    /**
-     * Persist the continuation for an expected run ending and translate it
-     * into an outcome; returns no outcome for genuine errors so the caller's
-     * error guards run.
-     */
-    translateExpectedEnding(args2: {
+    /** Prepare a cooperative yield at the current durable boundary. */
+    prepareYieldIfDue(currentMessages: PiMessage[]): CooperativeTurnYieldError | undefined;
+    /** Persist an auth pause; only a durable pause may return `awaiting_auth`. */
+    parkForAuth(pause: AuthorizationPauseError, currentUsage?: AgentTurnUsage): Promise<AuthPauseOutcome>;
+    /** Persist a yield, retry, or timeout as a suspended run. */
+    translateSuspension(ending: {
         currentUsage?: AgentTurnUsage;
         error: unknown;
-    }): Promise<ExpectedEndingTranslation>;
+    }): Promise<AgentRunOutcome | undefined>;
 };
 export type ResumeState = ReturnType<typeof createResumeState>;
 export {};

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/conversations/history.d.ts

@@ -25,6 +25,7 @@ export declare const historyReplacementSchema: z.ZodObject<{
         type: z.ZodLiteral<"handoff">;
         modelProfile: z.ZodString;
         modelId: z.ZodString;
+        reasoningLevel: z.ZodOptional<z.ZodString>;
         triggeringToolCallId: z.ZodOptional<z.ZodString>;
         replacementHistory: z.ZodArray<z.ZodObject<{
             message: z.ZodPipe<z.ZodObject<{
@@ -237,6 +238,7 @@ export declare const conversationEventDataSchema: z.ZodUnion<readonly [z.ZodUnio
     type: z.ZodLiteral<"handoff">;
     modelProfile: z.ZodString;
     modelId: z.ZodString;
+    reasoningLevel: z.ZodOptional<z.ZodString>;
     triggeringToolCallId: z.ZodOptional<z.ZodString>;
     replacementHistory: z.ZodArray<z.ZodObject<{
         message: z.ZodPipe<z.ZodObject<{
@@ -479,6 +481,7 @@ export declare const conversationEventSchema: z.ZodUnion<readonly [z.ZodObject<{
         type: z.ZodLiteral<"handoff">;
         modelProfile: z.ZodString;
         modelId: z.ZodString;
+        reasoningLevel: z.ZodOptional<z.ZodString>;
         triggeringToolCallId: z.ZodOptional<z.ZodString>;
         replacementHistory: z.ZodArray<z.ZodObject<{
             message: z.ZodPipe<z.ZodObject<{

package/dist/chat/conversations/sql/privacy.d.ts

@@ -1,27 +1,15 @@
 import type { JuniorSqlDatabase } from "@/db/db";
-import { juniorConversationEvents } from "@/db/schema";
 import type { JuniorDestinationVisibility } from "@/db/schema/destinations";
 /** Root conversation identity and its normalized destination visibility. */
 export interface RootConversationVisibility {
     rootConversationId: string;
     visibility: JuniorDestinationVisibility | null;
 }
-type ConversationEventPrivacySnapshot = RootConversationVisibility & {
-    events: Array<typeof juniorConversationEvents.$inferSelect>;
-};
-/**
- * Read selected event rows and their root privacy authority in one SQL snapshot.
- */
-export declare function readConversationEventPrivacySnapshot(executor: JuniorSqlDatabase, args: {
-    conversationId: string;
-    eventTypes: readonly string[];
-}): Promise<ConversationEventPrivacySnapshot | undefined>;
 /**
  * Resolve a conversation's privacy authority from its persisted root.
  *
- * Parent links are immutable after insertion. Missing, cyclic, or over-depth
- * lineage fails closed, while the root destination is locked so callers that
- * keep the transaction open receive a stable visibility decision.
+ * Missing or structurally invalid root metadata fails closed. The root
+ * destination is locked so callers that keep the transaction open receive a
+ * stable visibility decision.
  */
 export declare function resolveRootVisibility(executor: JuniorSqlDatabase, conversationId: string): Promise<RootConversationVisibility>;
-export {};

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

@@ -2,7 +2,7 @@ import { z } from "zod";
 /** Permissive schema for durable Pi SDK messages whose content shape may evolve. */
 export declare const piMessageSchema: z.ZodPipe<z.ZodObject<{
     role: z.ZodString;
-}, z.core.$loose>, z.ZodTransform<import("@earendil-works/pi-ai").AssistantMessage | import("@earendil-works/pi-ai").UserMessage | import("@earendil-works/pi-ai").ToolResultMessage<any> | import("@earendil-works/pi-agent-core").BashExecutionMessage | import("@earendil-works/pi-agent-core").CustomMessage<unknown> | import("@earendil-works/pi-agent-core").BranchSummaryMessage | import("@earendil-works/pi-agent-core").CompactionSummaryMessage, {
+}, z.core.$loose>, z.ZodTransform<import("@earendil-works/pi-ai").AssistantMessage | import("@earendil-works/pi-ai").UserMessage | import("@earendil-works/pi-ai").ToolResultMessage<any> | import("@earendil-works/pi-agent-core").CustomMessage<unknown> | import("@earendil-works/pi-agent-core").BashExecutionMessage | import("@earendil-works/pi-agent-core").BranchSummaryMessage | import("@earendil-works/pi-agent-core").CompactionSummaryMessage, {
     [x: string]: unknown;
     role: string;
 }>>;
@@ -12,7 +12,7 @@ export type PiMessage = z.output<typeof piMessageSchema>;
 export declare const piContentMessageSchema: z.ZodPipe<z.ZodObject<{
     content: z.ZodArray<z.ZodUnknown>;
     role: z.ZodString;
-}, z.core.$loose>, z.ZodTransform<import("@earendil-works/pi-ai").AssistantMessage | import("@earendil-works/pi-ai").UserMessage | import("@earendil-works/pi-ai").ToolResultMessage<any> | import("@earendil-works/pi-agent-core").BashExecutionMessage | import("@earendil-works/pi-agent-core").CustomMessage<unknown> | import("@earendil-works/pi-agent-core").BranchSummaryMessage | import("@earendil-works/pi-agent-core").CompactionSummaryMessage, {
+}, z.core.$loose>, z.ZodTransform<import("@earendil-works/pi-ai").AssistantMessage | import("@earendil-works/pi-ai").UserMessage | import("@earendil-works/pi-ai").ToolResultMessage<any> | import("@earendil-works/pi-agent-core").CustomMessage<unknown> | import("@earendil-works/pi-agent-core").BashExecutionMessage | import("@earendil-works/pi-agent-core").BranchSummaryMessage | import("@earendil-works/pi-agent-core").CompactionSummaryMessage, {
     [x: string]: unknown;
     content: unknown[];
     role: string;

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/pi/sql-model-usage.d.ts

@@ -4,7 +4,10 @@ import { type AgentTurnUsage } from "@/chat/usage";
  * Aggregate real assistant calls by provider/model in SQL. Replayed history is
  * not another call; its tokens appear in the next call's input usage.
  */
-export declare function readConversationModelUsageFromSql(executor: JuniorSqlDatabase, conversationId: string): Promise<Array<{
+export declare function readConversationModelUsageFromSql(executor: JuniorSqlDatabase, options: {
+    conversationId: string;
+    includeDescendants?: boolean;
+}): Promise<Array<{
     modelId: string;
     usage: AgentTurnUsage;
 }>>;

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