@sentry/junior-plugin-api 0.121.0 → 0.122.1

package/dist/hooks.d.ts

@@ -1,11 +1,18 @@
 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 { AfterMcpToolHookContext, BeforeToolExecuteHookContext, PluginToolDefinition, SandboxPrepareHookContext, ToolRegistrationHookContext } from "./tools";
 import type { PromptMessage, SystemPromptContext, UserPromptContext, UserPromptContribution } from "./prompt";
 export interface PluginHooks {
     systemPrompt?(ctx: SystemPromptContext): Promise<PromptMessage[]> | PromptMessage[];
     userPrompt?(ctx: UserPromptContext): Promise<UserPromptContribution[] | undefined> | UserPromptContribution[] | undefined;
     beforeToolExecute?(ctx: BeforeToolExecuteHookContext): Promise<void> | void;
+    /**
+     * Run after a successful hosted MCP tool call.
+     *
+     * Prefer this for junior-owned side effects such as conversation annotations.
+     * Do not use it to invent a parallel tool contract for the provider tool.
+     */
+    afterMcpTool?(ctx: AfterMcpToolHookContext): Promise<void> | void;
     grantForEgress?(ctx: EgressHookContext): Promise<PluginGrant | undefined> | PluginGrant | undefined;
     heartbeat?(ctx: HeartbeatHookContext): Promise<HeartbeatResult | void> | HeartbeatResult | void;
     issueCredential?(ctx: IssueCredentialHookContext): Promise<PluginCredentialResult> | PluginCredentialResult;

package/dist/index.js

@@ -291,6 +291,14 @@ var PluginToolInputError = class extends Error {
     this.name = "PluginToolInputError";
   }
 };
+var pluginToolContentSchema = z6.discriminatedUnion("type", [
+  z6.object({ type: z6.literal("text"), text: z6.string() }).strict(),
+  z6.object({
+    type: z6.literal("image"),
+    data: z6.string(),
+    mimeType: z6.string()
+  }).strict()
+]);
 var pluginToolContinuationSchema = z6.object({
   arguments: z6.record(z6.string(), z6.unknown()),
   reason: z6.string().min(1).optional()
@@ -310,6 +318,9 @@ var pluginToolResultSchema = z6.object({
   error: z6.union([pluginToolErrorSchema, z6.string()]).optional()
 }).passthrough();
 var toolApprovalModeSchema = z6.enum(["auto", "review", "approve"]);
+function isPluginToolResultEnvelope(value) {
+  return value !== null && typeof value === "object" && Array.isArray(value.content) && "details" in value;
+}
 function formatZodPath(path) {
   return path.length > 0 ? path.map(String).join(".") : "root";
 }
@@ -362,6 +373,14 @@ function createZodTool(definition, helperName) {
           input,
           options
         );
+        if (isPluginToolResultEnvelope(result)) {
+          return {
+            content: z6.array(pluginToolContentSchema).parse(result.content),
+            details: outputSchema.parse(
+              pluginToolResultSchema.parse(result.details)
+            )
+          };
+        }
         return outputSchema.parse(pluginToolResultSchema.parse(result));
       }
     } : {}
@@ -609,6 +628,7 @@ export {
   pluginRunTranscriptEntrySchema,
   pluginRunTranscriptProvenanceSchema,
   pluginStoredTokensSchema,
+  pluginToolContentSchema,
   pluginToolContinuationSchema,
   pluginToolErrorSchema,
   pluginToolResultSchema,

package/dist/tools.d.ts

@@ -53,14 +53,22 @@ export interface PluginEgress {
         request: Request;
     }): Promise<Response>;
 }
-export type PluginMcpContent = {
-    type: "text";
-    text: string;
-} | {
-    type: "image";
-    data: string;
-    mimeType: string;
-};
+export declare const pluginToolContentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"image">;
+    data: z.ZodString;
+    mimeType: z.ZodString;
+}, 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> {
+    content: PluginToolContent[];
+    details: TDetails;
+}
+export type PluginMcpContent = PluginToolContent;
 /** Successful raw provider result returned to a plugin-owned wrapper tool. */
 export type PluginMcpToolSuccess = {
     content: PluginMcpContent[];
@@ -115,6 +123,29 @@ export interface BeforeToolExecuteHookContext extends PluginContext {
         name: string;
     };
 }
+/**
+ * Context for post-success MCP tool processing.
+ *
+ * Runs after a hosted MCP tool succeeds on the model-facing path. Use for
+ * junior-owned side effects such as conversation annotations without replacing
+ * the provider tool contract.
+ */
+export interface AfterMcpToolHookContext extends PluginContext {
+    /**
+     * Opaque Junior conversation/session identity for this turn.
+     * Interactive Slack turns use `slack:{channelId}:{threadTs}`.
+     */
+    conversationId?: string;
+    annotations?: PluginAnnotations;
+    result: {
+        structuredContent?: unknown;
+    };
+    tool: {
+        arguments: Record<string, unknown>;
+        /** Provider-local MCP tool name, for example `save_issue`. */
+        name: string;
+    };
+}
 export interface PluginToolExecuteOptions {
     /**
      * @deprecated Internal compatibility escape hatch for legacy tool bridges.
@@ -206,7 +237,7 @@ export interface ToolApprovalMetadata<TInput = unknown> {
      */
     describeProposal?(input: TInput): string;
 }
-export interface PluginToolDefinition<TInput = unknown, TOutput = unknown> extends ToolApprovalMetadata<TInput> {
+export interface PluginToolDefinition<TInput = unknown, TOutput = unknown, TExecuteOutput = TOutput> extends ToolApprovalMetadata<TInput> {
     description: string;
     executionMode?: unknown;
     inputSchema: unknown;
@@ -229,18 +260,19 @@ export interface PluginToolDefinition<TInput = unknown, TOutput = unknown> exten
      * future major version.
      */
     promptSnippet?: string;
-    execute?: PluginToolExecute<TInput, TOutput>;
+    execute?: PluginToolExecute<TInput, TExecuteOutput>;
 }
-type ZodPluginToolDefinition<TInputSchema extends ZodTypeAny, TOutputSchema extends ZodType<PluginToolResult>> = Omit<PluginToolDefinition<z.output<TInputSchema>, z.output<TOutputSchema>>, "inputSchema" | "outputSchema" | "prepareArguments" | "execute"> & {
+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"> & {
     inputSchema: TInputSchema;
     outputSchema: TOutputSchema;
     prepareArguments?: (args: unknown) => z.input<TInputSchema>;
-    execute?: (input: z.output<TInputSchema>, options: PluginToolExecuteOptions) => Promise<z.input<TOutputSchema>> | z.input<TOutputSchema>;
+    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>;
 /** Define a plugin tool with Zod input parsing and validated structured results. */
-export declare function zodTool<TInputSchema extends ZodTypeAny, TOutputSchema extends ZodType<PluginToolResult>>(definition: ZodPluginToolDefinition<TInputSchema, TOutputSchema>): PluginToolDefinition<z.output<TInputSchema>, z.output<TOutputSchema>>;
+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>>;
 /** Define a plugin tool with Zod input parsing and the structured result contract. */
-export declare function definePluginTool<TInputSchema extends ZodTypeAny, TOutputSchema extends ZodType<PluginToolResult>>(definition: ZodPluginToolDefinition<TInputSchema, TOutputSchema>): PluginToolDefinition<z.output<TInputSchema>, z.output<TOutputSchema>>;
+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 interface SlackToolRegistrationHookContext {
     /**
      * Capabilities of the source Slack conversation exposed to this plugin.

package/package.json

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

package/src/hooks.ts

@@ -20,6 +20,7 @@ import type {
   SlackConversationLinkHookContext,
 } from "./operations";
 import type {
+  AfterMcpToolHookContext,
   BeforeToolExecuteHookContext,
   PluginToolDefinition,
   SandboxPrepareHookContext,
@@ -43,6 +44,13 @@ export interface PluginHooks {
     | UserPromptContribution[]
     | undefined;
   beforeToolExecute?(ctx: BeforeToolExecuteHookContext): Promise<void> | void;
+  /**
+   * Run after a successful hosted MCP tool call.
+   *
+   * Prefer this for junior-owned side effects such as conversation annotations.
+   * Do not use it to invent a parallel tool contract for the provider tool.
+   */
+  afterMcpTool?(ctx: AfterMcpToolHookContext): Promise<void> | void;
   grantForEgress?(
     ctx: EgressHookContext,
   ): Promise<PluginGrant | undefined> | PluginGrant | undefined;

package/src/tools.ts

@@ -67,9 +67,27 @@ export interface PluginEgress {
   }): Promise<Response>;
 }
 
-export type PluginMcpContent =
-  | { type: "text"; text: string }
-  | { type: "image"; data: string; mimeType: string };
+export const pluginToolContentSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("text"), text: z.string() }).strict(),
+  z
+    .object({
+      type: z.literal("image"),
+      data: z.string(),
+      mimeType: z.string(),
+    })
+    .strict(),
+]);
+
+/** 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> {
+  content: PluginToolContent[];
+  details: TDetails;
+}
+
+export type PluginMcpContent = PluginToolContent;
 
 /** Successful raw provider result returned to a plugin-owned wrapper tool. */
 export type PluginMcpToolSuccess = {
@@ -135,6 +153,30 @@ export interface BeforeToolExecuteHookContext extends PluginContext {
   };
 }
 
+/**
+ * Context for post-success MCP tool processing.
+ *
+ * Runs after a hosted MCP tool succeeds on the model-facing path. Use for
+ * junior-owned side effects such as conversation annotations without replacing
+ * the provider tool contract.
+ */
+export interface AfterMcpToolHookContext extends PluginContext {
+  /**
+   * Opaque Junior conversation/session identity for this turn.
+   * Interactive Slack turns use `slack:{channelId}:{threadTs}`.
+   */
+  conversationId?: string;
+  annotations?: PluginAnnotations;
+  result: {
+    structuredContent?: unknown;
+  };
+  tool: {
+    arguments: Record<string, unknown>;
+    /** Provider-local MCP tool name, for example `save_issue`. */
+    name: string;
+  };
+}
+
 export interface PluginToolExecuteOptions {
   /**
    * @deprecated Internal compatibility escape hatch for legacy tool bridges.
@@ -234,6 +276,7 @@ export interface ToolApprovalMetadata<TInput = unknown> {
 export interface PluginToolDefinition<
   TInput = unknown,
   TOutput = unknown,
+  TExecuteOutput = TOutput,
 > extends ToolApprovalMetadata<TInput> {
   description: string;
   executionMode?: unknown;
@@ -257,12 +300,15 @@ export interface PluginToolDefinition<
    * future major version.
    */
   promptSnippet?: string;
-  execute?: PluginToolExecute<TInput, TOutput>;
+  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"
@@ -273,9 +319,25 @@ type ZodPluginToolDefinition<
   execute?: (
     input: z.output<TInputSchema>,
     options: PluginToolExecuteOptions,
-  ) => Promise<z.input<TOutputSchema>> | z.input<TOutputSchema>;
+  ) => Promise<TExecuteResult> | TExecuteResult;
 };
 
+type ParsedPluginToolExecuteResult<TOutputSchema extends ZodTypeAny, TResult> =
+  TResult extends PluginToolResultEnvelope<unknown>
+    ? PluginToolResultEnvelope<z.output<TOutputSchema>>
+    : z.output<TOutputSchema>;
+
+function isPluginToolResultEnvelope(
+  value: unknown,
+): value is PluginToolResultEnvelope<unknown> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    Array.isArray((value as { content?: unknown }).content) &&
+    "details" in value
+  );
+}
+
 function formatZodPath(path: readonly PropertyKey[]): string {
   return path.length > 0 ? path.map(String).join(".") : "root";
 }
@@ -304,10 +366,21 @@ function parsePluginToolInput<TInputSchema extends ZodTypeAny>(
 function createZodTool<
   TInputSchema extends ZodTypeAny,
   TOutputSchema extends ZodType<PluginToolResult>,
+  TExecuteResult extends
+    | z.input<TOutputSchema>
+    | PluginToolResultEnvelope<z.input<TOutputSchema>>,
 >(
-  definition: ZodPluginToolDefinition<TInputSchema, TOutputSchema>,
+  definition: ZodPluginToolDefinition<
+    TInputSchema,
+    TOutputSchema,
+    TExecuteResult
+  >,
   helperName: "definePluginTool" | "zodTool",
-): PluginToolDefinition<z.output<TInputSchema>, z.output<TOutputSchema>> {
+): PluginToolDefinition<
+  z.output<TInputSchema>,
+  z.output<TOutputSchema>,
+  ParsedPluginToolExecuteResult<TOutputSchema, TExecuteResult>
+> {
   const { inputSchema, outputSchema, prepareArguments, execute, ...tool } =
     definition;
   let modelInputSchema: unknown;
@@ -345,20 +418,43 @@ function createZodTool<
               input as z.output<TInputSchema>,
               options,
             );
+            if (isPluginToolResultEnvelope(result)) {
+              return {
+                content: z.array(pluginToolContentSchema).parse(result.content),
+                details: outputSchema.parse(
+                  pluginToolResultSchema.parse(result.details),
+                ),
+              };
+            }
             return outputSchema.parse(pluginToolResultSchema.parse(result));
           },
         }
       : {}),
-  };
+  } as PluginToolDefinition<
+    z.output<TInputSchema>,
+    z.output<TOutputSchema>,
+    ParsedPluginToolExecuteResult<TOutputSchema, TExecuteResult>
+  >;
 }
 
 /** Define a plugin tool with Zod input parsing and validated structured results. */
 export function zodTool<
   TInputSchema extends ZodTypeAny,
   TOutputSchema extends ZodType<PluginToolResult>,
+  TExecuteResult extends
+    | z.input<TOutputSchema>
+    | PluginToolResultEnvelope<z.input<TOutputSchema>>,
 >(
-  definition: ZodPluginToolDefinition<TInputSchema, TOutputSchema>,
-): PluginToolDefinition<z.output<TInputSchema>, z.output<TOutputSchema>> {
+  definition: ZodPluginToolDefinition<
+    TInputSchema,
+    TOutputSchema,
+    TExecuteResult
+  >,
+): PluginToolDefinition<
+  z.output<TInputSchema>,
+  z.output<TOutputSchema>,
+  ParsedPluginToolExecuteResult<TOutputSchema, TExecuteResult>
+> {
   return createZodTool(definition, "zodTool");
 }
 
@@ -366,9 +462,20 @@ export function zodTool<
 export function definePluginTool<
   TInputSchema extends ZodTypeAny,
   TOutputSchema extends ZodType<PluginToolResult>,
+  TExecuteResult extends
+    | z.input<TOutputSchema>
+    | PluginToolResultEnvelope<z.input<TOutputSchema>>,
 >(
-  definition: ZodPluginToolDefinition<TInputSchema, TOutputSchema>,
-): PluginToolDefinition<z.output<TInputSchema>, z.output<TOutputSchema>> {
+  definition: ZodPluginToolDefinition<
+    TInputSchema,
+    TOutputSchema,
+    TExecuteResult
+  >,
+): PluginToolDefinition<
+  z.output<TInputSchema>,
+  z.output<TOutputSchema>,
+  ParsedPluginToolExecuteResult<TOutputSchema, TExecuteResult>
+> {
   return createZodTool(definition, "definePluginTool");
 }