@sentry/junior-plugin-api 0.68.0 → 0.70.0

package/dist/index.d.ts

@@ -1,9 +1,40 @@
-export interface AgentPluginRequester {
-    userId?: string;
-    userName?: string;
-    fullName?: string;
-    email?: string;
-}
+import { z } from "zod";
+/** Runtime-owned provider-neutral address for routing future work or side effects. */
+export declare const destinationSchema: z.ZodObject<{
+    platform: z.ZodLiteral<"slack">;
+    teamId: z.ZodString;
+    channelId: z.ZodString;
+}, z.core.$strict>;
+/** Stable user credential subject shape accepted from plugins. */
+export declare const agentPluginCredentialSubjectSchema: z.ZodObject<{
+    type: z.ZodLiteral<"user">;
+    userId: z.ZodString;
+    allowedWhen: z.ZodLiteral<"private-direct-conversation">;
+}, z.core.$strict>;
+/** Runtime-provided requester identity visible to plugin hooks. */
+export declare const agentPluginRequesterSchema: z.ZodObject<{
+    userId: z.ZodOptional<z.ZodString>;
+    userName: z.ZodOptional<z.ZodString>;
+    fullName: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Plugin dispatch request accepted by Junior core. */
+export declare const dispatchOptionsSchema: z.ZodObject<{
+    idempotencyKey: z.ZodPipe<z.ZodString, z.ZodString>;
+    credentialSubject: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"user">;
+        userId: z.ZodString;
+        allowedWhen: z.ZodLiteral<"private-direct-conversation">;
+    }, z.core.$strict>>;
+    destination: z.ZodObject<{
+        platform: z.ZodLiteral<"slack">;
+        teamId: z.ZodString;
+        channelId: z.ZodString;
+    }, z.core.$strict>;
+    input: z.ZodPipe<z.ZodString, z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+export type AgentPluginRequester = z.output<typeof agentPluginRequesterSchema>;
 export interface AgentPluginMetadata {
     name: string;
 }
@@ -20,7 +51,7 @@ export interface AgentPluginLogger {
     info(message: string, metadata?: Record<string, unknown>): void;
     warn(message: string, metadata?: Record<string, unknown>): void;
 }
-/** Thrown when a trusted plugin tool rejects invalid model or user input. */
+/** Thrown when a plugin tool rejects invalid model or user input. */
 export declare class AgentPluginToolInputError extends Error {
     constructor(message: string, options?: {
         cause?: unknown;
@@ -90,13 +121,36 @@ export interface AgentPluginToolDefinition<TInput = unknown> {
     execute?: AgentPluginToolExecute<TInput>;
 }
 export interface ToolRegistrationHookContext extends AgentPluginContext {
+    /**
+     * Capabilities of `channelId` — the raw conversation channel exposed to
+     * this plugin. Recomputed from `channelId`, not from `destination`.
+     */
     channelCapabilities?: {
         canAddReactions: boolean;
         canCreateCanvas: boolean;
         canPostToChannel: boolean;
     };
+    /**
+     * The raw Slack channel ID for this conversation — the DM or channel where
+     * this turn is happening, without any assistant-context-source override.
+     * Use this as the stable binding key for state scoped to a Slack conversation.
+     * `channelCapabilities` describes this channel.
+     */
     channelId?: string;
+    /**
+     * Opaque Junior conversation/session identity for this turn.
+     * Interactive Slack turns use `slack:{channelId}:{threadTs}`.
+     * Scheduled/API turns use an internal id such as `agent-dispatch:{id}`.
+     * Do not parse as Slack unless the value starts with `slack:`.
+     */
+    conversationId?: string;
     credentialSubject?: AgentPluginCredentialSubject;
+    /**
+     * Runtime-owned destination suitable for future autonomous dispatch. For
+     * Slack, this is the raw conversation channel, not a thread timestamp or
+     * assistant-context source channel.
+     */
+    destination?: Destination;
     messageTs?: string;
     requester?: AgentPluginRequester;
     state: AgentPluginState;
@@ -104,22 +158,9 @@ export interface ToolRegistrationHookContext extends AgentPluginContext {
     threadTs?: string;
     userText?: string;
 }
-export interface AgentPluginCredentialSubject {
-    type: "user";
-    userId: string;
-    allowedWhen: "private-direct-conversation";
-}
-export interface DispatchOptions {
-    credentialSubject?: AgentPluginCredentialSubject;
-    destination: {
-        platform: "slack";
-        teamId: string;
-        channelId: string;
-    };
-    idempotencyKey: string;
-    input: string;
-    metadata?: Record<string, string>;
-}
+export type AgentPluginCredentialSubject = z.output<typeof agentPluginCredentialSubjectSchema>;
+export type Destination = z.output<typeof destinationSchema>;
+export type DispatchOptions = z.output<typeof dispatchOptionsSchema>;
 export interface DispatchResult {
     id: string;
     status: "created" | "already_exists";
@@ -202,9 +243,166 @@ export interface SlackConversationLink {
 export interface SlackConversationLinkHookContext extends AgentPluginContext {
     conversationId: string;
 }
+declare const agentPluginGrantAccessSchema: z.ZodUnion<readonly [z.ZodLiteral<"read">, z.ZodLiteral<"write">]>;
+/** Runtime schema for provider authorization a plugin may request. */
+export declare const agentPluginAuthorizationSchema: z.ZodObject<{
+    provider: z.ZodString;
+    scope: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"oauth">;
+}, z.core.$strict>;
+/** Runtime schema for a provider account attached to stored OAuth tokens. */
+export declare const agentPluginProviderAccountSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Runtime schema for a plugin-defined outbound credential grant. */
+export declare const agentPluginGrantSchema: z.ZodObject<{
+    access: z.ZodUnion<readonly [z.ZodLiteral<"read">, z.ZodLiteral<"write">]>;
+    name: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+    requirements: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+/** Runtime schema for plugin-issued header mutations. */
+export declare const agentPluginCredentialHeaderTransformSchema: z.ZodObject<{
+    domain: z.ZodString;
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>;
+/** Runtime schema for a short-lived plugin-issued credential lease. */
+export declare const agentPluginCredentialLeaseSchema: z.ZodObject<{
+    account: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    authorization: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        scope: z.ZodOptional<z.ZodString>;
+        type: z.ZodLiteral<"oauth">;
+    }, z.core.$strict>>;
+    expiresAt: z.ZodString;
+    headerTransforms: z.ZodArray<z.ZodObject<{
+        domain: z.ZodString;
+        headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Runtime schema for the result returned by a plugin credential hook. */
+export declare const agentPluginCredentialResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    lease: z.ZodObject<{
+        account: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+            url: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        authorization: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodString;
+            scope: z.ZodOptional<z.ZodString>;
+            type: z.ZodLiteral<"oauth">;
+        }, z.core.$strict>>;
+        expiresAt: z.ZodString;
+        headerTransforms: z.ZodArray<z.ZodObject<{
+            domain: z.ZodString;
+            headers: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    type: z.ZodLiteral<"lease">;
+}, z.core.$strict>, z.ZodObject<{
+    authorization: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        scope: z.ZodOptional<z.ZodString>;
+        type: z.ZodLiteral<"oauth">;
+    }, z.core.$strict>>;
+    message: z.ZodString;
+    type: z.ZodLiteral<"needed">;
+}, z.core.$strict>, z.ZodObject<{
+    message: z.ZodString;
+    type: z.ZodLiteral<"unavailable">;
+}, z.core.$strict>], "type">;
+export type AgentPluginGrantAccess = z.output<typeof agentPluginGrantAccessSchema>;
+/** Provider authorization Junior can start when a plugin-owned grant is missing. */
+export type AgentPluginAuthorization = z.output<typeof agentPluginAuthorizationSchema>;
+/** Interrupt sandbox egress so Junior can start provider authorization. */
+export declare class EgressAuthRequired extends Error {
+    authorization?: AgentPluginAuthorization;
+    constructor(message: string, options?: {
+        authorization?: AgentPluginAuthorization;
+        cause?: unknown;
+    });
+}
+/** Provider account identity resolved by a plugin OAuth hook. */
+export type AgentPluginProviderAccount = z.output<typeof agentPluginProviderAccountSchema>;
+/** Plugin-defined grant required before Junior can forward one outbound request. */
+export type AgentPluginGrant = z.output<typeof agentPluginGrantSchema>;
+/** Request details available while selecting the grant for sandbox egress. */
+export interface AgentPluginEgressRequest {
+    /** Capped request body text when the host exposes it for provider-specific grant classification. */
+    bodyText?: string;
+    method: string;
+    url: string;
+}
+export interface EgressHookContext extends AgentPluginContext {
+    request: AgentPluginEgressRequest;
+}
+export interface AgentPluginEgressResponse {
+    /** Snapshot of upstream response headers; mutations do not affect pass-through. */
+    headers: Headers;
+    readText(maxBytes: number): Promise<string | undefined>;
+    status: number;
+}
+export interface EgressResponseHookContext extends AgentPluginContext {
+    grant: AgentPluginGrant;
+    permissionDenied(message: string): void;
+    request: Omit<AgentPluginEgressRequest, "bodyText">;
+    response: AgentPluginEgressResponse;
+}
+/** Header mutations a plugin-issued credential lease may apply to owned domains. */
+export type AgentPluginCredentialHeaderTransform = z.output<typeof agentPluginCredentialHeaderTransformSchema>;
+/** Short-lived credential headers issued by a plugin for a selected grant. */
+export type AgentPluginCredentialLease = z.output<typeof agentPluginCredentialLeaseSchema>;
+export type AgentPluginCredentialResult = z.output<typeof agentPluginCredentialResultSchema>;
+export type AgentPluginCredentialActor = {
+    type: "system";
+    id: string;
+} | {
+    type: "user";
+    userId: string;
+};
+export interface AgentPluginResolvedCredentialUser {
+    type: "user";
+    userId: string;
+}
+export interface AgentPluginStoredTokens {
+    account?: AgentPluginProviderAccount;
+    accessToken: string;
+    expiresAt?: number;
+    refreshToken: string;
+    scope?: string;
+}
+export interface AgentPluginUserTokenSlot {
+    get(): Promise<AgentPluginStoredTokens | undefined>;
+    set(tokens: AgentPluginStoredTokens): Promise<void>;
+    userId: string;
+}
+export interface AgentPluginTokenStore {
+    credentialSubject?: AgentPluginUserTokenSlot;
+    currentUser?: AgentPluginUserTokenSlot;
+}
+export interface ResolveOAuthAccountHookContext extends AgentPluginContext {
+    tokens: AgentPluginStoredTokens;
+}
+export interface IssueCredentialHookContext extends AgentPluginContext {
+    actor: AgentPluginCredentialActor;
+    credentialSubject?: AgentPluginResolvedCredentialUser;
+    grant: AgentPluginGrant;
+    tokens: AgentPluginTokenStore;
+}
 export interface AgentPluginHooks {
     sandboxPrepare?(ctx: SandboxPrepareHookContext): Promise<void> | void;
     beforeToolExecute?(ctx: BeforeToolExecuteHookContext): Promise<void> | void;
+    grantForEgress?(ctx: EgressHookContext): Promise<AgentPluginGrant | undefined> | AgentPluginGrant | undefined;
+    issueCredential?(ctx: IssueCredentialHookContext): Promise<AgentPluginCredentialResult> | AgentPluginCredentialResult;
+    onEgressResponse?(ctx: EgressResponseHookContext): Promise<void> | void;
+    resolveOAuthAccount?(ctx: ResolveOAuthAccountHookContext): Promise<AgentPluginProviderAccount | undefined> | AgentPluginProviderAccount | undefined;
     routes?(ctx: RouteRegistrationHookContext): AgentPluginRoute[];
     tools?(ctx: ToolRegistrationHookContext): Record<string, AgentPluginToolDefinition>;
     heartbeat?(ctx: HeartbeatHookContext): Promise<HeartbeatResult | void> | HeartbeatResult | void;
@@ -217,6 +415,21 @@ export interface JuniorPluginOAuthConfig {
     clientIdEnv: string;
     clientSecretEnv: string;
     scope?: string;
+    /**
+     * Treat a provider token response with `scope: ""` like an omitted scope and
+     * fall back to the requested scope string when storing the token.
+     *
+     * Enable this only for providers whose token responses cannot report OAuth
+     * scopes even though Junior needs a local requested-scope string for
+     * reauthorization checks. The built-in GitHub App plugin enables this because
+     * GitHub App user-to-server tokens always return an empty scope value — their
+     * effective access is enforced by GitHub App permissions, installation
+     * repository access, and the requesting user's own access, not OAuth scopes.
+     *
+     * Do not enable this for standard OAuth providers where an explicit empty
+     * `scope` means the provider granted no scopes.
+     */
+    treatEmptyScopeAsUnreported?: boolean;
     tokenAuthMethod?: "body" | "basic";
     tokenEndpoint: string;
     tokenExtraHeaders?: Record<string, string>;
@@ -228,17 +441,7 @@ export interface JuniorPluginOAuthBearerCredentials {
     domains: string[];
     type: "oauth-bearer";
 }
-export interface JuniorPluginGitHubAppCredentials {
-    apiHeaders?: Record<string, string>;
-    appIdEnv: string;
-    authTokenEnv: string;
-    authTokenPlaceholder?: string;
-    domains: string[];
-    installationIdEnv: string;
-    privateKeyEnv: string;
-    type: "github-app";
-}
-export type JuniorPluginCredentials = JuniorPluginOAuthBearerCredentials | JuniorPluginGitHubAppCredentials;
+export type JuniorPluginCredentials = JuniorPluginOAuthBearerCredentials;
 export interface JuniorPluginNpmRuntimeDependency {
     package: string;
     type: "npm";
@@ -301,3 +504,4 @@ export interface JuniorPluginRegistration extends JuniorPluginRegistrationInput
 }
 /** Define one Junior plugin registration for app and build-time wiring. */
 export declare function defineJuniorPlugin(plugin: JuniorPluginRegistrationInput): JuniorPluginRegistration;
+export {};

package/dist/index.js

@@ -1,15 +1,134 @@
 // src/index.ts
+import { z } from "zod";
+var slackTeamIdSchema = z.string().regex(/^T[A-Z0-9]+$/);
+var slackConversationIdSchema = z.string().regex(/^(C|G|D)[A-Z0-9]+$/);
+var exactActorUserIdSchema = z.string().min(1).refine(
+  (value) => value === value.trim() && value.toLowerCase() !== "unknown"
+);
+var nonBlankStringSchema = z.string().refine((value) => value.trim().length > 0);
+var destinationSchema = z.object({
+  platform: z.literal("slack"),
+  teamId: slackTeamIdSchema,
+  channelId: slackConversationIdSchema
+}).strict();
+var agentPluginCredentialSubjectSchema = z.object({
+  type: z.literal("user"),
+  userId: exactActorUserIdSchema,
+  allowedWhen: z.literal("private-direct-conversation")
+}).strict();
+var agentPluginRequesterSchema = z.object({
+  userId: exactActorUserIdSchema.optional(),
+  userName: nonBlankStringSchema.optional(),
+  fullName: nonBlankStringSchema.optional(),
+  email: nonBlankStringSchema.optional()
+}).strict();
+var dispatchMetadataSchema = z.record(z.string(), z.string()).superRefine((metadata, ctx) => {
+  const entries = Object.entries(metadata);
+  if (entries.length > 20) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "Dispatch metadata has too many keys"
+    });
+    return;
+  }
+  for (const [key, value] of entries) {
+    if (!key.trim()) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Dispatch metadata values must be strings",
+        path: [key]
+      });
+      continue;
+    }
+    if (key.length > 128) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Dispatch metadata key exceeds the maximum length",
+        path: [key]
+      });
+    }
+    if (value.length > 512) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Dispatch metadata value exceeds the maximum length",
+        path: [key]
+      });
+    }
+  }
+});
+var dispatchOptionsSchema = z.object({
+  idempotencyKey: nonBlankStringSchema.pipe(z.string().max(512)),
+  credentialSubject: agentPluginCredentialSubjectSchema.optional(),
+  destination: destinationSchema,
+  input: nonBlankStringSchema.pipe(z.string().max(32e3)),
+  metadata: dispatchMetadataSchema.optional()
+}).strict();
 var AgentPluginToolInputError = class extends Error {
   constructor(message, options) {
     super(message, options);
     this.name = "AgentPluginToolInputError";
   }
 };
+var agentPluginProviderNameSchema = z.string().regex(/^[a-z][a-z0-9-]*$/);
+var agentPluginGrantNameSchema = z.string().regex(/^[a-z][a-z0-9.-]*$/);
+var agentPluginGrantAccessSchema = z.union([
+  z.literal("read"),
+  z.literal("write")
+]);
+var agentPluginAuthorizationSchema = z.object({
+  provider: agentPluginProviderNameSchema,
+  scope: nonBlankStringSchema.optional(),
+  type: z.literal("oauth")
+}).strict();
+var agentPluginProviderAccountSchema = z.object({
+  id: nonBlankStringSchema,
+  label: nonBlankStringSchema.optional(),
+  url: nonBlankStringSchema.optional()
+}).strict();
+var agentPluginGrantSchema = z.object({
+  access: agentPluginGrantAccessSchema,
+  name: agentPluginGrantNameSchema,
+  reason: nonBlankStringSchema.optional(),
+  requirements: z.array(nonBlankStringSchema).min(1).optional()
+}).strict();
+var agentPluginCredentialHeaderTransformSchema = z.object({
+  domain: z.string().min(1),
+  headers: z.record(z.string(), z.string()).refine((headers) => Object.keys(headers).length > 0)
+}).strict();
+var agentPluginCredentialLeaseSchema = z.object({
+  account: agentPluginProviderAccountSchema.optional(),
+  authorization: agentPluginAuthorizationSchema.optional(),
+  expiresAt: z.string().refine((value) => Number.isFinite(Date.parse(value))),
+  headerTransforms: z.array(agentPluginCredentialHeaderTransformSchema).min(1)
+}).strict();
+var agentPluginCredentialResultSchema = z.discriminatedUnion("type", [
+  z.object({
+    lease: agentPluginCredentialLeaseSchema,
+    type: z.literal("lease")
+  }).strict(),
+  z.object({
+    authorization: agentPluginAuthorizationSchema.optional(),
+    message: nonBlankStringSchema,
+    type: z.literal("needed")
+  }).strict(),
+  z.object({
+    message: nonBlankStringSchema,
+    type: z.literal("unavailable")
+  }).strict()
+]);
+var EgressAuthRequired = class extends Error {
+  authorization;
+  constructor(message, options) {
+    super(message, { cause: options?.cause });
+    this.name = "EgressAuthRequired";
+    this.authorization = options?.authorization;
+  }
+};
 var PLUGIN_NAME_RE = /^[a-z][a-z0-9-]*$/;
 function defineJuniorPlugin(plugin) {
   if ("pluginConfig" in plugin) {
     throw new Error(
-      "pluginConfig is no longer supported. Put runtime metadata in manifest and trusted state prefixes on the plugin registration."
+      "pluginConfig is no longer supported. Put runtime metadata in manifest and state prefixes on the plugin registration."
     );
   }
   const manifest = plugin.manifest;
@@ -46,5 +165,16 @@ function defineJuniorPlugin(plugin) {
 }
 export {
   AgentPluginToolInputError,
-  defineJuniorPlugin
+  EgressAuthRequired,
+  agentPluginAuthorizationSchema,
+  agentPluginCredentialHeaderTransformSchema,
+  agentPluginCredentialLeaseSchema,
+  agentPluginCredentialResultSchema,
+  agentPluginCredentialSubjectSchema,
+  agentPluginGrantSchema,
+  agentPluginProviderAccountSchema,
+  agentPluginRequesterSchema,
+  defineJuniorPlugin,
+  destinationSchema,
+  dispatchOptionsSchema
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-plugin-api",
-  "version": "0.68.0",
+  "version": "0.70.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -21,6 +21,9 @@
     "dist",
     "src"
   ],
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
   "devDependencies": {
     "oxlint": "^1.66.0",
     "tsup": "^8.5.1",

package/src/index.ts

@@ -1,9 +1,94 @@
-export interface AgentPluginRequester {
-  userId?: string;
-  userName?: string;
-  fullName?: string;
-  email?: string;
-}
+import { z } from "zod";
+
+const slackTeamIdSchema = z.string().regex(/^T[A-Z0-9]+$/);
+const slackConversationIdSchema = z.string().regex(/^(C|G|D)[A-Z0-9]+$/);
+const exactActorUserIdSchema = z
+  .string()
+  .min(1)
+  .refine(
+    (value) => value === value.trim() && value.toLowerCase() !== "unknown",
+  );
+const nonBlankStringSchema = z
+  .string()
+  .refine((value) => value.trim().length > 0);
+
+/** Runtime-owned provider-neutral address for routing future work or side effects. */
+export const destinationSchema = z
+  .object({
+    platform: z.literal("slack"),
+    teamId: slackTeamIdSchema,
+    channelId: slackConversationIdSchema,
+  })
+  .strict();
+
+/** Stable user credential subject shape accepted from plugins. */
+export const agentPluginCredentialSubjectSchema = z
+  .object({
+    type: z.literal("user"),
+    userId: exactActorUserIdSchema,
+    allowedWhen: z.literal("private-direct-conversation"),
+  })
+  .strict();
+
+/** Runtime-provided requester identity visible to plugin hooks. */
+export const agentPluginRequesterSchema = z
+  .object({
+    userId: exactActorUserIdSchema.optional(),
+    userName: nonBlankStringSchema.optional(),
+    fullName: nonBlankStringSchema.optional(),
+    email: nonBlankStringSchema.optional(),
+  })
+  .strict();
+
+const dispatchMetadataSchema = z
+  .record(z.string(), z.string())
+  .superRefine((metadata, ctx) => {
+    const entries = Object.entries(metadata);
+    if (entries.length > 20) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Dispatch metadata has too many keys",
+      });
+      return;
+    }
+    for (const [key, value] of entries) {
+      if (!key.trim()) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Dispatch metadata values must be strings",
+          path: [key],
+        });
+        continue;
+      }
+      if (key.length > 128) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Dispatch metadata key exceeds the maximum length",
+          path: [key],
+        });
+      }
+      if (value.length > 512) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Dispatch metadata value exceeds the maximum length",
+          path: [key],
+        });
+      }
+    }
+  });
+
+/** Plugin dispatch request accepted by Junior core. */
+export const dispatchOptionsSchema = z
+  .object({
+    idempotencyKey: nonBlankStringSchema.pipe(z.string().max(512)),
+    credentialSubject: agentPluginCredentialSubjectSchema.optional(),
+    destination: destinationSchema,
+    input: nonBlankStringSchema.pipe(z.string().max(32_000)),
+    metadata: dispatchMetadataSchema.optional(),
+  })
+  .strict();
+
+export type AgentPluginRequester = z.output<typeof agentPluginRequesterSchema>;
 
 export interface AgentPluginMetadata {
   name: string;
@@ -25,7 +110,7 @@ export interface AgentPluginLogger {
   warn(message: string, metadata?: Record<string, unknown>): void;
 }
 
-/** Thrown when a trusted plugin tool rejects invalid model or user input. */
+/** Thrown when a plugin tool rejects invalid model or user input. */
 export class AgentPluginToolInputError extends Error {
   constructor(message: string, options?: { cause?: unknown }) {
     super(message, options);
@@ -104,13 +189,36 @@ export interface AgentPluginToolDefinition<TInput = unknown> {
 }
 
 export interface ToolRegistrationHookContext extends AgentPluginContext {
+  /**
+   * Capabilities of `channelId` — the raw conversation channel exposed to
+   * this plugin. Recomputed from `channelId`, not from `destination`.
+   */
   channelCapabilities?: {
     canAddReactions: boolean;
     canCreateCanvas: boolean;
     canPostToChannel: boolean;
   };
+  /**
+   * The raw Slack channel ID for this conversation — the DM or channel where
+   * this turn is happening, without any assistant-context-source override.
+   * Use this as the stable binding key for state scoped to a Slack conversation.
+   * `channelCapabilities` describes this channel.
+   */
   channelId?: string;
+  /**
+   * Opaque Junior conversation/session identity for this turn.
+   * Interactive Slack turns use `slack:{channelId}:{threadTs}`.
+   * Scheduled/API turns use an internal id such as `agent-dispatch:{id}`.
+   * Do not parse as Slack unless the value starts with `slack:`.
+   */
+  conversationId?: string;
   credentialSubject?: AgentPluginCredentialSubject;
+  /**
+   * Runtime-owned destination suitable for future autonomous dispatch. For
+   * Slack, this is the raw conversation channel, not a thread timestamp or
+   * assistant-context source channel.
+   */
+  destination?: Destination;
   messageTs?: string;
   requester?: AgentPluginRequester;
   state: AgentPluginState;
@@ -119,23 +227,13 @@ export interface ToolRegistrationHookContext extends AgentPluginContext {
   userText?: string;
 }
 
-export interface AgentPluginCredentialSubject {
-  type: "user";
-  userId: string;
-  allowedWhen: "private-direct-conversation";
-}
+export type AgentPluginCredentialSubject = z.output<
+  typeof agentPluginCredentialSubjectSchema
+>;
 
-export interface DispatchOptions {
-  credentialSubject?: AgentPluginCredentialSubject;
-  destination: {
-    platform: "slack";
-    teamId: string;
-    channelId: string;
-  };
-  idempotencyKey: string;
-  input: string;
-  metadata?: Record<string, string>;
-}
+export type Destination = z.output<typeof destinationSchema>;
+
+export type DispatchOptions = z.output<typeof dispatchOptionsSchema>;
 
 export interface DispatchResult {
   id: string;
@@ -256,9 +354,221 @@ export interface SlackConversationLinkHookContext extends AgentPluginContext {
   conversationId: string;
 }
 
+const agentPluginProviderNameSchema = z.string().regex(/^[a-z][a-z0-9-]*$/);
+const agentPluginGrantNameSchema = z.string().regex(/^[a-z][a-z0-9.-]*$/);
+const agentPluginGrantAccessSchema = z.union([
+  z.literal("read"),
+  z.literal("write"),
+]);
+
+/** Runtime schema for provider authorization a plugin may request. */
+export const agentPluginAuthorizationSchema = z
+  .object({
+    provider: agentPluginProviderNameSchema,
+    scope: nonBlankStringSchema.optional(),
+    type: z.literal("oauth"),
+  })
+  .strict();
+
+/** Runtime schema for a provider account attached to stored OAuth tokens. */
+export const agentPluginProviderAccountSchema = z
+  .object({
+    id: nonBlankStringSchema,
+    label: nonBlankStringSchema.optional(),
+    url: nonBlankStringSchema.optional(),
+  })
+  .strict();
+
+/** Runtime schema for a plugin-defined outbound credential grant. */
+export const agentPluginGrantSchema = z
+  .object({
+    access: agentPluginGrantAccessSchema,
+    name: agentPluginGrantNameSchema,
+    reason: nonBlankStringSchema.optional(),
+    requirements: z.array(nonBlankStringSchema).min(1).optional(),
+  })
+  .strict();
+
+/** Runtime schema for plugin-issued header mutations. */
+export const agentPluginCredentialHeaderTransformSchema = z
+  .object({
+    domain: z.string().min(1),
+    headers: z
+      .record(z.string(), z.string())
+      .refine((headers) => Object.keys(headers).length > 0),
+  })
+  .strict();
+
+/** Runtime schema for a short-lived plugin-issued credential lease. */
+export const agentPluginCredentialLeaseSchema = z
+  .object({
+    account: agentPluginProviderAccountSchema.optional(),
+    authorization: agentPluginAuthorizationSchema.optional(),
+    expiresAt: z.string().refine((value) => Number.isFinite(Date.parse(value))),
+    headerTransforms: z
+      .array(agentPluginCredentialHeaderTransformSchema)
+      .min(1),
+  })
+  .strict();
+
+/** Runtime schema for the result returned by a plugin credential hook. */
+export const agentPluginCredentialResultSchema = z.discriminatedUnion("type", [
+  z
+    .object({
+      lease: agentPluginCredentialLeaseSchema,
+      type: z.literal("lease"),
+    })
+    .strict(),
+  z
+    .object({
+      authorization: agentPluginAuthorizationSchema.optional(),
+      message: nonBlankStringSchema,
+      type: z.literal("needed"),
+    })
+    .strict(),
+  z
+    .object({
+      message: nonBlankStringSchema,
+      type: z.literal("unavailable"),
+    })
+    .strict(),
+]);
+
+export type AgentPluginGrantAccess = z.output<
+  typeof agentPluginGrantAccessSchema
+>;
+
+/** Provider authorization Junior can start when a plugin-owned grant is missing. */
+export type AgentPluginAuthorization = z.output<
+  typeof agentPluginAuthorizationSchema
+>;
+
+/** Interrupt sandbox egress so Junior can start provider authorization. */
+export class EgressAuthRequired extends Error {
+  authorization?: AgentPluginAuthorization;
+
+  constructor(
+    message: string,
+    options?: {
+      authorization?: AgentPluginAuthorization;
+      cause?: unknown;
+    },
+  ) {
+    super(message, { cause: options?.cause });
+    this.name = "EgressAuthRequired";
+    this.authorization = options?.authorization;
+  }
+}
+
+/** Provider account identity resolved by a plugin OAuth hook. */
+export type AgentPluginProviderAccount = z.output<
+  typeof agentPluginProviderAccountSchema
+>;
+
+/** Plugin-defined grant required before Junior can forward one outbound request. */
+export type AgentPluginGrant = z.output<typeof agentPluginGrantSchema>;
+
+/** Request details available while selecting the grant for sandbox egress. */
+export interface AgentPluginEgressRequest {
+  /** Capped request body text when the host exposes it for provider-specific grant classification. */
+  bodyText?: string;
+  method: string;
+  url: string;
+}
+
+export interface EgressHookContext extends AgentPluginContext {
+  request: AgentPluginEgressRequest;
+}
+
+export interface AgentPluginEgressResponse {
+  /** Snapshot of upstream response headers; mutations do not affect pass-through. */
+  headers: Headers;
+  readText(maxBytes: number): Promise<string | undefined>;
+  status: number;
+}
+
+export interface EgressResponseHookContext extends AgentPluginContext {
+  grant: AgentPluginGrant;
+  permissionDenied(message: string): void;
+  request: Omit<AgentPluginEgressRequest, "bodyText">;
+  response: AgentPluginEgressResponse;
+}
+
+/** Header mutations a plugin-issued credential lease may apply to owned domains. */
+export type AgentPluginCredentialHeaderTransform = z.output<
+  typeof agentPluginCredentialHeaderTransformSchema
+>;
+
+/** Short-lived credential headers issued by a plugin for a selected grant. */
+export type AgentPluginCredentialLease = z.output<
+  typeof agentPluginCredentialLeaseSchema
+>;
+
+export type AgentPluginCredentialResult = z.output<
+  typeof agentPluginCredentialResultSchema
+>;
+
+export type AgentPluginCredentialActor =
+  | {
+      type: "system";
+      id: string;
+    }
+  | {
+      type: "user";
+      userId: string;
+    };
+
+export interface AgentPluginResolvedCredentialUser {
+  type: "user";
+  userId: string;
+}
+
+export interface AgentPluginStoredTokens {
+  account?: AgentPluginProviderAccount;
+  accessToken: string;
+  expiresAt?: number;
+  refreshToken: string;
+  scope?: string;
+}
+
+export interface AgentPluginUserTokenSlot {
+  get(): Promise<AgentPluginStoredTokens | undefined>;
+  set(tokens: AgentPluginStoredTokens): Promise<void>;
+  userId: string;
+}
+
+export interface AgentPluginTokenStore {
+  credentialSubject?: AgentPluginUserTokenSlot;
+  currentUser?: AgentPluginUserTokenSlot;
+}
+
+export interface ResolveOAuthAccountHookContext extends AgentPluginContext {
+  tokens: AgentPluginStoredTokens;
+}
+
+export interface IssueCredentialHookContext extends AgentPluginContext {
+  actor: AgentPluginCredentialActor;
+  credentialSubject?: AgentPluginResolvedCredentialUser;
+  grant: AgentPluginGrant;
+  tokens: AgentPluginTokenStore;
+}
+
 export interface AgentPluginHooks {
   sandboxPrepare?(ctx: SandboxPrepareHookContext): Promise<void> | void;
   beforeToolExecute?(ctx: BeforeToolExecuteHookContext): Promise<void> | void;
+  grantForEgress?(
+    ctx: EgressHookContext,
+  ): Promise<AgentPluginGrant | undefined> | AgentPluginGrant | undefined;
+  issueCredential?(
+    ctx: IssueCredentialHookContext,
+  ): Promise<AgentPluginCredentialResult> | AgentPluginCredentialResult;
+  onEgressResponse?(ctx: EgressResponseHookContext): Promise<void> | void;
+  resolveOAuthAccount?(
+    ctx: ResolveOAuthAccountHookContext,
+  ):
+    | Promise<AgentPluginProviderAccount | undefined>
+    | AgentPluginProviderAccount
+    | undefined;
   routes?(ctx: RouteRegistrationHookContext): AgentPluginRoute[];
   tools?(
     ctx: ToolRegistrationHookContext,
@@ -283,6 +593,21 @@ export interface JuniorPluginOAuthConfig {
   clientIdEnv: string;
   clientSecretEnv: string;
   scope?: string;
+  /**
+   * Treat a provider token response with `scope: ""` like an omitted scope and
+   * fall back to the requested scope string when storing the token.
+   *
+   * Enable this only for providers whose token responses cannot report OAuth
+   * scopes even though Junior needs a local requested-scope string for
+   * reauthorization checks. The built-in GitHub App plugin enables this because
+   * GitHub App user-to-server tokens always return an empty scope value — their
+   * effective access is enforced by GitHub App permissions, installation
+   * repository access, and the requesting user's own access, not OAuth scopes.
+   *
+   * Do not enable this for standard OAuth providers where an explicit empty
+   * `scope` means the provider granted no scopes.
+   */
+  treatEmptyScopeAsUnreported?: boolean;
   tokenAuthMethod?: "body" | "basic";
   tokenEndpoint: string;
   tokenExtraHeaders?: Record<string, string>;
@@ -296,20 +621,7 @@ export interface JuniorPluginOAuthBearerCredentials {
   type: "oauth-bearer";
 }
 
-export interface JuniorPluginGitHubAppCredentials {
-  apiHeaders?: Record<string, string>;
-  appIdEnv: string;
-  authTokenEnv: string;
-  authTokenPlaceholder?: string;
-  domains: string[];
-  installationIdEnv: string;
-  privateKeyEnv: string;
-  type: "github-app";
-}
-
-export type JuniorPluginCredentials =
-  | JuniorPluginOAuthBearerCredentials
-  | JuniorPluginGitHubAppCredentials;
+export type JuniorPluginCredentials = JuniorPluginOAuthBearerCredentials;
 
 export interface JuniorPluginNpmRuntimeDependency {
   package: string;
@@ -392,7 +704,7 @@ export function defineJuniorPlugin(
 ): JuniorPluginRegistration {
   if ("pluginConfig" in plugin) {
     throw new Error(
-      "pluginConfig is no longer supported. Put runtime metadata in manifest and trusted state prefixes on the plugin registration.",
+      "pluginConfig is no longer supported. Put runtime metadata in manifest and state prefixes on the plugin registration.",
     );
   }
   const manifest = plugin.manifest;