@sentry/junior 0.80.1 → 0.82.0

package/dist/chat/agent-dispatch/runner.d.ts

@@ -1,5 +1,5 @@
 import { generateAssistantReply as generateAssistantReplyImpl } from "@/chat/respond";
-import type { SandboxEgressTracePropagationConfig } from "@/chat/sandbox/egress-tracing";
+import type { SandboxEgressTracePropagationConfig } from "@/chat/sandbox/egress/tracing";
 import { scheduleSessionCompletedPluginTasks } from "@/chat/plugins/task-runner";
 import { scheduleDispatchCallback } from "./signing";
 import type { DispatchCallback } from "./types";

package/dist/chat/app/services.d.ts

@@ -1,5 +1,5 @@
 import { generateAssistantReply as generateAssistantReplyImpl } from "@/chat/respond";
-import type { SandboxEgressTracePropagationConfig } from "@/chat/sandbox/egress-tracing";
+import type { SandboxEgressTracePropagationConfig } from "@/chat/sandbox/egress/tracing";
 import { type ConversationMemoryDeps, type ConversationMemoryService } from "@/chat/services/conversation-memory";
 import { type ContextCompactor, type ContextCompactorDeps } from "@/chat/services/context-compaction";
 import { type SubscribedReplyPolicy, type SubscribedReplyPolicyDeps } from "@/chat/services/subscribed-reply-policy";

package/dist/chat/egress/credentialed.d.ts

@@ -0,0 +1,57 @@
+import { type SandboxEgressGrantSelection } from "@/chat/sandbox/egress/credentials";
+import { type SandboxEgressCredentialContext, type SandboxEgressCredentialLease } from "@/chat/sandbox/egress/session";
+import { type SandboxEgressTracePropagationConfig } from "@/chat/sandbox/egress/tracing";
+/**
+ * Intercepts the already-authenticated provider request before live forwarding.
+ *
+ * Tests use this to inspect the exact upstream request after grant selection
+ * and credential header injection, without weakening the proxy verification
+ * path that runs before this hook is reached.
+ */
+export type CredentialedEgressHttpInterceptor = (input: {
+    provider: string;
+    request: Request;
+    upstreamUrl: URL;
+}) => Promise<Response | undefined>;
+/** Runtime dependencies for the credentialed provider forwarding step. */
+export interface CredentialedEgressDeps {
+    clearCredentialLease?: (provider: string, grantName: string, credentialContext: SandboxEgressCredentialContext) => Promise<void>;
+    fetch?: typeof fetch;
+    issueCredentialLease?: (provider: string, selection: SandboxEgressGrantSelection, credentialContext: SandboxEgressCredentialContext) => Promise<SandboxEgressCredentialLease>;
+    interceptHttp?: CredentialedEgressHttpInterceptor;
+    recordAuthRequired?: (input: {
+        authorization?: SandboxEgressCredentialLease["authorization"];
+        credentialContext: SandboxEgressCredentialContext;
+        grant: SandboxEgressCredentialLease["grant"];
+        kind?: "auth_required" | "unavailable";
+        message: string;
+        provider: string;
+    }) => Promise<void>;
+    recordPermissionDenied?: (input: {
+        credentialContext: SandboxEgressCredentialContext;
+        lease: SandboxEgressCredentialLease;
+        message: string;
+        provider: string;
+        upstream: Response;
+        upstreamUrl: URL;
+    }) => Promise<void>;
+    tracePropagation?: SandboxEgressTracePropagationConfig;
+}
+/**
+ * Forward one verified sandbox egress request with host-managed credentials.
+ *
+ * The caller must already have authenticated the sandbox VM, checked the signed
+ * credential context, and resolved the provider for `upstreamUrl`. This function
+ * then selects the read/write grant, issues or reuses a short-lived credential
+ * lease, applies its header transforms, and maps provider auth failures into
+ * command-level signals instead of throwing raw upstream details at the agent.
+ */
+export declare function executeCredentialedEgressRequest(input: {
+    activeEgressId: string;
+    credentialContext: SandboxEgressCredentialContext;
+    deps: CredentialedEgressDeps;
+    operation?: string;
+    provider: string;
+    request: Request;
+    upstreamUrl: URL;
+}): Promise<Response>;

package/dist/chat/egress/plugin.d.ts

@@ -0,0 +1,24 @@
+import type { PluginAuthorization, PluginEgress } from "@sentry/junior-plugin-api";
+import type { CredentialContext } from "@/chat/credentials/context";
+interface PluginEgressAuth {
+    handleAuthRequired(input: {
+        authorization?: PluginAuthorization;
+        grant: {
+            access: "read" | "write";
+            name: string;
+            reason?: string;
+            requirements?: string[];
+        };
+        kind: "auth_required" | "unavailable";
+        message: string;
+        provider: string;
+    }): Promise<void>;
+}
+interface PluginEgressDeps {
+    credentialContext?: CredentialContext;
+    fetch?: typeof fetch;
+    pluginAuth: PluginEgressAuth;
+}
+/** Create host-owned provider egress for plugin runtime tools. */
+export declare function createPluginEgress(deps: PluginEgressDeps): PluginEgress;
+export {};

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

@@ -3,6 +3,7 @@ import type { StoredTokens, UserTokenStore } from "@/chat/credentials/user-token
 export interface EgressGrantInput {
     bodyText?: string;
     method: string;
+    operation?: string;
     provider: string;
     upstreamUrl: URL;
 }
@@ -11,6 +12,7 @@ export declare function selectPluginGrant(input: EgressGrantInput): Promise<Plug
 export interface EgressResponseInput {
     grant: PluginGrant;
     method: string;
+    operation?: string;
     provider: string;
     response: {
         headers: Headers;

package/dist/chat/respond.d.ts

@@ -5,7 +5,7 @@ import type { ConversationPendingAuthState } from "@/chat/state/conversation";
 import type { ImageGenerateToolDeps, WebFetchToolDeps, WebSearchToolDeps } from "@/chat/tools/types";
 import type { PiMessage } from "@/chat/pi/messages";
 import { type SandboxAcquiredState } from "@/chat/sandbox/sandbox";
-import type { SandboxEgressTracePropagationConfig } from "@/chat/sandbox/egress-tracing";
+import type { SandboxEgressTracePropagationConfig } from "@/chat/sandbox/egress/tracing";
 import type { AssistantStatusSpec } from "@/chat/slack/assistant-thread/status";
 import type { SlackConversationContext } from "@/chat/slack/conversation-context";
 import { type ToolExecutionReport } from "@/chat/tools/agent-tools";

package/dist/chat/sandbox/{egress-credentials.d.ts → egress/credentials.d.ts}

@@ -1,5 +1,6 @@
 import type { PluginAuthorization, PluginGrant } from "@sentry/junior-plugin-api";
-import { type SandboxEgressCredentialContext, type SandboxEgressCredentialLease } from "@/chat/sandbox/egress-session";
+import { type SandboxEgressCredentialContext, type SandboxEgressCredentialLease } from "@/chat/sandbox/egress/session";
+/** Describes whether grant selection came from plugin hooks or the broker default. */
 export type SandboxEgressGrantSelection = {
     grant: PluginGrant;
     source: "plugin";
@@ -8,7 +9,12 @@ export type SandboxEgressGrantSelection = {
     source: "broker";
 };
 export type SandboxEgressCredentialErrorKind = "auth_required" | "unavailable";
-/** Signals that egress selected a grant but could not issue credential headers. */
+/**
+ * Signals that egress selected a grant but could not issue credential headers.
+ *
+ * Callers convert this into command-level auth-required state so the agent can
+ * request authorization without exposing provider-specific lease internals.
+ */
 export declare class SandboxEgressCredentialError extends Error {
     readonly authorization?: PluginAuthorization;
     readonly grant: PluginGrant;
@@ -22,16 +28,33 @@ export declare class SandboxEgressCredentialError extends Error {
         provider: string;
     });
 }
-/** Select the plugin-defined or default grant needed for one outbound request. */
+/**
+ * Select the grant needed for one outbound request.
+ *
+ * GitHub GraphQL and other plugin-owned APIs may need body-aware grant choices;
+ * providers without hooks use a simple read/write default based on HTTP method.
+ */
 export declare function selectSandboxEgressGrant(input: {
     bodyText?: string;
     method: string;
+    operation?: string;
     provider: string;
     upstreamUrl: URL;
 }): Promise<SandboxEgressGrantSelection>;
-/** Resolve the authorization flow attached to a broker-selected egress grant. */
+/**
+ * Resolve the authorization flow attached to a broker-selected egress grant.
+ *
+ * Plugin-selected grants can return their own authorization metadata when
+ * issuing credentials; broker defaults use the provider OAuth config.
+ */
 export declare function authorizationForSandboxEgressGrant(provider: string, selection: SandboxEgressGrantSelection): PluginAuthorization | undefined;
-/** Return a cached or newly issued credential lease for a selected grant. */
+/**
+ * Return cached or newly issued credential header transforms for a selected grant.
+ *
+ * Leases are cached per actor/context/grant, validated against provider-owned
+ * domains, and reused only while both the provider lease and sandbox context are
+ * still valid.
+ */
 export declare function sandboxEgressCredentialLease(provider: string, selection: SandboxEgressGrantSelection, context: SandboxEgressCredentialContext): Promise<SandboxEgressCredentialLease>;
 /** Return whether a credential lease can modify requests to the target host. */
 export declare function hasSandboxEgressLeaseTransformForHost(lease: SandboxEgressCredentialLease, host: string): boolean;

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

@@ -0,0 +1,32 @@
+import type { NetworkPolicy } from "@vercel/sandbox";
+import type { TracePropagationHeaders } from "@/chat/logging";
+import { type SandboxEgressTracePropagationConfig } from "@/chat/sandbox/egress/tracing";
+/** Return whether an outbound host is covered by a provider domain rule. */
+export declare function matchesSandboxEgressDomain(host: string, domain: string): boolean;
+/**
+ * Resolve the plugin provider responsible for an outbound sandbox host.
+ *
+ * Only plugin-declared provider domains are eligible for credentialed sandbox
+ * egress. Hosts without a matching provider are blocked by the proxy even if a
+ * malformed or stale network policy tried to forward them.
+ */
+export declare function resolveSandboxEgressProviderForHost(host: string): string | undefined;
+/**
+ * Build the policy that forwards provider domains through the egress proxy.
+ *
+ * The signed credential token is embedded in the forward URL so the proxy can
+ * bind each forwarded request back to the actor and sandbox VM that created the
+ * command. The sandbox receives placeholder env vars, not provider credentials.
+ */
+export declare function buildSandboxEgressNetworkPolicy(input?: {
+    credentialToken?: string;
+    traceConfig?: SandboxEgressTracePropagationConfig;
+    traceHeaders?: TracePropagationHeaders;
+}): NetworkPolicy;
+/**
+ * Resolve non-secret command environment values for registered sandbox providers.
+ *
+ * Credential env vars are placeholders that tell tools which auth variable name
+ * exists; real credential headers are issued lazily by host egress.
+ */
+export declare function resolveSandboxCommandEnvironment(): Promise<Record<string, string>>;

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

@@ -0,0 +1,35 @@
+import { type CredentialedEgressHttpInterceptor } from "@/chat/egress/credentialed";
+import { type SandboxEgressTracePropagationConfig } from "@/chat/sandbox/egress/tracing";
+import type { JWTPayload } from "jose";
+/**
+ * Intercepts a verified sandbox HTTP request before live provider forwarding.
+ *
+ * The hook runs after OIDC, forwarded URL validation, provider ownership, and
+ * credential-context checks have succeeded.
+ */
+export type SandboxEgressHttpInterceptor = CredentialedEgressHttpInterceptor;
+/** Runtime dependencies for the sandbox egress proxy boundary. */
+interface ProxyDeps {
+    fetch?: typeof fetch;
+    interceptHttp?: SandboxEgressHttpInterceptor;
+    tracePropagation?: SandboxEgressTracePropagationConfig;
+    verifyOidc?: (token: string) => Promise<JWTPayload>;
+}
+/**
+ * Return whether a request carries the forwarding headers expected from Vercel.
+ *
+ * This is only a cheap classifier for routing into the proxy handler. Real
+ * authentication happens in `proxySandboxEgressRequest` by verifying the OIDC
+ * token and signed Junior credential context.
+ */
+export declare function isSandboxEgressForwardedRequest(request: Request): boolean;
+/**
+ * Handle one forwarded sandbox egress request.
+ *
+ * This is the public proxy boundary: it rejects unauthenticated VM requests,
+ * rejects forwarded URLs outside plugin-owned provider domains, rejects signed
+ * credential contexts that do not match the active VM id, and only then asks
+ * `execute.ts` to issue credentials and contact the upstream provider.
+ */
+export declare function proxySandboxEgressRequest(request: Request, deps?: ProxyDeps): Promise<Response>;
+export {};

package/dist/chat/sandbox/{egress-session.d.ts → egress/session.d.ts}

@@ -1,30 +1,60 @@
 import type { CredentialContext } from "@/chat/credentials/context";
-import { type SandboxEgressAuthRequiredSignal, type SandboxEgressCredentialContext, type SandboxEgressCredentialLease, type SandboxEgressPermissionDeniedSignal } from "@/chat/sandbox/egress-schemas";
+import { type SandboxEgressAuthRequiredSignal, type SandboxEgressCredentialContext, type SandboxEgressCredentialLease, type SandboxEgressPermissionDeniedSignal } from "@/chat/sandbox/egress/schemas";
 export declare const SANDBOX_EGRESS_PROXY_PATH = "/api/internal/sandbox-egress";
 export type { SandboxEgressAuthRequiredSignal, SandboxEgressCredentialContext, SandboxEgressCredentialLease, SandboxEgressPermissionDeniedSignal, };
-/** Create a signed actor/sandbox context token for lazy sandbox egress auth. */
+/**
+ * Create the signed Junior credential context embedded in the proxy URL.
+ *
+ * The token binds requester credentials to a specific sandbox egress id and a
+ * short expiry. Vercel OIDC proves which VM sent a request; this token proves
+ * which Junior actor and credential context that VM is allowed to use.
+ */
 export declare function createSandboxEgressCredentialToken(input: {
     credentials: CredentialContext;
     egressId: string;
     ttlMs?: number;
 }): string;
-/** Verify a signed actor/sandbox context token from the proxy URL. */
+/**
+ * Verify the signed Junior credential context from the proxy URL.
+ *
+ * Returning `undefined` means the token is missing, expired, malformed, or not
+ * signed with the current `JUNIOR_SECRET`.
+ */
 export declare function parseSandboxEgressCredentialToken(token: string | undefined): SandboxEgressCredentialContext | undefined;
-/** Cache a short-lived credential lease for one actor/sandbox context and grant. */
+/**
+ * Cache credential header transforms for one actor, VM, context token, and grant.
+ *
+ * The cache TTL is capped by both the provider lease expiry and the signed
+ * context expiry so a stale sandbox URL cannot keep using old credentials.
+ */
 export declare function setSandboxEgressCredentialLease(context: SandboxEgressCredentialContext, lease: SandboxEgressCredentialLease): Promise<void>;
-/** Load a cached egress credential lease for one actor/sandbox context and grant. */
+/**
+ * Load cached credential header transforms for the exact actor/context/grant.
+ */
 export declare function getSandboxEgressCredentialLease(provider: string, grantName: string, context: SandboxEgressCredentialContext): Promise<SandboxEgressCredentialLease | undefined>;
-/** Clear a cached egress credential lease after the provider rejects its headers. */
+/** Clear a cached lease after the upstream provider rejects its auth headers. */
 export declare function clearSandboxEgressCredentialLease(provider: string, grantName: string, context: SandboxEgressCredentialContext): Promise<void>;
-/** Record that host-side sandbox egress returned an auth-required response. */
+/**
+ * Record that credential issuance needs user authorization for this command.
+ *
+ * The command runner consumes this after the sandbox tool finishes so the agent
+ * can present a normal authorization-required response instead of a raw proxy
+ * failure.
+ */
 export declare function setSandboxEgressAuthRequiredSignal(context: SandboxEgressCredentialContext, signal: Omit<SandboxEgressAuthRequiredSignal, "createdAtMs" | "kind"> & {
     kind?: SandboxEgressAuthRequiredSignal["kind"];
 }): Promise<void>;
-/** Record that host-side sandbox egress saw an upstream permission denial. */
+/**
+ * Record that the provider rejected an issued credential with permission denial.
+ */
 export declare function setSandboxEgressPermissionDeniedSignal(context: SandboxEgressCredentialContext, signal: Omit<SandboxEgressPermissionDeniedSignal, "createdAtMs">): Promise<void>;
-/** Remove any pending host-side sandbox egress signals for a command. */
+/** Remove pending auth/permission signals before or after a sandbox command. */
 export declare function clearSandboxEgressSignals(egressId: string | undefined): Promise<void>;
-/** Consume the host-side sandbox egress auth signal produced during a command. */
+/**
+ * Consume the auth signal produced during a sandbox command, preferring writes.
+ */
 export declare function consumeSandboxEgressAuthRequiredSignal(egressId: string | undefined): Promise<SandboxEgressAuthRequiredSignal | undefined>;
-/** Consume the host-side sandbox egress permission signal produced during a command. */
+/**
+ * Consume the permission signal produced during a sandbox command, preferring writes.
+ */
 export declare function consumeSandboxEgressPermissionDeniedSignal(egressId: string | undefined): Promise<SandboxEgressPermissionDeniedSignal | undefined>;

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

@@ -1,6 +1,6 @@
 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 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";

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

@@ -1,5 +1,5 @@
 import type { FileUpload } from "chat";
-import type { Destination, LocalDestination, LocalSource, SlackDestination, SlackSource, Source } from "@sentry/junior-plugin-api";
+import type { Destination, LocalDestination, LocalSource, PluginEgress, SlackDestination, SlackSource, Source } from "@sentry/junior-plugin-api";
 import type { McpToolManager } from "@/chat/mcp/tool-manager";
 import type { SandboxWorkspace } from "@/chat/sandbox/workspace";
 import type { AgentTurnSurface } from "@/chat/state/turn-session";
@@ -54,6 +54,7 @@ interface BaseToolRuntimeContext {
     userText?: string;
     artifactState?: ThreadArtifactsState;
     configuration?: Record<string, unknown>;
+    egress: PluginEgress;
     mcpToolManager?: McpToolManager;
     sandbox: SandboxWorkspace;
 }