@sentry/junior-plugin-api 0.116.1 → 0.118.0

package/README.md

@@ -21,7 +21,8 @@ The manifest declares runtime metadata such as:
 - provider domains, grants, OAuth, API-header transformations, and safe command
   environment placeholders;
 - runtime dependencies and snapshot installation steps;
-- configuration fields.
+- configuration fields;
+- signed-in user pages backed by core-owned discovery and read routes.
 
 Manifest values are validated before runtime activation. Secret deployment
 values remain host-only; sandbox-exposed command environment must be explicitly
@@ -39,6 +40,18 @@ 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.
+- 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.
+
+## 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.
 
 ## Durable Work
 

package/dist/hooks.d.ts

@@ -1,10 +1,10 @@
 import type { EgressHookContext, EgressResponseHookContext, IssueCredentialHookContext, PluginCredentialResult, PluginGrant, PluginProviderAccount, ResolveOAuthAccountHookContext } from "./credentials";
 import type { HeartbeatHookContext, HeartbeatResult, OperationalReportHookContext, ApiRouteRegistrationHookContext, PluginOperationalReportContent, PluginRoute, PluginRouteApp, RouteRegistrationHookContext, SlackConversationLink, SlackConversationLinkHookContext } from "./operations";
 import type { BeforeToolExecuteHookContext, PluginToolDefinition, SandboxPrepareHookContext, ToolRegistrationHookContext } from "./tools";
-import type { PromptMessage, SystemPromptContext, UserPromptContext } from "./prompt";
+import type { PromptMessage, SystemPromptContext, UserPromptContext, UserPromptContribution } from "./prompt";
 export interface PluginHooks {
     systemPrompt?(ctx: SystemPromptContext): Promise<PromptMessage[]> | PromptMessage[];
-    userPrompt?(ctx: UserPromptContext): Promise<PromptMessage[] | undefined> | PromptMessage[] | undefined;
+    userPrompt?(ctx: UserPromptContext): Promise<UserPromptContribution[] | undefined> | UserPromptContribution[] | undefined;
     beforeToolExecute?(ctx: BeforeToolExecuteHookContext): Promise<void> | void;
     grantForEgress?(ctx: EgressHookContext): Promise<PluginGrant | undefined> | PluginGrant | undefined;
     heartbeat?(ctx: HeartbeatHookContext): Promise<HeartbeatResult | void> | HeartbeatResult | void;

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export * from "./annotations";
 export * from "./schemas";
 export * from "./context";
 export * from "./state";
-export { promptMessageSchema, type PromptMessage, type SystemPromptContext, type UserPromptContext, } from "./prompt";
+export { definePromptContext, promptContextSchema, promptMessageSchema, type PromptContext, type PromptContextContribution, type PromptMessage, type SystemPromptContext, type UserPromptContribution, type UserPromptContext, } from "./prompt";
 export * from "./dispatch";
 export * from "./resource-events";
 export * from "./tasks";
@@ -13,3 +13,4 @@ export * from "./hooks";
 export * from "./cli";
 export * from "./manifest";
 export * from "./registration";
+export * from "./user-pages";

package/dist/index.js

@@ -198,9 +198,25 @@ function isSlackDestination(destination) {
 
 // src/prompt.ts
 import { z as z3 } from "zod";
+var promptContextKindSchema = z3.string().trim().min(1).max(64).regex(/^[a-z][a-z0-9_-]*$/);
 var promptMessageSchema = z3.object({
   text: z3.string().trim().min(1).max(8e3)
 }).strict();
+var promptContextSchema = z3.object({
+  kind: promptContextKindSchema,
+  version: z3.number().int().positive(),
+  content: z3.record(z3.string(), z3.unknown())
+}).strict();
+function definePromptContext(definition) {
+  const identity = promptContextSchema.pick({ kind: true, version: true }).parse({ kind: definition.kind, version: definition.version });
+  return (content) => {
+    const parsed = definition.schema.parse(content);
+    return {
+      context: { ...identity, content: parsed },
+      renderPrompt: () => definition.renderPrompt(parsed)
+    };
+  };
+}
 
 // src/resource-events.ts
 import { z as z4 } from "zod";
@@ -446,6 +462,7 @@ var EgressPolicyDenied = class extends Error {
 
 // src/registration.ts
 var PLUGIN_NAME_RE = /^[a-z][a-z0-9-]*$/;
+var USER_PAGE_ID_RE = /^[a-z][a-z0-9-]*$/;
 function defineJuniorPlugin(plugin) {
   if ("pluginConfig" in plugin) {
     throw new Error(
@@ -480,10 +497,69 @@ function defineJuniorPlugin(plugin) {
       `Junior plugin "${name}" manifest.description is required.`
     );
   }
+  if (plugin.userPages !== void 0 && !Array.isArray(plugin.userPages)) {
+    throw new Error(`Junior plugin "${name}" userPages must be an array.`);
+  }
+  const userPageIds = /* @__PURE__ */ new Set();
+  for (const page of plugin.userPages ?? []) {
+    if (!page || typeof page !== "object") {
+      throw new Error(`Junior plugin "${name}" user pages must be objects.`);
+    }
+    if (typeof page.id !== "string" || page.id.length > 64 || !USER_PAGE_ID_RE.test(page.id)) {
+      throw new Error(
+        `Junior plugin "${name}" user page id "${page.id}" must be a lowercase identifier.`
+      );
+    }
+    if (userPageIds.has(page.id)) {
+      throw new Error(
+        `Junior plugin "${name}" has duplicate user page id "${page.id}".`
+      );
+    }
+    if (typeof page.label !== "string" || !page.label.trim() || page.label.length > 80 || typeof page.description !== "string" || !page.description.trim() || page.description.length > 500) {
+      throw new Error(
+        `Junior plugin "${name}" user page "${page.id}" requires label and description.`
+      );
+    }
+    if (typeof page.read !== "function") {
+      throw new Error(
+        `Junior plugin "${name}" user page "${page.id}" requires a read function.`
+      );
+    }
+    userPageIds.add(page.id);
+  }
   return {
     ...plugin
   };
 }
+
+// src/user-pages.ts
+import { z as z9 } from "zod";
+var userPageIdSchema = nonBlankStringSchema.max(64).regex(/^[a-z][a-z0-9-]*$/);
+var userPageLabelSchema = nonBlankStringSchema.max(80);
+var userPageDescriptionSchema = nonBlankStringSchema.max(500);
+var pluginUserPageMetadataSchema = z9.object({
+  label: nonBlankStringSchema.max(80),
+  value: nonBlankStringSchema.max(500)
+}).strict();
+var pluginUserPageRecordSchema = z9.object({
+  description: nonBlankStringSchema.max(1e3).optional(),
+  id: nonBlankStringSchema.max(128),
+  metadata: z9.array(pluginUserPageMetadataSchema).max(8).optional(),
+  title: nonBlankStringSchema.max(4e3)
+}).strict();
+var pluginUserPageContentSchema = z9.object({
+  emptyText: nonBlankStringSchema.max(500).optional(),
+  records: z9.array(pluginUserPageRecordSchema).max(100),
+  type: z9.literal("list")
+}).strict();
+var pluginUserPageLinkSchema = z9.object({
+  description: userPageDescriptionSchema,
+  id: userPageIdSchema,
+  label: userPageLabelSchema,
+  pluginDisplayName: nonBlankStringSchema.max(200),
+  pluginName: nonBlankStringSchema.max(100)
+}).strict();
+var pluginUserPageLinksSchema = z9.array(pluginUserPageLinkSchema);
 export {
   EgressAuthRequired,
   EgressPolicyDenied,
@@ -494,6 +570,7 @@ export {
   createSlackSource,
   defineJuniorPlugin,
   definePluginTool,
+  definePromptContext,
   destinationSchema,
   destinationVisibilitySchema,
   dispatchOptionsSchema,
@@ -520,6 +597,10 @@ export {
   pluginToolContinuationSchema,
   pluginToolErrorSchema,
   pluginToolResultSchema,
+  pluginUserPageContentSchema,
+  pluginUserPageLinkSchema,
+  pluginUserPageLinksSchema,
+  promptContextSchema,
   promptMessageSchema,
   resourceEventSchema,
   resourceLinkAnnotationSchema,

package/dist/prompt.d.ts

@@ -6,6 +6,27 @@ export declare const promptMessageSchema: z.ZodObject<{
 }, z.core.$strict>;
 /** Small plugin-owned prompt text block rendered by Junior core. */
 export type PromptMessage = z.output<typeof promptMessageSchema>;
+export declare const promptContextSchema: z.ZodObject<{
+    kind: z.ZodString;
+    version: z.ZodNumber;
+    content: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+/** Structured plugin context retained alongside its model-visible rendering. */
+export type PromptContext = z.output<typeof promptContextSchema>;
+/** Runtime contribution produced from one validated plugin context value. */
+export interface PromptContextContribution {
+    context: PromptContext;
+    renderPrompt(): string;
+}
+/** Define one typed, versioned plugin context contribution. */
+export declare function definePromptContext<TSchema extends z.ZodType<Record<string, unknown>>>(definition: {
+    kind: string;
+    version: number;
+    schema: TSchema;
+    renderPrompt(content: z.output<TSchema>): string;
+}): (content: z.input<TSchema>) => PromptContextContribution;
+/** One request-scoped plugin contribution to the model-visible user prompt. */
+export type UserPromptContribution = PromptMessage | PromptContextContribution;
 /** Stable platform context for plugin system prompt guidance. */
 export type SystemPromptContext = Pick<PluginContext, "db" | "log" | "plugin"> & {
     platform: Platform;

package/dist/registration.d.ts

@@ -2,6 +2,7 @@ import type { PluginCliDefinition } from "./cli";
 import type { PluginHooks } from "./hooks";
 import type { PluginManifest } from "./manifest";
 import type { PluginTasks } from "./tasks";
+import type { PluginUserPageDefinition } from "./user-pages";
 export interface PluginModelConfig {
     /** Host model family used when no explicit structured model id is configured. */
     structuredModel?: "default" | "fast";
@@ -15,6 +16,7 @@ export type PluginRegistrationInput = {
     model?: PluginModelConfig;
     packageName?: string;
     tasks?: PluginTasks;
+    userPages?: PluginUserPageDefinition[];
 };
 export interface PluginRegistration extends PluginRegistrationInput {
 }

package/dist/user-pages.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Core-rendered plugin user pages.
+ *
+ * Plugins own bounded data projection; Junior owns viewer authorization,
+ * routing, response validation, and browser rendering.
+ */
+import { z } from "zod";
+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>;
+    records: z.ZodArray<z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        metadata: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strict>>>;
+        title: z.ZodString;
+    }, z.core.$strict>>;
+    type: z.ZodLiteral<"list">;
+}, z.core.$strict>;
+/** Validated content for the current core-rendered list page type. */
+export type PluginUserPageContent = z.output<typeof pluginUserPageContentSchema>;
+export declare const pluginUserPageLinkSchema: z.ZodObject<{
+    description: z.ZodString;
+    id: z.ZodString;
+    label: z.ZodString;
+    pluginDisplayName: z.ZodString;
+    pluginName: z.ZodString;
+}, z.core.$strict>;
+export declare const pluginUserPageLinksSchema: z.ZodArray<z.ZodObject<{
+    description: z.ZodString;
+    id: z.ZodString;
+    label: z.ZodString;
+    pluginDisplayName: z.ZodString;
+    pluginName: z.ZodString;
+}, z.core.$strict>>;
+/** Safe navigation metadata for one registered plugin user page. */
+export type PluginUserPageLink = z.output<typeof pluginUserPageLinkSchema>;
+/** 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. */
+export interface PluginUserPageContext extends PluginContext {
+    viewer: {
+        actors: PluginUserPageActor[];
+        email: string;
+    };
+}
+/** Navigation metadata and reader for one core-rendered plugin user page. */
+export interface PluginUserPageDefinition {
+    description: string;
+    id: string;
+    label: string;
+    read(ctx: PluginUserPageContext): Promise<PluginUserPageContent> | PluginUserPageContent;
+}

package/package.json

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

package/src/hooks.ts

@@ -29,6 +29,7 @@ import type {
   PromptMessage,
   SystemPromptContext,
   UserPromptContext,
+  UserPromptContribution,
 } from "./prompt";
 
 export interface PluginHooks {
@@ -37,7 +38,10 @@ export interface PluginHooks {
   ): Promise<PromptMessage[]> | PromptMessage[];
   userPrompt?(
     ctx: UserPromptContext,
-  ): Promise<PromptMessage[] | undefined> | PromptMessage[] | undefined;
+  ):
+    | Promise<UserPromptContribution[] | undefined>
+    | UserPromptContribution[]
+    | undefined;
   beforeToolExecute?(ctx: BeforeToolExecuteHookContext): Promise<void> | void;
   grantForEgress?(
     ctx: EgressHookContext,

package/src/index.ts

@@ -3,9 +3,14 @@ export * from "./schemas";
 export * from "./context";
 export * from "./state";
 export {
+  definePromptContext,
+  promptContextSchema,
   promptMessageSchema,
+  type PromptContext,
+  type PromptContextContribution,
   type PromptMessage,
   type SystemPromptContext,
+  type UserPromptContribution,
   type UserPromptContext,
 } from "./prompt";
 export * from "./dispatch";
@@ -18,3 +23,4 @@ export * from "./hooks";
 export * from "./cli";
 export * from "./manifest";
 export * from "./registration";
+export * from "./user-pages";

package/src/prompt.ts

@@ -9,6 +9,13 @@ import type {
 } from "./context";
 import type { PluginState } from "./state";
 
+const promptContextKindSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(64)
+  .regex(/^[a-z][a-z0-9_-]*$/);
+
 export const promptMessageSchema = z
   .object({
     text: z.string().trim().min(1).max(8_000),
@@ -18,6 +25,47 @@ export const promptMessageSchema = z
 /** Small plugin-owned prompt text block rendered by Junior core. */
 export type PromptMessage = z.output<typeof promptMessageSchema>;
 
+export const promptContextSchema = z
+  .object({
+    kind: promptContextKindSchema,
+    version: z.number().int().positive(),
+    content: z.record(z.string(), z.unknown()),
+  })
+  .strict();
+
+/** Structured plugin context retained alongside its model-visible rendering. */
+export type PromptContext = z.output<typeof promptContextSchema>;
+
+/** Runtime contribution produced from one validated plugin context value. */
+export interface PromptContextContribution {
+  context: PromptContext;
+  renderPrompt(): string;
+}
+
+/** Define one typed, versioned plugin context contribution. */
+export function definePromptContext<
+  TSchema extends z.ZodType<Record<string, unknown>>,
+>(definition: {
+  kind: string;
+  version: number;
+  schema: TSchema;
+  renderPrompt(content: z.output<TSchema>): string;
+}): (content: z.input<TSchema>) => PromptContextContribution {
+  const identity = promptContextSchema
+    .pick({ kind: true, version: true })
+    .parse({ kind: definition.kind, version: definition.version });
+  return (content) => {
+    const parsed = definition.schema.parse(content);
+    return {
+      context: { ...identity, content: parsed },
+      renderPrompt: () => definition.renderPrompt(parsed),
+    };
+  };
+}
+
+/** One request-scoped plugin contribution to the model-visible user prompt. */
+export type UserPromptContribution = PromptMessage | PromptContextContribution;
+
 /** Stable platform context for plugin system prompt guidance. */
 export type SystemPromptContext = Pick<
   PluginContext,

package/src/registration.ts

@@ -2,6 +2,7 @@ import type { PluginCliDefinition } from "./cli";
 import type { PluginHooks } from "./hooks";
 import type { PluginManifest } from "./manifest";
 import type { PluginTasks } from "./tasks";
+import type { PluginUserPageDefinition } from "./user-pages";
 
 export interface PluginModelConfig {
   /** Host model family used when no explicit structured model id is configured. */
@@ -17,11 +18,13 @@ export type PluginRegistrationInput = {
   model?: PluginModelConfig;
   packageName?: string;
   tasks?: PluginTasks;
+  userPages?: PluginUserPageDefinition[];
 };
 
 export interface PluginRegistration extends PluginRegistrationInput {}
 
 const PLUGIN_NAME_RE = /^[a-z][a-z0-9-]*$/;
+const USER_PAGE_ID_RE = /^[a-z][a-z0-9-]*$/;
 
 /** Define one Junior plugin registration for app and build-time wiring. */
 export function defineJuniorPlugin(
@@ -66,6 +69,47 @@ export function defineJuniorPlugin(
       `Junior plugin "${name}" manifest.description is required.`,
     );
   }
+  if (plugin.userPages !== undefined && !Array.isArray(plugin.userPages)) {
+    throw new Error(`Junior plugin "${name}" userPages must be an array.`);
+  }
+  const userPageIds = new Set<string>();
+  for (const page of plugin.userPages ?? []) {
+    if (!page || typeof page !== "object") {
+      throw new Error(`Junior plugin "${name}" user pages must be objects.`);
+    }
+    if (
+      typeof page.id !== "string" ||
+      page.id.length > 64 ||
+      !USER_PAGE_ID_RE.test(page.id)
+    ) {
+      throw new Error(
+        `Junior plugin "${name}" user page id "${page.id}" must be a lowercase identifier.`,
+      );
+    }
+    if (userPageIds.has(page.id)) {
+      throw new Error(
+        `Junior plugin "${name}" has duplicate user page id "${page.id}".`,
+      );
+    }
+    if (
+      typeof page.label !== "string" ||
+      !page.label.trim() ||
+      page.label.length > 80 ||
+      typeof page.description !== "string" ||
+      !page.description.trim() ||
+      page.description.length > 500
+    ) {
+      throw new Error(
+        `Junior plugin "${name}" user page "${page.id}" requires label and description.`,
+      );
+    }
+    if (typeof page.read !== "function") {
+      throw new Error(
+        `Junior plugin "${name}" user page "${page.id}" requires a read function.`,
+      );
+    }
+    userPageIds.add(page.id);
+  }
   return {
     ...plugin,
   };

package/src/user-pages.ts

@@ -0,0 +1,81 @@
+/**
+ * Core-rendered plugin user pages.
+ *
+ * Plugins own bounded data projection; Junior owns viewer authorization,
+ * routing, response validation, and browser rendering.
+ */
+import { z } from "zod";
+import type { LocalActor, PluginContext, SlackActor } from "./context";
+import { nonBlankStringSchema } from "./schemas";
+
+const userPageIdSchema = nonBlankStringSchema
+  .max(64)
+  .regex(/^[a-z][a-z0-9-]*$/);
+const userPageLabelSchema = nonBlankStringSchema.max(80);
+const userPageDescriptionSchema = nonBlankStringSchema.max(500);
+
+const pluginUserPageMetadataSchema = z
+  .object({
+    label: nonBlankStringSchema.max(80),
+    value: nonBlankStringSchema.max(500),
+  })
+  .strict();
+
+const pluginUserPageRecordSchema = z
+  .object({
+    description: nonBlankStringSchema.max(1_000).optional(),
+    id: nonBlankStringSchema.max(128),
+    metadata: z.array(pluginUserPageMetadataSchema).max(8).optional(),
+    title: nonBlankStringSchema.max(4_000),
+  })
+  .strict();
+
+/** Bounded list content returned by a plugin-owned user page. */
+export const pluginUserPageContentSchema = z
+  .object({
+    emptyText: nonBlankStringSchema.max(500).optional(),
+    records: z.array(pluginUserPageRecordSchema).max(100),
+    type: z.literal("list"),
+  })
+  .strict();
+
+/** Validated content for the current core-rendered list page type. */
+export type PluginUserPageContent = z.output<
+  typeof pluginUserPageContentSchema
+>;
+
+export const pluginUserPageLinkSchema = z
+  .object({
+    description: userPageDescriptionSchema,
+    id: userPageIdSchema,
+    label: userPageLabelSchema,
+    pluginDisplayName: nonBlankStringSchema.max(200),
+    pluginName: nonBlankStringSchema.max(100),
+  })
+  .strict();
+
+export const pluginUserPageLinksSchema = z.array(pluginUserPageLinkSchema);
+
+/** Safe navigation metadata for one registered plugin user page. */
+export type PluginUserPageLink = z.output<typeof pluginUserPageLinkSchema>;
+
+/** 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. */
+export interface PluginUserPageContext extends PluginContext {
+  viewer: {
+    actors: PluginUserPageActor[];
+    email: string;
+  };
+}
+
+/** Navigation metadata and reader for one core-rendered plugin user page. */
+export interface PluginUserPageDefinition {
+  description: string;
+  id: string;
+  label: string;
+  read(
+    ctx: PluginUserPageContext,
+  ): Promise<PluginUserPageContent> | PluginUserPageContent;
+}