@sentry/junior-plugin-api 0.127.0 → 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) {
@@ -429,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 = [
@@ -455,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) {
@@ -511,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);
       }
     } : {}
   };
@@ -801,6 +804,7 @@ export {
   destinationVisibilitySchema,
   dispatchOptionsSchema,
   getSourceKey,
+  identitySchema,
   isPrivateSource,
   isSlackDestination,
   localActorSchema,
@@ -826,8 +830,7 @@ export {
   pluginStoredTokensSchema,
   pluginToolContentSchema,
   pluginToolContinuationSchema,
-  pluginToolErrorSchema,
-  pluginToolResultSchema,
+  pluginToolOutputSchema,
   pluginUserPageContentSchema,
   pluginUserPageInputSchema,
   pluginUserPageLinkSchema,
@@ -848,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/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.127.0",
+  "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/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. */