@sentry/junior-plugin-api 0.119.0 → 0.121.0

package/README.md

@@ -45,6 +45,9 @@ reports, and other typed hook surfaces exported by this package.
 - Tool hooks return model-visible schemas aligned with their executor inputs.
 - Host-owned structured model and embedding calls do not expose provider
   credentials to plugins.
+- Authenticated API route apps receive one verified viewer in their request
+  context. The registration hook exposes actor resolution for plugins whose
+  viewer-owned data spans platform identities.
 - User page readers receive the signed-in email plus runtime-owned actors linked
   to that user. Plugins return bounded data and do not mount their own page
   routes or browser code.
@@ -52,11 +55,12 @@ reports, and other typed hook surfaces exported by this package.
 ## User Pages
 
 Register signed-in pages through `userPages` beside `hooks`, `tasks`, and `cli`.
-Each definition owns its navigation metadata and `read(ctx)` function, so a
-page cannot be advertised without an implementation. Core owns discovery,
-authentication, actor resolution, routing, response validation, and rendering.
-The initial response type is the bounded `list` page; add another core-rendered
-type only when a concrete product need proves it.
+Each definition owns its navigation metadata and `read(ctx, input)` function,
+so a page cannot be advertised without an implementation. List readers receive
+validated search and cursor input and may return an opaque continuation cursor.
+Records may expose bounded `DELETE` actions inside their own authenticated
+plugin API namespace. Core owns discovery, authentication, actor resolution,
+routing, response validation, rendering, confirmation, and query state.
 
 ## Durable Work
 

package/dist/index.js

@@ -541,7 +541,15 @@ var pluginUserPageMetadataSchema = z9.object({
   label: nonBlankStringSchema.max(80),
   value: nonBlankStringSchema.max(500)
 }).strict();
+var pluginUserPageActionSchema = z9.object({
+  confirmation: nonBlankStringSchema.max(500).optional(),
+  href: nonBlankStringSchema.max(500).regex(/^\/api\/plugins\/[a-z][a-z0-9-]*(?:\/|$)/),
+  label: nonBlankStringSchema.max(80),
+  method: z9.literal("DELETE"),
+  tone: z9.enum(["danger", "neutral"]).optional()
+}).strict();
 var pluginUserPageRecordSchema = z9.object({
+  actions: z9.array(pluginUserPageActionSchema).max(4).optional(),
   description: nonBlankStringSchema.max(1e3).optional(),
   id: nonBlankStringSchema.max(128),
   metadata: z9.array(pluginUserPageMetadataSchema).max(8).optional(),
@@ -549,7 +557,9 @@ var pluginUserPageRecordSchema = z9.object({
 }).strict();
 var pluginUserPageContentSchema = z9.object({
   emptyText: nonBlankStringSchema.max(500).optional(),
+  nextCursor: nonBlankStringSchema.max(1e3).optional(),
   records: z9.array(pluginUserPageRecordSchema).max(100),
+  searchPlaceholder: nonBlankStringSchema.max(120).optional(),
   type: z9.literal("list")
 }).strict();
 var pluginUserPageLinkSchema = z9.object({
@@ -560,6 +570,11 @@ var pluginUserPageLinkSchema = z9.object({
   pluginName: nonBlankStringSchema.max(100)
 }).strict();
 var pluginUserPageLinksSchema = z9.array(pluginUserPageLinkSchema);
+var pluginUserPageInputSchema = z9.object({
+  cursor: nonBlankStringSchema.max(1e3).optional(),
+  limit: z9.number().int().min(1).max(50),
+  query: z9.string().trim().max(200).optional()
+}).strict();
 export {
   EgressAuthRequired,
   EgressPolicyDenied,
@@ -598,6 +613,7 @@ export {
   pluginToolErrorSchema,
   pluginToolResultSchema,
   pluginUserPageContentSchema,
+  pluginUserPageInputSchema,
   pluginUserPageLinkSchema,
   pluginUserPageLinksSchema,
   promptContextSchema,

package/dist/manifest.d.ts

@@ -42,10 +42,13 @@ export interface PluginRuntimePostinstallCommand {
     sudo?: boolean;
 }
 export interface PluginMcpConfig {
+    /** Provider tools exposed directly to the model. */
     allowedTools?: string[];
     headers?: Record<string, string>;
     transport: "http";
     url: string;
+    /** Provider tools hidden from the model and callable only by plugin-owned wrapper tools. */
+    wrappedTools?: string[];
 }
 export interface PluginEnvVarDeclaration {
     default?: string;

package/dist/operations.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { PluginContext } from "./context";
+import type { LocalActor, PluginContext, SlackActor } from "./context";
 import type { Dispatch, DispatchOptions, DispatchResult } from "./dispatch";
 import type { PluginReadState, PluginState } from "./state";
 import type { ResourceEventPublisher } from "./resource-events";
@@ -89,6 +89,10 @@ export interface RouteRegistrationHookContext extends PluginContext {
     resourceEvents: ResourceEventPublisher;
 }
 export interface ApiRouteRegistrationHookContext extends PluginContext {
+    viewer: {
+        /** Resolve every runtime actor linked to one authenticated viewer email. */
+        actors(email: string): Promise<Array<LocalActor | SlackActor>>;
+    };
 }
 /** Per-request context Junior passes to authenticated plugin product API routes. */
 export declare const pluginApiRouteRequestContextSchema: z.ZodObject<{

package/dist/prompt.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { Destination, Platform, PluginContext, PluginEmbedder, Actor, Source } from "./context";
+import type { Destination, Platform, PluginContext, PluginEmbedder, PluginModel, Actor, Source } from "./context";
 import type { PluginState } from "./state";
 export declare const promptMessageSchema: z.ZodObject<{
     text: z.ZodString;
@@ -36,6 +36,7 @@ export type UserPromptContext = Pick<PluginContext, "db" | "log" | "plugin"> & {
     conversationId?: string;
     destination: Destination;
     embedder: PluginEmbedder;
+    model: PluginModel;
     actor?: Actor;
     source: Source;
     state: PluginState;

package/dist/tools.d.ts

@@ -53,6 +53,53 @@ export interface PluginEgress {
         request: Request;
     }): Promise<Response>;
 }
+export type PluginMcpContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+/** Successful raw provider result returned to a plugin-owned wrapper tool. */
+export type PluginMcpToolSuccess = {
+    content: PluginMcpContent[];
+    status: "success";
+    structuredContent?: unknown;
+};
+/** Handled provider authorization pause with no provider result to consume. */
+export type PluginMcpAuthorizationPending = {
+    status: "authorization_pending";
+};
+/** Definitive provider rejection; transport and session failures still throw. */
+export type PluginMcpToolError = {
+    message: string;
+    status: "error";
+};
+export type PluginMcpToolResult = PluginMcpAuthorizationPending | PluginMcpToolError | PluginMcpToolSuccess;
+/** Access to this plugin's hosted MCP provider without exposing credentials. */
+export interface PluginMcp {
+    /**
+     * Call a provider tool declared in `wrappedTools`.
+     *
+     * The host activates the provider when needed. Successful calls return the
+     * provider's original content, provider rejections return an error result,
+     * and authorization pauses return no tool content. Transport failures throw.
+     */
+    callTool(input: {
+        arguments?: Record<string, unknown>;
+        name: string;
+        toolCallId?: string;
+    }): Promise<PluginMcpToolResult>;
+    /**
+     * Activate the provider before wrapper-owned state changes.
+     *
+     * Ordinary wrappers can call `callTool` directly. Durable mutation wrappers
+     * may prepare first so an initial authorization pause happens before they
+     * record pending work.
+     */
+    prepare(): Promise<"authorization_pending" | "ready">;
+}
 export interface SandboxPrepareHookContext extends PluginContext {
     actor?: Actor;
     sandbox: PluginSandbox;
@@ -221,6 +268,7 @@ interface BaseToolRegistrationHookContext extends PluginContext {
     annotations?: PluginAnnotations;
     embedder: PluginEmbedder;
     egress: PluginEgress;
+    mcp?: PluginMcp;
     model: PluginModel;
     state: PluginState;
     userText?: string;

package/dist/user-pages.d.ts

@@ -9,7 +9,18 @@ import type { LocalActor, PluginContext, SlackActor } from "./context";
 /** Bounded list content returned by a plugin-owned user page. */
 export declare const pluginUserPageContentSchema: z.ZodObject<{
     emptyText: z.ZodOptional<z.ZodString>;
+    nextCursor: z.ZodOptional<z.ZodString>;
     records: z.ZodArray<z.ZodObject<{
+        actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            confirmation: z.ZodOptional<z.ZodString>;
+            href: z.ZodString;
+            label: z.ZodString;
+            method: z.ZodLiteral<"DELETE">;
+            tone: z.ZodOptional<z.ZodEnum<{
+                danger: "danger";
+                neutral: "neutral";
+            }>>;
+        }, z.core.$strict>>>;
         description: z.ZodOptional<z.ZodString>;
         id: z.ZodString;
         metadata: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -18,6 +29,7 @@ export declare const pluginUserPageContentSchema: z.ZodObject<{
         }, z.core.$strict>>>;
         title: z.ZodString;
     }, z.core.$strict>>;
+    searchPlaceholder: z.ZodOptional<z.ZodString>;
     type: z.ZodLiteral<"list">;
 }, z.core.$strict>;
 /** Validated content for the current core-rendered list page type. */
@@ -38,6 +50,13 @@ export declare const pluginUserPageLinksSchema: z.ZodArray<z.ZodObject<{
 }, z.core.$strict>>;
 /** Safe navigation metadata for one registered plugin user page. */
 export type PluginUserPageLink = z.output<typeof pluginUserPageLinkSchema>;
+/** Validated query state passed to one plugin user page reader. */
+export declare const pluginUserPageInputSchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodNumber;
+    query: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type PluginUserPageInput = z.output<typeof pluginUserPageInputSchema>;
 /** Runtime-owned actor shapes that may belong to an authenticated viewer. */
 export type PluginUserPageActor = SlackActor | LocalActor;
 /** Trusted host context supplied while reading one plugin user page. */
@@ -52,5 +71,5 @@ export interface PluginUserPageDefinition {
     description: string;
     id: string;
     label: string;
-    read(ctx: PluginUserPageContext): Promise<PluginUserPageContent> | PluginUserPageContent;
+    read(ctx: PluginUserPageContext, input: PluginUserPageInput): Promise<PluginUserPageContent> | PluginUserPageContent;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-plugin-api",
-  "version": "0.119.0",
+  "version": "0.121.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/src/manifest.ts

@@ -53,10 +53,13 @@ export interface PluginRuntimePostinstallCommand {
 }
 
 export interface PluginMcpConfig {
+  /** Provider tools exposed directly to the model. */
   allowedTools?: string[];
   headers?: Record<string, string>;
   transport: "http";
   url: string;
+  /** Provider tools hidden from the model and callable only by plugin-owned wrapper tools. */
+  wrappedTools?: string[];
 }
 
 export interface PluginEnvVarDeclaration {

package/src/operations.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { PluginContext } from "./context";
+import type { LocalActor, PluginContext, SlackActor } from "./context";
 import type { Dispatch, DispatchOptions, DispatchResult } from "./dispatch";
 import { nonBlankStringSchema } from "./schemas";
 import type { PluginReadState, PluginState } from "./state";
@@ -119,7 +119,12 @@ export interface RouteRegistrationHookContext extends PluginContext {
   resourceEvents: ResourceEventPublisher;
 }
 
-export interface ApiRouteRegistrationHookContext extends PluginContext {}
+export interface ApiRouteRegistrationHookContext extends PluginContext {
+  viewer: {
+    /** Resolve every runtime actor linked to one authenticated viewer email. */
+    actors(email: string): Promise<Array<LocalActor | SlackActor>>;
+  };
+}
 
 /** Per-request context Junior passes to authenticated plugin product API routes. */
 export const pluginApiRouteRequestContextSchema = z

package/src/prompt.ts

@@ -4,6 +4,7 @@ import type {
   Platform,
   PluginContext,
   PluginEmbedder,
+  PluginModel,
   Actor,
   Source,
 } from "./context";
@@ -79,6 +80,7 @@ export type UserPromptContext = Pick<PluginContext, "db" | "log" | "plugin"> & {
   conversationId?: string;
   destination: Destination;
   embedder: PluginEmbedder;
+  model: PluginModel;
   actor?: Actor;
   source: Source;
   state: PluginState;

package/src/tools.ts

@@ -67,6 +67,57 @@ export interface PluginEgress {
   }): Promise<Response>;
 }
 
+export type PluginMcpContent =
+  | { type: "text"; text: string }
+  | { type: "image"; data: string; mimeType: string };
+
+/** Successful raw provider result returned to a plugin-owned wrapper tool. */
+export type PluginMcpToolSuccess = {
+  content: PluginMcpContent[];
+  status: "success";
+  structuredContent?: unknown;
+};
+
+/** Handled provider authorization pause with no provider result to consume. */
+export type PluginMcpAuthorizationPending = {
+  status: "authorization_pending";
+};
+
+/** Definitive provider rejection; transport and session failures still throw. */
+export type PluginMcpToolError = {
+  message: string;
+  status: "error";
+};
+
+export type PluginMcpToolResult =
+  | PluginMcpAuthorizationPending
+  | PluginMcpToolError
+  | PluginMcpToolSuccess;
+
+/** Access to this plugin's hosted MCP provider without exposing credentials. */
+export interface PluginMcp {
+  /**
+   * Call a provider tool declared in `wrappedTools`.
+   *
+   * The host activates the provider when needed. Successful calls return the
+   * provider's original content, provider rejections return an error result,
+   * and authorization pauses return no tool content. Transport failures throw.
+   */
+  callTool(input: {
+    arguments?: Record<string, unknown>;
+    name: string;
+    toolCallId?: string;
+  }): Promise<PluginMcpToolResult>;
+  /**
+   * Activate the provider before wrapper-owned state changes.
+   *
+   * Ordinary wrappers can call `callTool` directly. Durable mutation wrappers
+   * may prepare first so an initial authorization pause happens before they
+   * record pending work.
+   */
+  prepare(): Promise<"authorization_pending" | "ready">;
+}
+
 export interface SandboxPrepareHookContext extends PluginContext {
   actor?: Actor;
   sandbox: PluginSandbox;
@@ -350,6 +401,7 @@ interface BaseToolRegistrationHookContext extends PluginContext {
   annotations?: PluginAnnotations;
   embedder: PluginEmbedder;
   egress: PluginEgress;
+  mcp?: PluginMcp;
   model: PluginModel;
   state: PluginState;
   userText?: string;

package/src/user-pages.ts

@@ -21,8 +21,21 @@ const pluginUserPageMetadataSchema = z
   })
   .strict();
 
+const pluginUserPageActionSchema = z
+  .object({
+    confirmation: nonBlankStringSchema.max(500).optional(),
+    href: nonBlankStringSchema
+      .max(500)
+      .regex(/^\/api\/plugins\/[a-z][a-z0-9-]*(?:\/|$)/),
+    label: nonBlankStringSchema.max(80),
+    method: z.literal("DELETE"),
+    tone: z.enum(["danger", "neutral"]).optional(),
+  })
+  .strict();
+
 const pluginUserPageRecordSchema = z
   .object({
+    actions: z.array(pluginUserPageActionSchema).max(4).optional(),
     description: nonBlankStringSchema.max(1_000).optional(),
     id: nonBlankStringSchema.max(128),
     metadata: z.array(pluginUserPageMetadataSchema).max(8).optional(),
@@ -34,7 +47,9 @@ const pluginUserPageRecordSchema = z
 export const pluginUserPageContentSchema = z
   .object({
     emptyText: nonBlankStringSchema.max(500).optional(),
+    nextCursor: nonBlankStringSchema.max(1_000).optional(),
     records: z.array(pluginUserPageRecordSchema).max(100),
+    searchPlaceholder: nonBlankStringSchema.max(120).optional(),
     type: z.literal("list"),
   })
   .strict();
@@ -59,6 +74,17 @@ export const pluginUserPageLinksSchema = z.array(pluginUserPageLinkSchema);
 /** Safe navigation metadata for one registered plugin user page. */
 export type PluginUserPageLink = z.output<typeof pluginUserPageLinkSchema>;
 
+/** Validated query state passed to one plugin user page reader. */
+export const pluginUserPageInputSchema = z
+  .object({
+    cursor: nonBlankStringSchema.max(1_000).optional(),
+    limit: z.number().int().min(1).max(50),
+    query: z.string().trim().max(200).optional(),
+  })
+  .strict();
+
+export type PluginUserPageInput = z.output<typeof pluginUserPageInputSchema>;
+
 /** Runtime-owned actor shapes that may belong to an authenticated viewer. */
 export type PluginUserPageActor = SlackActor | LocalActor;
 
@@ -77,5 +103,6 @@ export interface PluginUserPageDefinition {
   label: string;
   read(
     ctx: PluginUserPageContext,
+    input: PluginUserPageInput,
   ): Promise<PluginUserPageContent> | PluginUserPageContent;
 }