@sentry/junior-plugin-api 0.120.0 → 0.122.0

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[];
@@ -206,7 +214,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 +237,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.120.0",
+  "version": "0.122.0",
   "private": false,
   "publishConfig": {
     "access": "public"

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 = {
@@ -234,6 +252,7 @@ export interface ToolApprovalMetadata<TInput = unknown> {
 export interface PluginToolDefinition<
   TInput = unknown,
   TOutput = unknown,
+  TExecuteOutput = TOutput,
 > extends ToolApprovalMetadata<TInput> {
   description: string;
   executionMode?: unknown;
@@ -257,12 +276,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 +295,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 +342,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 +394,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 +438,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");
 }