@sentry/junior-plugin-api 0.89.0 → 0.90.0

package/dist/index.js

@@ -196,82 +196,158 @@ var pluginRunContextSchema = z4.object({
 }).strict();
 
 // src/tools.ts
+import { z as z5 } from "zod";
 var PluginToolInputError = class extends Error {
   constructor(message, options) {
     super(message, options);
     this.name = "PluginToolInputError";
   }
 };
+var pluginToolContinuationSchema = z5.object({
+  arguments: z5.record(z5.string(), z5.unknown()),
+  reason: z5.string().min(1).optional()
+}).strict();
+var pluginToolErrorSchema = z5.object({
+  kind: z5.string().min(1),
+  message: z5.string().min(1),
+  retryable: z5.boolean().optional()
+}).strict();
+var pluginToolResultSchema = z5.object({
+  ok: z5.boolean(),
+  status: z5.enum(["success", "error"]),
+  target: z5.string().min(1).optional(),
+  data: z5.unknown().optional(),
+  truncated: z5.boolean().optional(),
+  continuation: pluginToolContinuationSchema.optional(),
+  error: z5.union([pluginToolErrorSchema, z5.string()]).optional()
+}).passthrough();
+function formatZodPath(path) {
+  return path.length > 0 ? path.map(String).join(".") : "root";
+}
+function formatPluginToolInputError(error) {
+  const details = error.issues.slice(0, 5).map((issue) => `${formatZodPath(issue.path)}: ${issue.message}`).join("; ");
+  return `Invalid tool arguments: ${details || "input did not match schema"}`;
+}
+function parsePluginToolInput(schema, args) {
+  const result = schema.safeParse(args);
+  if (!result.success) {
+    throw new PluginToolInputError(formatPluginToolInputError(result.error), {
+      cause: result.error
+    });
+  }
+  return result.data;
+}
+function definePluginTool(definition) {
+  const { inputSchema, outputSchema, prepareArguments, execute, ...tool } = definition;
+  let modelInputSchema;
+  let modelOutputSchema;
+  try {
+    modelInputSchema = z5.toJSONSchema(inputSchema);
+  } catch (error) {
+    throw new TypeError(
+      "definePluginTool() inputSchema must be representable as JSON Schema.",
+      { cause: error }
+    );
+  }
+  try {
+    modelOutputSchema = z5.toJSONSchema(outputSchema);
+  } catch (error) {
+    throw new TypeError(
+      "definePluginTool() outputSchema must be representable as JSON Schema.",
+      { cause: error }
+    );
+  }
+  return {
+    ...tool,
+    inputSchema: modelInputSchema,
+    outputSchema: modelOutputSchema,
+    prepareArguments(args) {
+      return parsePluginToolInput(
+        inputSchema,
+        prepareArguments ? prepareArguments(args) : args
+      );
+    },
+    ...execute ? {
+      async execute(input, options) {
+        const result = await execute(
+          input,
+          options
+        );
+        return outputSchema.parse(pluginToolResultSchema.parse(result));
+      }
+    } : {}
+  };
+}
 
 // src/operations.ts
-import { z as z5 } from "zod";
-var pluginApiRouteRequestContextSchema = z5.object({
-  auth: z5.object({
-    user: z5.object({
-      email: z5.string().nullable().optional(),
-      emailVerified: z5.boolean().optional(),
-      hostedDomain: z5.string().nullable().optional(),
-      name: z5.string().nullable().optional()
+import { z as z6 } from "zod";
+var pluginApiRouteRequestContextSchema = z6.object({
+  auth: z6.object({
+    user: z6.object({
+      email: z6.string().nullable().optional(),
+      emailVerified: z6.boolean().optional(),
+      hostedDomain: z6.string().nullable().optional(),
+      name: z6.string().nullable().optional()
     }).strict()
   }).strict(),
   pluginName: nonBlankStringSchema
 }).strict();
 
 // src/credentials.ts
-import { z as z6 } from "zod";
-var pluginProviderNameSchema = z6.string().regex(/^[a-z][a-z0-9-]*$/);
-var pluginGrantNameSchema = z6.string().regex(/^[a-z][a-z0-9.-]*$/);
-var pluginGrantAccessSchema = z6.union([
-  z6.literal("read"),
-  z6.literal("write")
+import { z as z7 } from "zod";
+var pluginProviderNameSchema = z7.string().regex(/^[a-z][a-z0-9-]*$/);
+var pluginGrantNameSchema = z7.string().regex(/^[a-z][a-z0-9.-]*$/);
+var pluginGrantAccessSchema = z7.union([
+  z7.literal("read"),
+  z7.literal("write")
 ]);
-var pluginAuthorizationSchema = z6.object({
+var pluginAuthorizationSchema = z7.object({
   provider: pluginProviderNameSchema,
   scope: nonBlankStringSchema.optional(),
-  type: z6.literal("oauth")
+  type: z7.literal("oauth")
 }).strict();
-var pluginProviderAccountSchema = z6.object({
+var pluginProviderAccountSchema = z7.object({
   id: nonBlankStringSchema,
   label: nonBlankStringSchema.optional(),
   url: nonBlankStringSchema.optional()
 }).strict();
-var pluginStoredTokensSchema = z6.object({
+var pluginStoredTokensSchema = z7.object({
   account: pluginProviderAccountSchema.optional(),
   accessToken: nonBlankStringSchema,
-  expiresAt: z6.number().finite().optional(),
+  expiresAt: z7.number().finite().optional(),
   refreshToken: nonBlankStringSchema,
-  refreshTokenExpiresAt: z6.number().finite().optional(),
+  refreshTokenExpiresAt: z7.number().finite().optional(),
   scope: nonBlankStringSchema.optional()
 }).strict();
-var pluginGrantSchema = z6.object({
+var pluginGrantSchema = z7.object({
   access: pluginGrantAccessSchema,
   name: pluginGrantNameSchema,
   reason: nonBlankStringSchema.optional(),
-  requirements: z6.array(nonBlankStringSchema).min(1).optional()
+  requirements: z7.array(nonBlankStringSchema).min(1).optional()
 }).strict();
-var pluginCredentialHeaderTransformSchema = z6.object({
-  domain: z6.string().min(1),
-  headers: z6.record(z6.string(), z6.string()).refine((headers) => Object.keys(headers).length > 0)
+var pluginCredentialHeaderTransformSchema = z7.object({
+  domain: z7.string().min(1),
+  headers: z7.record(z7.string(), z7.string()).refine((headers) => Object.keys(headers).length > 0)
 }).strict();
-var pluginCredentialLeaseSchema = z6.object({
+var pluginCredentialLeaseSchema = z7.object({
   account: pluginProviderAccountSchema.optional(),
   authorization: pluginAuthorizationSchema.optional(),
-  expiresAt: z6.string().refine((value) => Number.isFinite(Date.parse(value))),
-  headerTransforms: z6.array(pluginCredentialHeaderTransformSchema).min(1)
+  expiresAt: z7.string().refine((value) => Number.isFinite(Date.parse(value))),
+  headerTransforms: z7.array(pluginCredentialHeaderTransformSchema).min(1)
 }).strict();
-var pluginCredentialResultSchema = z6.discriminatedUnion("type", [
-  z6.object({
+var pluginCredentialResultSchema = z7.discriminatedUnion("type", [
+  z7.object({
     lease: pluginCredentialLeaseSchema,
-    type: z6.literal("lease")
+    type: z7.literal("lease")
   }).strict(),
-  z6.object({
+  z7.object({
     authorization: pluginAuthorizationSchema.optional(),
     message: nonBlankStringSchema,
-    type: z6.literal("needed")
+    type: z7.literal("needed")
   }).strict(),
-  z6.object({
+  z7.object({
     message: nonBlankStringSchema,
-    type: z6.literal("unavailable")
+    type: z7.literal("unavailable")
   }).strict()
 ]);
 var EgressAuthRequired = class extends Error {
@@ -336,6 +412,7 @@ export {
   createLocalSource,
   createSlackSource,
   defineJuniorPlugin,
+  definePluginTool,
   destinationSchema,
   dispatchOptionsSchema,
   getSourceKey,
@@ -357,6 +434,9 @@ export {
   pluginRunContextSchema,
   pluginRunTranscriptEntrySchema,
   pluginStoredTokensSchema,
+  pluginToolContinuationSchema,
+  pluginToolErrorSchema,
+  pluginToolResultSchema,
   promptMessageSchema,
   requesterSchema,
   slackDestinationSchema,

package/dist/tools.d.ts

@@ -1,6 +1,7 @@
 import type { PluginContext, LocalInvocationContext, PluginEmbedder, PluginModel, Requester, SlackInvocationContext } from "./context";
 import type { PluginCredentialSubject } from "./credentials";
 import type { PluginState } from "./state";
+import { z, type ZodType, type ZodTypeAny } from "zod";
 export interface PluginEnv {
     get(key: string): string | undefined;
     set(key: string, value: string): void;
@@ -72,14 +73,44 @@ export interface PluginToolExecuteOptions {
     /** Stable runtime tool-call id; durable create tools should derive idempotency keys from it. */
     toolCallId?: string;
 }
-export type PluginToolExecute<TInput = unknown> = {
-    bivarianceHack(input: TInput, options: PluginToolExecuteOptions): Promise<unknown> | unknown;
+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";
+    }>;
+    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 PluginToolExecute<TInput = unknown, TOutput = unknown> = {
+    bivarianceHack(input: TInput, options: PluginToolExecuteOptions): Promise<TOutput> | TOutput;
 }["bivarianceHack"];
-export interface PluginToolDefinition<TInput = unknown> {
+export interface PluginToolDefinition<TInput = unknown, TOutput = unknown> {
     annotations?: unknown;
     description: string;
     executionMode?: unknown;
     inputSchema: unknown;
+    outputSchema?: unknown;
     prepareArguments?: (args: unknown) => unknown;
     /**
      * @deprecated Put tool-selection and usage guidance directly in `description`
@@ -93,8 +124,18 @@ export interface PluginToolDefinition<TInput = unknown> {
      * future major version.
      */
     promptSnippet?: string;
-    execute?: PluginToolExecute<TInput>;
+    execute?: PluginToolExecute<TInput, TOutput>;
 }
+type ZodPluginToolDefinition<TInputSchema extends ZodTypeAny, TOutputSchema extends ZodType<PluginToolResult>> = 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>;
+};
+/**
+ * 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 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.89.0",
+  "version": "0.90.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/src/tools.ts

@@ -8,6 +8,7 @@ import type {
 } from "./context";
 import type { PluginCredentialSubject } from "./credentials";
 import type { PluginState } from "./state";
+import { z, type ZodType, type ZodTypeAny } from "zod";
 
 export interface PluginEnv {
   get(key: string): string | undefined;
@@ -89,18 +90,48 @@ export interface PluginToolExecuteOptions {
   toolCallId?: string;
 }
 
-export type PluginToolExecute<TInput = unknown> = {
+export const pluginToolContinuationSchema = z
+  .object({
+    arguments: z.record(z.string(), z.unknown()),
+    reason: z.string().min(1).optional(),
+  })
+  .strict();
+
+export const pluginToolErrorSchema = 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 PluginToolExecute<TInput = unknown, TOutput = unknown> = {
   bivarianceHack(
     input: TInput,
     options: PluginToolExecuteOptions,
-  ): Promise<unknown> | unknown;
+  ): Promise<TOutput> | TOutput;
 }["bivarianceHack"];
 
-export interface PluginToolDefinition<TInput = unknown> {
+export interface PluginToolDefinition<TInput = unknown, TOutput = unknown> {
   annotations?: unknown;
   description: string;
   executionMode?: unknown;
   inputSchema: unknown;
+  outputSchema?: unknown;
   prepareArguments?: (args: unknown) => unknown;
   /**
    * @deprecated Put tool-selection and usage guidance directly in `description`
@@ -114,7 +145,101 @@ export interface PluginToolDefinition<TInput = unknown> {
    * future major version.
    */
   promptSnippet?: string;
-  execute?: PluginToolExecute<TInput>;
+  execute?: PluginToolExecute<TInput, TOutput>;
+}
+
+type ZodPluginToolDefinition<
+  TInputSchema extends ZodTypeAny,
+  TOutputSchema extends ZodType<PluginToolResult>,
+> = 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>;
+};
+
+function formatZodPath(path: readonly PropertyKey[]): string {
+  return path.length > 0 ? path.map(String).join(".") : "root";
+}
+
+function formatPluginToolInputError(error: z.ZodError): string {
+  const details = error.issues
+    .slice(0, 5)
+    .map((issue) => `${formatZodPath(issue.path)}: ${issue.message}`)
+    .join("; ");
+  return `Invalid tool arguments: ${details || "input did not match schema"}`;
+}
+
+function parsePluginToolInput<TInputSchema extends ZodTypeAny>(
+  schema: TInputSchema,
+  args: unknown,
+): z.output<TInputSchema> {
+  const result = schema.safeParse(args);
+  if (!result.success) {
+    throw new PluginToolInputError(formatPluginToolInputError(result.error), {
+      cause: result.error,
+    });
+  }
+  return result.data;
+}
+
+/**
+ * Define a plugin tool with Zod input parsing and the structured result contract.
+ */
+export function definePluginTool<
+  TInputSchema extends ZodTypeAny,
+  TOutputSchema extends ZodType<PluginToolResult>,
+>(
+  definition: ZodPluginToolDefinition<TInputSchema, TOutputSchema>,
+): PluginToolDefinition<z.output<TInputSchema>, z.output<TOutputSchema>> {
+  const { inputSchema, outputSchema, prepareArguments, execute, ...tool } =
+    definition;
+  let modelInputSchema: unknown;
+  let modelOutputSchema: unknown;
+  try {
+    modelInputSchema = z.toJSONSchema(inputSchema);
+  } catch (error) {
+    throw new TypeError(
+      "definePluginTool() inputSchema must be representable as JSON Schema.",
+      { cause: error },
+    );
+  }
+  try {
+    modelOutputSchema = z.toJSONSchema(outputSchema);
+  } catch (error) {
+    throw new TypeError(
+      "definePluginTool() outputSchema must be representable as JSON Schema.",
+      { cause: error },
+    );
+  }
+  return {
+    ...tool,
+    inputSchema: modelInputSchema,
+    outputSchema: modelOutputSchema,
+    prepareArguments(args) {
+      return parsePluginToolInput(
+        inputSchema,
+        prepareArguments ? prepareArguments(args) : args,
+      );
+    },
+    ...(execute
+      ? {
+          async execute(input, options) {
+            const result = await execute(
+              input as z.output<TInputSchema>,
+              options,
+            );
+            return outputSchema.parse(pluginToolResultSchema.parse(result));
+          },
+        }
+      : {}),
+  };
 }
 
 export interface SlackToolRegistrationHookContext {