@sentry/junior-plugin-api 0.126.1 → 0.128.0

package/README.md

@@ -55,12 +55,14 @@ reports, and other typed hook surfaces exported by this package.
   binds the plugin namespace and owns access to the conversation event log.
   Event `costUsd` is additive operation cost and must not duplicate cost
   already recorded in the conversation's agent model usage.
-- 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.
+- Tool hooks may lazily resolve the active actor's canonical identity and linked
+  user through `ctx.users.resolveActor()`.
+- Authenticated API route hooks receive `ctx.users.resolve(email)` for lazy
+  canonical user resolution. Routes that do not need personal ownership do not
+  query identity storage.
+- User page readers receive the canonical viewer `User` with linked identities.
+  Plugins return bounded data and do not mount their own page routes or browser
+  code.
 
 ## User Pages
 
@@ -72,7 +74,7 @@ Set `navigation: "primary"` for a top-level dashboard navigation item. The
 default `profile` placement keeps account-oriented pages in the signed-in user
 menu. Junior always renders core System navigation after plugin pages.
 Records may expose bounded `DELETE` actions inside their own authenticated
-plugin API namespace. Core owns discovery, authentication, actor resolution,
+plugin API namespace. Core owns discovery, authentication, user resolution,
 routing, response validation, rendering, confirmation, and query state.
 
 ## Durable Work

package/dist/context.d.ts

@@ -1,12 +1,14 @@
 import { z } from "zod";
 import type { ZodTypeAny } from "zod";
-import { destinationSchema, localActorSchema, platformSchema, actorSchema, slackActorSchema, systemActorSchema, sourceSchema } from "./schemas";
+import { destinationSchema, identitySchema, localActorSchema, platformSchema, actorSchema, slackActorSchema, systemActorSchema, sourceSchema, userSchema } from "./schemas";
 /** Runtime platform name without source or destination coordinates. */
 export type Platform = z.output<typeof platformSchema>;
 export type Actor = z.output<typeof actorSchema>;
 export type SlackActor = z.output<typeof slackActorSchema>;
 export type LocalActor = z.output<typeof localActorSchema>;
 export type SystemActor = z.output<typeof systemActorSchema>;
+export type Identity = z.output<typeof identitySchema>;
+export type User = z.output<typeof userSchema>;
 export type Source = z.output<typeof sourceSchema>;
 export type SlackSource = Extract<Source, {
     platform: "slack";

package/dist/index.js

@@ -154,6 +154,20 @@ var actorSchema = z3.discriminatedUnion("platform", [
   localActorSchema,
   systemActorSchema
 ]);
+var identitySchema = z3.object({
+  displayName: nonBlankStringSchema.optional(),
+  handle: nonBlankStringSchema.optional(),
+  id: exactNonBlankStringSchema,
+  provider: exactNonBlankStringSchema,
+  providerSubjectId: exactNonBlankStringSchema,
+  providerTenantId: exactNonBlankStringSchema.optional()
+}).strict();
+var userSchema = z3.object({
+  displayName: nonBlankStringSchema.optional(),
+  email: nonBlankStringSchema.max(320),
+  id: exactNonBlankStringSchema,
+  identities: z3.array(identitySchema).max(100)
+}).strict();
 var dispatchMetadataSchema = z3.record(z3.string(), z3.string()).superRefine((metadata, ctx) => {
   const entries = Object.entries(metadata);
   if (entries.length > 20) {
@@ -276,24 +290,94 @@ function definePromptContext(definition) {
 
 // src/resource-events.ts
 import { z as z5 } from "zod";
+var RESOURCE_EVENT_SUMMARY_MAX_LENGTH = 4e3;
+var RESOURCE_EVENT_TEXT_MAX_LENGTH = 8e3;
+var resourceEventTypeSchema = z5.string().regex(/^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)+$/).describe(
+  "Canonical dotted event type, such as issue.closed or pull_request.review.changes_requested."
+);
+var resourceTypeSchema = z5.string().regex(/^[a-z][a-z0-9_]*$/).describe(
+  "Canonical plugin-defined resource type, such as issue or pull_request."
+);
+var pluginResourceEventTypeSchema = z5.object({
+  type: resourceTypeSchema,
+  supportedEvents: z5.array(resourceEventTypeSchema).min(1),
+  suggestedEvents: z5.array(resourceEventTypeSchema).optional()
+}).strict().superRefine((resourceType, context) => {
+  const supported = /* @__PURE__ */ new Set();
+  resourceType.supportedEvents.forEach((eventType, index) => {
+    if (supported.has(eventType)) {
+      context.addIssue({
+        code: "custom",
+        message: `Duplicate supported resource event type "${eventType}".`,
+        path: ["supportedEvents", index]
+      });
+    }
+    supported.add(eventType);
+  });
+  const suggested = /* @__PURE__ */ new Set();
+  resourceType.suggestedEvents?.forEach((eventType, index) => {
+    if (suggested.has(eventType)) {
+      context.addIssue({
+        code: "custom",
+        message: `Duplicate suggested resource event type "${eventType}".`,
+        path: ["suggestedEvents", index]
+      });
+    }
+    if (!supported.has(eventType)) {
+      context.addIssue({
+        code: "custom",
+        message: `Suggested resource event type "${eventType}" is not supported.`,
+        path: ["suggestedEvents", index]
+      });
+    }
+    suggested.add(eventType);
+  });
+});
+var pluginResourceEventsSchema = z5.object({
+  resourceTypes: z5.array(pluginResourceEventTypeSchema).min(1),
+  isEnabled: z5.function({ input: [], output: z5.boolean() }).optional(),
+  normalizeIdentifier: z5.function({ input: [z5.string()], output: z5.string() }).optional()
+}).strict().superRefine((registration, context) => {
+  const seen = /* @__PURE__ */ new Set();
+  registration.resourceTypes.forEach((resourceType, index) => {
+    if (seen.has(resourceType.type)) {
+      context.addIssue({
+        code: "custom",
+        message: `Duplicate resource type "${resourceType.type}".`,
+        path: ["resourceTypes", index, "type"]
+      });
+    }
+    seen.add(resourceType.type);
+  });
+});
+function normalizeResourceEventIdentifier(registration, identifier) {
+  const trimmed = identifier.trim();
+  const normalized = (registration?.normalizeIdentifier?.(trimmed) ?? trimmed).trim();
+  if (!normalized) {
+    throw new Error("Resource event identifier must not normalize to empty");
+  }
+  return normalized;
+}
 var subscribableResourceSchema = z5.object({
+  identifier: z5.string().min(1),
   label: z5.string().min(1),
-  provider: z5.string().min(1),
-  resourceRef: z5.string().min(1),
-  suggestedEvents: z5.array(z5.string().min(1)).optional(),
-  supportedEvents: z5.array(z5.string().min(1)),
-  type: z5.string().min(1)
+  namespace: z5.string().min(1),
+  suggestedEvents: z5.array(resourceEventTypeSchema).optional(),
+  supportedEvents: z5.array(resourceEventTypeSchema),
+  type: resourceTypeSchema
 }).strict();
-var resourceEventSchema = z5.object({
+var resourceEventInputSchema = z5.object({
   eventKey: z5.string().min(1),
-  eventType: z5.string().min(1),
+  eventType: resourceEventTypeSchema,
+  identifier: z5.string().min(1),
   occurredAtMs: z5.number().finite(),
-  provider: z5.string().min(1),
-  resourceRef: z5.string().min(1),
   terminal: z5.boolean().optional(),
-  trustedSummary: z5.string().min(1),
-  untrustedText: z5.string().optional()
+  trustedSummary: z5.string().min(1).transform((value) => value.slice(0, RESOURCE_EVENT_SUMMARY_MAX_LENGTH)),
+  untrustedText: z5.string().transform((value) => value.slice(0, RESOURCE_EVENT_TEXT_MAX_LENGTH)).optional()
 }).strict();
+var resourceEventSchema = resourceEventInputSchema.extend({
+  namespace: z5.string().min(1)
+});
 
 // src/tasks.ts
 import { z as z6 } from "zod";
@@ -359,19 +443,10 @@ var pluginToolContinuationSchema = z7.object({
   arguments: z7.record(z7.string(), z7.unknown()),
   reason: z7.string().min(1).optional()
 }).strict();
-var pluginToolErrorSchema = z7.object({
-  kind: z7.string().min(1),
-  message: z7.string().min(1),
-  retryable: z7.boolean().optional()
-}).strict();
-var pluginToolResultSchema = z7.object({
-  ok: z7.boolean(),
-  status: z7.enum(["success", "error"]),
+var pluginToolOutputSchema = z7.object({
   target: z7.string().min(1).optional(),
-  data: z7.unknown().optional(),
   truncated: z7.boolean().optional(),
-  continuation: pluginToolContinuationSchema.optional(),
-  error: z7.union([pluginToolErrorSchema, z7.string()]).optional()
+  continuation: pluginToolContinuationSchema.optional()
 }).passthrough();
 var toolApprovalModeSchema = z7.enum(["auto", "review", "approve"]);
 var REQUIRED_TOOL_ANNOTATION_KEYS = [
@@ -385,7 +460,7 @@ function missingToolAnnotationKeys(annotations) {
     (key) => typeof annotations?.[key] !== "boolean"
   );
 }
-function isPluginToolResultEnvelope(value) {
+function isPluginToolOutputEnvelope(value) {
   return value !== null && typeof value === "object" && Array.isArray(value.content) && "details" in value;
 }
 function formatZodPath(path) {
@@ -441,15 +516,13 @@ function createZodTool(definition, helperName) {
           input,
           options
         );
-        if (isPluginToolResultEnvelope(result)) {
+        if (isPluginToolOutputEnvelope(result)) {
           return {
             content: z7.array(pluginToolContentSchema).parse(result.content),
-            details: outputSchema.parse(
-              pluginToolResultSchema.parse(result.details)
-            )
+            details: outputSchema.parse(result.details)
           };
         }
-        return outputSchema.parse(pluginToolResultSchema.parse(result));
+        return outputSchema.parse(result);
       }
     } : {}
   };
@@ -597,6 +670,14 @@ function defineJuniorPlugin(plugin) {
       `Junior plugin "${name}" conversationEvents must be an array.`
     );
   }
+  if (plugin.resourceEvents !== void 0) {
+    const parsed = pluginResourceEventsSchema.safeParse(plugin.resourceEvents);
+    if (!parsed.success) {
+      throw new Error(`Junior plugin "${name}" resourceEvents is invalid.`, {
+        cause: parsed.error
+      });
+    }
+  }
   const conversationEventIds = /* @__PURE__ */ new Set();
   for (const event of plugin.conversationEvents ?? []) {
     if (!event || typeof event !== "object" && typeof event !== "function" || typeof event.parse !== "function" || typeof event.renderEvent !== "function") {
@@ -707,6 +788,8 @@ export {
   EgressPolicyDenied,
   PluginToolInputError,
   REQUIRED_TOOL_ANNOTATION_KEYS,
+  RESOURCE_EVENT_SUMMARY_MAX_LENGTH,
+  RESOURCE_EVENT_TEXT_MAX_LENGTH,
   actorSchema,
   conversationAnnotationInputSchema,
   conversationEventIconSchema,
@@ -721,6 +804,7 @@ export {
   destinationVisibilitySchema,
   dispatchOptionsSchema,
   getSourceKey,
+  identitySchema,
   isPrivateSource,
   isSlackDestination,
   localActorSchema,
@@ -728,6 +812,7 @@ export {
   localSourceSchema,
   missingToolAnnotationKeys,
   nonBlankStringSchema,
+  normalizeResourceEventIdentifier,
   platformSchema,
   pluginApiRouteRequestContextSchema,
   pluginAuthorizationSchema,
@@ -737,14 +822,15 @@ export {
   pluginCredentialSubjectSchema,
   pluginGrantSchema,
   pluginProviderAccountSchema,
+  pluginResourceEventTypeSchema,
+  pluginResourceEventsSchema,
   pluginRunContextSchema,
   pluginRunTranscriptEntrySchema,
   pluginRunTranscriptProvenanceSchema,
   pluginStoredTokensSchema,
   pluginToolContentSchema,
   pluginToolContinuationSchema,
-  pluginToolErrorSchema,
-  pluginToolResultSchema,
+  pluginToolOutputSchema,
   pluginUserPageContentSchema,
   pluginUserPageInputSchema,
   pluginUserPageLinkSchema,
@@ -752,8 +838,11 @@ export {
   promptContextSchema,
   promptMessageSchema,
   replyAttributionSchema,
+  resourceEventInputSchema,
   resourceEventSchema,
+  resourceEventTypeSchema,
   resourceLinkAnnotationSchema,
+  resourceTypeSchema,
   slackActorSchema,
   slackDestinationSchema,
   slackSourceSchema,
@@ -762,5 +851,6 @@ export {
   subscribableResourceSchema,
   systemActorSchema,
   toolApprovalModeSchema,
+  userSchema,
   zodTool
 };

package/dist/operations.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { LocalActor, PluginContext, SlackActor } from "./context";
+import type { PluginContext, User } from "./context";
 import type { Dispatch, DispatchOptions, DispatchResult } from "./dispatch";
 import type { PluginReadState, PluginState } from "./state";
 import type { ResourceEventPublisher } from "./resource-events";
@@ -93,9 +93,9 @@ export interface RouteRegistrationHookContext extends PluginContext {
 }
 export interface ApiRouteRegistrationHookContext extends PluginContext {
     eventStats: PluginConversationEventStats;
-    viewer: {
-        /** Resolve every runtime actor linked to one authenticated viewer email. */
-        actors(email: string): Promise<Array<LocalActor | SlackActor>>;
+    users: {
+        /** Resolve or create the canonical user for one verified email. */
+        resolve(email: string): Promise<User | undefined>;
     };
 }
 /** Per-request context Junior passes to authenticated plugin product API routes. */

package/dist/registration.d.ts

@@ -4,6 +4,7 @@ import type { PluginHooks } from "./hooks";
 import type { PluginManifest } from "./manifest";
 import type { PluginTasks } from "./tasks";
 import type { PluginUserPageDefinition } from "./user-pages";
+import { type PluginResourceEvents } from "./resource-events";
 export interface PluginModelConfig {
     /** Host model family used when no explicit structured model id is configured. */
     structuredModel?: "default" | "fast";
@@ -17,6 +18,7 @@ export type PluginRegistrationInput = {
     manifest: PluginManifest;
     model?: PluginModelConfig;
     packageName?: string;
+    resourceEvents?: PluginResourceEvents;
     tasks?: PluginTasks;
     userPages?: PluginUserPageDefinition[];
 };

package/dist/resource-events.d.ts

@@ -1,25 +1,58 @@
 import { z } from "zod";
+export declare const RESOURCE_EVENT_SUMMARY_MAX_LENGTH = 4000;
+export declare const RESOURCE_EVENT_TEXT_MAX_LENGTH = 8000;
+/** Canonical dotted event type published and selected across plugins. */
+export declare const resourceEventTypeSchema: z.ZodString;
+export declare const resourceTypeSchema: z.ZodString;
+export declare const pluginResourceEventTypeSchema: z.ZodObject<{
+    type: z.ZodString;
+    supportedEvents: z.ZodArray<z.ZodString>;
+    suggestedEvents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const pluginResourceEventsSchema: z.ZodObject<{
+    resourceTypes: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        supportedEvents: z.ZodArray<z.ZodString>;
+        suggestedEvents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    isEnabled: z.ZodOptional<z.ZodFunction<z.ZodTuple<readonly [], null>, z.ZodBoolean>>;
+    normalizeIdentifier: z.ZodOptional<z.ZodFunction<z.ZodTuple<readonly [z.ZodString], null>, z.ZodString>>;
+}, z.core.$strict>;
+export type PluginResourceEventType = z.output<typeof pluginResourceEventTypeSchema>;
+export type PluginResourceEvents = z.output<typeof pluginResourceEventsSchema>;
+/** Apply a plugin's identifier convention at resource-event boundaries. */
+export declare function normalizeResourceEventIdentifier(registration: Pick<PluginResourceEvents, "normalizeIdentifier"> | undefined, identifier: string): string;
 export declare const subscribableResourceSchema: z.ZodObject<{
+    identifier: z.ZodString;
     label: z.ZodString;
-    provider: z.ZodString;
-    resourceRef: z.ZodString;
+    namespace: z.ZodString;
     suggestedEvents: z.ZodOptional<z.ZodArray<z.ZodString>>;
     supportedEvents: z.ZodArray<z.ZodString>;
     type: z.ZodString;
 }, z.core.$strict>;
 export type SubscribableResource = z.output<typeof subscribableResourceSchema>;
+export declare const resourceEventInputSchema: z.ZodObject<{
+    eventKey: z.ZodString;
+    eventType: z.ZodString;
+    identifier: z.ZodString;
+    occurredAtMs: z.ZodNumber;
+    terminal: z.ZodOptional<z.ZodBoolean>;
+    trustedSummary: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    untrustedText: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+}, z.core.$strict>;
+export type ResourceEventInput = z.output<typeof resourceEventInputSchema>;
 export declare const resourceEventSchema: z.ZodObject<{
     eventKey: z.ZodString;
     eventType: z.ZodString;
+    identifier: z.ZodString;
     occurredAtMs: z.ZodNumber;
-    provider: z.ZodString;
-    resourceRef: z.ZodString;
     terminal: z.ZodOptional<z.ZodBoolean>;
-    trustedSummary: z.ZodString;
-    untrustedText: z.ZodOptional<z.ZodString>;
+    trustedSummary: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    untrustedText: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    namespace: z.ZodString;
 }, z.core.$strict>;
 export type ResourceEvent = z.output<typeof resourceEventSchema>;
 export interface ResourceEventPublisher {
-    /** Publish one normalized event whose provider matches the owning plugin name. */
-    publish(event: ResourceEvent): Promise<void>;
+    /** Publish one normalized event under the owning plugin's namespace. */
+    publish(event: ResourceEventInput): Promise<void>;
 }

package/dist/schemas.d.ts

@@ -117,6 +117,29 @@ export declare const actorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     platform: z.ZodLiteral<"system">;
     name: z.ZodString;
 }, z.core.$strict>], "platform">;
+/** Core-owned provider account linked to a user when verified. */
+export declare const identitySchema: z.ZodObject<{
+    displayName: z.ZodOptional<z.ZodString>;
+    handle: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    provider: z.ZodString;
+    providerSubjectId: z.ZodString;
+    providerTenantId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Core-owned person with every linked provider identity. */
+export declare const userSchema: z.ZodObject<{
+    displayName: z.ZodOptional<z.ZodString>;
+    email: z.ZodString;
+    id: z.ZodString;
+    identities: z.ZodArray<z.ZodObject<{
+        displayName: z.ZodOptional<z.ZodString>;
+        handle: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        provider: z.ZodString;
+        providerSubjectId: z.ZodString;
+        providerTenantId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 /** Compact destination-visible context explaining what produced a reply. */
 export declare const replyAttributionSchema: z.ZodObject<{
     label: z.ZodPipe<z.ZodString, z.ZodString>;

package/dist/tools.d.ts

@@ -1,9 +1,9 @@
-import type { PluginContext, LocalInvocationContext, PluginEmbedder, PluginModel, Actor, SlackInvocationContext } from "./context";
+import type { PluginContext, LocalInvocationContext, PluginEmbedder, Identity, PluginModel, Actor, SlackInvocationContext, User } from "./context";
 import type { PluginCredentialSubject } from "./credentials";
 import type { PluginAnnotations } from "./annotations";
 import type { SlackConversationLink } from "./operations";
 import type { PluginState } from "./state";
-import { z, type ZodType, type ZodTypeAny } from "zod";
+import { z, type ZodTypeAny } from "zod";
 export interface PluginEnv {
     get(key: string): string | undefined;
     set(key: string, value: string): void;
@@ -63,8 +63,8 @@ export declare const pluginToolContentSchema: z.ZodDiscriminatedUnion<[z.ZodObje
 }, z.core.$strict>], "type">;
 /** Model-visible content returned by a plugin tool. */
 export type PluginToolContent = z.output<typeof pluginToolContentSchema>;
-/** Standard tool result envelope with separate model content and runtime details. */
-export interface PluginToolResultEnvelope<TDetails = PluginToolResult> {
+/** Pi-native projection with model-facing content and canonical runtime details. */
+export interface PluginToolOutputEnvelope<TDetails = unknown> {
     content: PluginToolContent[];
     details: TDetails;
 }
@@ -159,31 +159,16 @@ export declare const pluginToolContinuationSchema: z.ZodObject<{
     arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
-export declare const pluginToolErrorSchema: z.ZodObject<{
-    kind: z.ZodString;
-    message: z.ZodString;
-    retryable: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strict>;
-export declare const pluginToolResultSchema: z.ZodObject<{
-    ok: z.ZodBoolean;
-    status: z.ZodEnum<{
-        error: "error";
-        success: "success";
-    }>;
+/** Shared optional fields for canonical plugin tool outputs. */
+export declare const pluginToolOutputSchema: z.ZodObject<{
     target: z.ZodOptional<z.ZodString>;
-    data: z.ZodOptional<z.ZodUnknown>;
     truncated: z.ZodOptional<z.ZodBoolean>;
     continuation: z.ZodOptional<z.ZodObject<{
         arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         reason: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
-    error: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
-        kind: z.ZodString;
-        message: z.ZodString;
-        retryable: z.ZodOptional<z.ZodBoolean>;
-    }, z.core.$strict>, z.ZodString]>>;
 }, z.core.$loose>;
-export type PluginToolResult = z.output<typeof pluginToolResultSchema>;
+export type PluginToolOutput = z.output<typeof pluginToolOutputSchema>;
 export type PluginToolExecute<TInput = unknown, TOutput = unknown> = {
     bivarianceHack(input: TInput, options: PluginToolExecuteOptions): Promise<TOutput> | TOutput;
 }["bivarianceHack"];
@@ -262,17 +247,17 @@ export interface PluginToolDefinition<TInput = unknown, TOutput = unknown, TExec
     promptSnippet?: string;
     execute?: PluginToolExecute<TInput, TExecuteOutput>;
 }
-type ZodPluginToolDefinition<TInputSchema extends ZodTypeAny, TOutputSchema extends ZodType<PluginToolResult>, TExecuteResult extends z.input<TOutputSchema> | PluginToolResultEnvelope<z.input<TOutputSchema>>> = Omit<PluginToolDefinition<z.output<TInputSchema>, z.output<TOutputSchema>>, "inputSchema" | "outputSchema" | "prepareArguments" | "execute"> & {
+type ZodPluginToolDefinition<TInputSchema extends ZodTypeAny, TOutputSchema extends ZodTypeAny, TExecuteResult extends z.input<TOutputSchema> | PluginToolOutputEnvelope<z.input<TOutputSchema>>> = Omit<PluginToolDefinition<z.output<TInputSchema>, z.output<TOutputSchema>>, "inputSchema" | "outputSchema" | "prepareArguments" | "execute"> & {
     inputSchema: TInputSchema;
     outputSchema: TOutputSchema;
     prepareArguments?: (args: unknown) => z.input<TInputSchema>;
     execute?: (input: z.output<TInputSchema>, options: PluginToolExecuteOptions) => Promise<TExecuteResult> | TExecuteResult;
 };
-type ParsedPluginToolExecuteResult<TOutputSchema extends ZodTypeAny, TResult> = TResult extends PluginToolResultEnvelope<unknown> ? PluginToolResultEnvelope<z.output<TOutputSchema>> : z.output<TOutputSchema>;
+type ParsedPluginToolExecuteResult<TOutputSchema extends ZodTypeAny, TResult> = TResult extends PluginToolOutputEnvelope<unknown> ? PluginToolOutputEnvelope<z.output<TOutputSchema>> : z.output<TOutputSchema>;
 /** Define a plugin tool with Zod input parsing and validated structured results. */
-export declare function zodTool<TInputSchema extends ZodTypeAny, TOutputSchema extends ZodType<PluginToolResult>, TExecuteResult extends z.input<TOutputSchema> | PluginToolResultEnvelope<z.input<TOutputSchema>>>(definition: ZodPluginToolDefinition<TInputSchema, TOutputSchema, TExecuteResult>): PluginToolDefinition<z.output<TInputSchema>, z.output<TOutputSchema>, ParsedPluginToolExecuteResult<TOutputSchema, TExecuteResult>>;
+export declare function zodTool<TInputSchema extends ZodTypeAny, TOutputSchema extends ZodTypeAny, TExecuteResult extends z.input<TOutputSchema> | PluginToolOutputEnvelope<z.input<TOutputSchema>>>(definition: ZodPluginToolDefinition<TInputSchema, TOutputSchema, TExecuteResult>): PluginToolDefinition<z.output<TInputSchema>, z.output<TOutputSchema>, ParsedPluginToolExecuteResult<TOutputSchema, TExecuteResult>>;
 /** Define a plugin tool with Zod input parsing and the structured result contract. */
-export declare function definePluginTool<TInputSchema extends ZodTypeAny, TOutputSchema extends ZodType<PluginToolResult>, TExecuteResult extends z.input<TOutputSchema> | PluginToolResultEnvelope<z.input<TOutputSchema>>>(definition: ZodPluginToolDefinition<TInputSchema, TOutputSchema, TExecuteResult>): PluginToolDefinition<z.output<TInputSchema>, z.output<TOutputSchema>, ParsedPluginToolExecuteResult<TOutputSchema, TExecuteResult>>;
+export declare function definePluginTool<TInputSchema extends ZodTypeAny, TOutputSchema extends ZodTypeAny, TExecuteResult extends z.input<TOutputSchema> | PluginToolOutputEnvelope<z.input<TOutputSchema>>>(definition: ZodPluginToolDefinition<TInputSchema, TOutputSchema, TExecuteResult>): PluginToolDefinition<z.output<TInputSchema>, z.output<TOutputSchema>, ParsedPluginToolExecuteResult<TOutputSchema, TExecuteResult>>;
 export interface SlackToolRegistrationHookContext {
     /**
      * Capabilities of the source Slack conversation exposed to this plugin.
@@ -289,6 +274,10 @@ export interface SlackToolRegistrationHookContext {
         allowedWhen: "private-direct-conversation";
     }>;
 }
+export interface PluginResourceEventToolContext {
+    /** Whether this invocation can create a working resource-event subscription. */
+    canSubscribe: boolean;
+}
 interface BaseToolRegistrationHookContext extends PluginContext {
     /**
      * Opaque Junior conversation/session identity for this turn.
@@ -302,7 +291,15 @@ interface BaseToolRegistrationHookContext extends PluginContext {
     egress: PluginEgress;
     mcp?: PluginMcp;
     model: PluginModel;
+    resourceEvents: PluginResourceEventToolContext;
     state: PluginState;
+    users: {
+        /** Resolve the current actor's stored identity and linked user. */
+        resolveActor(): Promise<{
+            identity: Identity;
+            user?: User;
+        } | undefined>;
+    };
     userText?: string;
 }
 interface SlackToolRegistrationContext extends BaseToolRegistrationHookContext, SlackInvocationContext {

package/dist/user-pages.d.ts

@@ -5,7 +5,7 @@
  * routing, response validation, and browser rendering.
  */
 import { z } from "zod";
-import type { LocalActor, PluginContext, SlackActor } from "./context";
+import type { PluginContext, User } from "./context";
 /** Bounded list content returned by a plugin-owned user page. */
 export declare const pluginUserPageContentSchema: z.ZodObject<{
     emptyText: z.ZodOptional<z.ZodString>;
@@ -76,14 +76,9 @@ export declare const pluginUserPageInputSchema: z.ZodObject<{
     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. */
 export interface PluginUserPageContext extends PluginContext {
-    viewer: {
-        actors: PluginUserPageActor[];
-        email: string;
-    };
+    viewer: User;
 }
 /** Navigation metadata and reader for one core-rendered plugin user page. */
 export interface PluginUserPageDefinition {

package/package.json

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

package/src/context.ts

@@ -2,12 +2,14 @@ import { z } from "zod";
 import type { ZodTypeAny } from "zod";
 import {
   destinationSchema,
+  identitySchema,
   localActorSchema,
   platformSchema,
   actorSchema,
   slackActorSchema,
   systemActorSchema,
   sourceSchema,
+  userSchema,
 } from "./schemas";
 
 /** Runtime platform name without source or destination coordinates. */
@@ -16,6 +18,8 @@ export type Actor = z.output<typeof actorSchema>;
 export type SlackActor = z.output<typeof slackActorSchema>;
 export type LocalActor = z.output<typeof localActorSchema>;
 export type SystemActor = z.output<typeof systemActorSchema>;
+export type Identity = z.output<typeof identitySchema>;
+export type User = z.output<typeof userSchema>;
 export type Source = z.output<typeof sourceSchema>;
 export type SlackSource = Extract<Source, { platform: "slack" }>;
 export type LocalSource = Extract<Source, { platform: "local" }>;

package/src/operations.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { LocalActor, PluginContext, SlackActor } from "./context";
+import type { PluginContext, User } from "./context";
 import type { Dispatch, DispatchOptions, DispatchResult } from "./dispatch";
 import { nonBlankStringSchema } from "./schemas";
 import type { PluginReadState, PluginState } from "./state";
@@ -124,9 +124,9 @@ export interface RouteRegistrationHookContext extends PluginContext {
 
 export interface ApiRouteRegistrationHookContext extends PluginContext {
   eventStats: PluginConversationEventStats;
-  viewer: {
-    /** Resolve every runtime actor linked to one authenticated viewer email. */
-    actors(email: string): Promise<Array<LocalActor | SlackActor>>;
+  users: {
+    /** Resolve or create the canonical user for one verified email. */
+    resolve(email: string): Promise<User | undefined>;
   };
 }
 

package/src/registration.ts

@@ -4,6 +4,10 @@ import type { PluginHooks } from "./hooks";
 import type { PluginManifest } from "./manifest";
 import type { PluginTasks } from "./tasks";
 import type { PluginUserPageDefinition } from "./user-pages";
+import {
+  pluginResourceEventsSchema,
+  type PluginResourceEvents,
+} from "./resource-events";
 
 export interface PluginModelConfig {
   /** Host model family used when no explicit structured model id is configured. */
@@ -19,6 +23,7 @@ export type PluginRegistrationInput = {
   manifest: PluginManifest;
   model?: PluginModelConfig;
   packageName?: string;
+  resourceEvents?: PluginResourceEvents;
   tasks?: PluginTasks;
   userPages?: PluginUserPageDefinition[];
 };
@@ -87,6 +92,14 @@ export function defineJuniorPlugin(
       `Junior plugin "${name}" conversationEvents must be an array.`,
     );
   }
+  if (plugin.resourceEvents !== undefined) {
+    const parsed = pluginResourceEventsSchema.safeParse(plugin.resourceEvents);
+    if (!parsed.success) {
+      throw new Error(`Junior plugin "${name}" resourceEvents is invalid.`, {
+        cause: parsed.error,
+      });
+    }
+  }
   const conversationEventIds = new Set<string>();
   for (const event of plugin.conversationEvents ?? []) {
     if (

package/src/resource-events.ts

@@ -1,34 +1,145 @@
 import { z } from "zod";
 
+export const RESOURCE_EVENT_SUMMARY_MAX_LENGTH = 4_000;
+export const RESOURCE_EVENT_TEXT_MAX_LENGTH = 8_000;
+
+/** Canonical dotted event type published and selected across plugins. */
+export const resourceEventTypeSchema = z
+  .string()
+  .regex(/^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)+$/)
+  .describe(
+    "Canonical dotted event type, such as issue.closed or pull_request.review.changes_requested.",
+  );
+
+export const resourceTypeSchema = z
+  .string()
+  .regex(/^[a-z][a-z0-9_]*$/)
+  .describe(
+    "Canonical plugin-defined resource type, such as issue or pull_request.",
+  );
+
+export const pluginResourceEventTypeSchema = z
+  .object({
+    type: resourceTypeSchema,
+    supportedEvents: z.array(resourceEventTypeSchema).min(1),
+    suggestedEvents: z.array(resourceEventTypeSchema).optional(),
+  })
+  .strict()
+  .superRefine((resourceType, context) => {
+    const supported = new Set<string>();
+    resourceType.supportedEvents.forEach((eventType, index) => {
+      if (supported.has(eventType)) {
+        context.addIssue({
+          code: "custom",
+          message: `Duplicate supported resource event type "${eventType}".`,
+          path: ["supportedEvents", index],
+        });
+      }
+      supported.add(eventType);
+    });
+    const suggested = new Set<string>();
+    resourceType.suggestedEvents?.forEach((eventType, index) => {
+      if (suggested.has(eventType)) {
+        context.addIssue({
+          code: "custom",
+          message: `Duplicate suggested resource event type "${eventType}".`,
+          path: ["suggestedEvents", index],
+        });
+      }
+      if (!supported.has(eventType)) {
+        context.addIssue({
+          code: "custom",
+          message: `Suggested resource event type "${eventType}" is not supported.`,
+          path: ["suggestedEvents", index],
+        });
+      }
+      suggested.add(eventType);
+    });
+  });
+
+export const pluginResourceEventsSchema = z
+  .object({
+    resourceTypes: z.array(pluginResourceEventTypeSchema).min(1),
+    isEnabled: z.function({ input: [], output: z.boolean() }).optional(),
+    normalizeIdentifier: z
+      .function({ input: [z.string()], output: z.string() })
+      .optional(),
+  })
+  .strict()
+  .superRefine((registration, context) => {
+    const seen = new Set<string>();
+    registration.resourceTypes.forEach((resourceType, index) => {
+      if (seen.has(resourceType.type)) {
+        context.addIssue({
+          code: "custom",
+          message: `Duplicate resource type "${resourceType.type}".`,
+          path: ["resourceTypes", index, "type"],
+        });
+      }
+      seen.add(resourceType.type);
+    });
+  });
+
+export type PluginResourceEventType = z.output<
+  typeof pluginResourceEventTypeSchema
+>;
+export type PluginResourceEvents = z.output<typeof pluginResourceEventsSchema>;
+
+/** Apply a plugin's identifier convention at resource-event boundaries. */
+export function normalizeResourceEventIdentifier(
+  registration: Pick<PluginResourceEvents, "normalizeIdentifier"> | undefined,
+  identifier: string,
+): string {
+  const trimmed = identifier.trim();
+  const normalized = (
+    registration?.normalizeIdentifier?.(trimmed) ?? trimmed
+  ).trim();
+  if (!normalized) {
+    throw new Error("Resource event identifier must not normalize to empty");
+  }
+  return normalized;
+}
+
 export const subscribableResourceSchema = z
   .object({
+    identifier: z.string().min(1),
     label: z.string().min(1),
-    provider: z.string().min(1),
-    resourceRef: z.string().min(1),
-    suggestedEvents: z.array(z.string().min(1)).optional(),
-    supportedEvents: z.array(z.string().min(1)),
-    type: z.string().min(1),
+    namespace: z.string().min(1),
+    suggestedEvents: z.array(resourceEventTypeSchema).optional(),
+    supportedEvents: z.array(resourceEventTypeSchema),
+    type: resourceTypeSchema,
   })
   .strict();
 
 export type SubscribableResource = z.output<typeof subscribableResourceSchema>;
 
-export const resourceEventSchema = z
+export const resourceEventInputSchema = z
   .object({
     eventKey: z.string().min(1),
-    eventType: z.string().min(1),
+    eventType: resourceEventTypeSchema,
+    identifier: z.string().min(1),
     occurredAtMs: z.number().finite(),
-    provider: z.string().min(1),
-    resourceRef: z.string().min(1),
     terminal: z.boolean().optional(),
-    trustedSummary: z.string().min(1),
-    untrustedText: z.string().optional(),
+    trustedSummary: z
+      .string()
+      .min(1)
+      .transform((value) => value.slice(0, RESOURCE_EVENT_SUMMARY_MAX_LENGTH)),
+    untrustedText: z
+      .string()
+      .transform((value) => value.slice(0, RESOURCE_EVENT_TEXT_MAX_LENGTH))
+      .optional(),
   })
   .strict();
 
+export type ResourceEventInput = z.output<typeof resourceEventInputSchema>;
+
+export const resourceEventSchema = resourceEventInputSchema.extend({
+  namespace: z.string().min(1),
+});
+
 export type ResourceEvent = z.output<typeof resourceEventSchema>;
 
 export interface ResourceEventPublisher {
-  /** Publish one normalized event whose provider matches the owning plugin name. */
-  publish(event: ResourceEvent): Promise<void>;
+  /** Publish one normalized event under the owning plugin's namespace. */
+  publish(event: ResourceEventInput): Promise<void>;
 }

package/src/schemas.ts

@@ -136,6 +136,28 @@ export const actorSchema = z.discriminatedUnion("platform", [
   systemActorSchema,
 ]);
 
+/** Core-owned provider account linked to a user when verified. */
+export const identitySchema = z
+  .object({
+    displayName: nonBlankStringSchema.optional(),
+    handle: nonBlankStringSchema.optional(),
+    id: exactNonBlankStringSchema,
+    provider: exactNonBlankStringSchema,
+    providerSubjectId: exactNonBlankStringSchema,
+    providerTenantId: exactNonBlankStringSchema.optional(),
+  })
+  .strict();
+
+/** Core-owned person with every linked provider identity. */
+export const userSchema = z
+  .object({
+    displayName: nonBlankStringSchema.optional(),
+    email: nonBlankStringSchema.max(320),
+    id: exactNonBlankStringSchema,
+    identities: z.array(identitySchema).max(100),
+  })
+  .strict();
+
 const dispatchMetadataSchema = z
   .record(z.string(), z.string())
   .superRefine((metadata, ctx) => {

package/src/tools.ts

@@ -2,15 +2,17 @@ import type {
   PluginContext,
   LocalInvocationContext,
   PluginEmbedder,
+  Identity,
   PluginModel,
   Actor,
   SlackInvocationContext,
+  User,
 } from "./context";
 import type { PluginCredentialSubject } from "./credentials";
 import type { PluginAnnotations } from "./annotations";
 import type { SlackConversationLink } from "./operations";
 import type { PluginState } from "./state";
-import { z, type ZodType, type ZodTypeAny } from "zod";
+import { z, type ZodTypeAny } from "zod";
 
 export interface PluginEnv {
   get(key: string): string | undefined;
@@ -81,8 +83,8 @@ export const pluginToolContentSchema = z.discriminatedUnion("type", [
 /** Model-visible content returned by a plugin tool. */
 export type PluginToolContent = z.output<typeof pluginToolContentSchema>;
 
-/** Standard tool result envelope with separate model content and runtime details. */
-export interface PluginToolResultEnvelope<TDetails = PluginToolResult> {
+/** Pi-native projection with model-facing content and canonical runtime details. */
+export interface PluginToolOutputEnvelope<TDetails = unknown> {
   content: PluginToolContent[];
   details: TDetails;
 }
@@ -194,27 +196,16 @@ export const pluginToolContinuationSchema = z
   })
   .strict();
 
-export const pluginToolErrorSchema = z
+/** Shared optional fields for canonical plugin tool outputs. */
+export const pluginToolOutputSchema = z
   .object({
-    kind: z.string().min(1),
-    message: z.string().min(1),
-    retryable: z.boolean().optional(),
-  })
-  .strict();
-
-export const pluginToolResultSchema = z
-  .object({
-    ok: z.boolean(),
-    status: z.enum(["success", "error"]),
     target: z.string().min(1).optional(),
-    data: z.unknown().optional(),
     truncated: z.boolean().optional(),
     continuation: pluginToolContinuationSchema.optional(),
-    error: z.union([pluginToolErrorSchema, z.string()]).optional(),
   })
   .passthrough();
 
-export type PluginToolResult = z.output<typeof pluginToolResultSchema>;
+export type PluginToolOutput = z.output<typeof pluginToolOutputSchema>;
 
 export type PluginToolExecute<TInput = unknown, TOutput = unknown> = {
   bivarianceHack(
@@ -320,10 +311,10 @@ export interface PluginToolDefinition<
 
 type ZodPluginToolDefinition<
   TInputSchema extends ZodTypeAny,
-  TOutputSchema extends ZodType<PluginToolResult>,
+  TOutputSchema extends ZodTypeAny,
   TExecuteResult extends
     | z.input<TOutputSchema>
-    | PluginToolResultEnvelope<z.input<TOutputSchema>>,
+    | PluginToolOutputEnvelope<z.input<TOutputSchema>>,
 > = Omit<
   PluginToolDefinition<z.output<TInputSchema>, z.output<TOutputSchema>>,
   "inputSchema" | "outputSchema" | "prepareArguments" | "execute"
@@ -338,13 +329,13 @@ type ZodPluginToolDefinition<
 };
 
 type ParsedPluginToolExecuteResult<TOutputSchema extends ZodTypeAny, TResult> =
-  TResult extends PluginToolResultEnvelope<unknown>
-    ? PluginToolResultEnvelope<z.output<TOutputSchema>>
+  TResult extends PluginToolOutputEnvelope<unknown>
+    ? PluginToolOutputEnvelope<z.output<TOutputSchema>>
     : z.output<TOutputSchema>;
 
-function isPluginToolResultEnvelope(
+function isPluginToolOutputEnvelope(
   value: unknown,
-): value is PluginToolResultEnvelope<unknown> {
+): value is PluginToolOutputEnvelope<unknown> {
   return (
     value !== null &&
     typeof value === "object" &&
@@ -380,10 +371,10 @@ function parsePluginToolInput<TInputSchema extends ZodTypeAny>(
 
 function createZodTool<
   TInputSchema extends ZodTypeAny,
-  TOutputSchema extends ZodType<PluginToolResult>,
+  TOutputSchema extends ZodTypeAny,
   TExecuteResult extends
     | z.input<TOutputSchema>
-    | PluginToolResultEnvelope<z.input<TOutputSchema>>,
+    | PluginToolOutputEnvelope<z.input<TOutputSchema>>,
 >(
   definition: ZodPluginToolDefinition<
     TInputSchema,
@@ -434,15 +425,13 @@ function createZodTool<
               input as z.output<TInputSchema>,
               options,
             );
-            if (isPluginToolResultEnvelope(result)) {
+            if (isPluginToolOutputEnvelope(result)) {
               return {
                 content: z.array(pluginToolContentSchema).parse(result.content),
-                details: outputSchema.parse(
-                  pluginToolResultSchema.parse(result.details),
-                ),
+                details: outputSchema.parse(result.details),
               };
             }
-            return outputSchema.parse(pluginToolResultSchema.parse(result));
+            return outputSchema.parse(result);
           },
         }
       : {}),
@@ -456,10 +445,10 @@ function createZodTool<
 /** Define a plugin tool with Zod input parsing and validated structured results. */
 export function zodTool<
   TInputSchema extends ZodTypeAny,
-  TOutputSchema extends ZodType<PluginToolResult>,
+  TOutputSchema extends ZodTypeAny,
   TExecuteResult extends
     | z.input<TOutputSchema>
-    | PluginToolResultEnvelope<z.input<TOutputSchema>>,
+    | PluginToolOutputEnvelope<z.input<TOutputSchema>>,
 >(
   definition: ZodPluginToolDefinition<
     TInputSchema,
@@ -477,10 +466,10 @@ export function zodTool<
 /** Define a plugin tool with Zod input parsing and the structured result contract. */
 export function definePluginTool<
   TInputSchema extends ZodTypeAny,
-  TOutputSchema extends ZodType<PluginToolResult>,
+  TOutputSchema extends ZodTypeAny,
   TExecuteResult extends
     | z.input<TOutputSchema>
-    | PluginToolResultEnvelope<z.input<TOutputSchema>>,
+    | PluginToolOutputEnvelope<z.input<TOutputSchema>>,
 >(
   definition: ZodPluginToolDefinition<
     TInputSchema,
@@ -513,6 +502,11 @@ export interface SlackToolRegistrationHookContext {
   >;
 }
 
+export interface PluginResourceEventToolContext {
+  /** Whether this invocation can create a working resource-event subscription. */
+  canSubscribe: boolean;
+}
+
 interface BaseToolRegistrationHookContext extends PluginContext {
   /**
    * Opaque Junior conversation/session identity for this turn.
@@ -526,7 +520,12 @@ interface BaseToolRegistrationHookContext extends PluginContext {
   egress: PluginEgress;
   mcp?: PluginMcp;
   model: PluginModel;
+  resourceEvents: PluginResourceEventToolContext;
   state: PluginState;
+  users: {
+    /** Resolve the current actor's stored identity and linked user. */
+    resolveActor(): Promise<{ identity: Identity; user?: User } | undefined>;
+  };
   userText?: string;
 }
 

package/src/user-pages.ts

@@ -5,7 +5,7 @@
  * routing, response validation, and browser rendering.
  */
 import { z } from "zod";
-import type { LocalActor, PluginContext, SlackActor } from "./context";
+import type { PluginContext, User } from "./context";
 import { nonBlankStringSchema } from "./schemas";
 
 const userPageIdSchema = nonBlankStringSchema
@@ -98,15 +98,9 @@ export const pluginUserPageInputSchema = z
 
 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. */
 export interface PluginUserPageContext extends PluginContext {
-  viewer: {
-    actors: PluginUserPageActor[];
-    email: string;
-  };
+  viewer: User;
 }
 
 /** Navigation metadata and reader for one core-rendered plugin user page. */