@sentry/junior-plugin-api 0.174.0 → 0.175.0

package/dist/index.js

@@ -331,6 +331,7 @@ var RESOURCE_EVENT_SUMMARY_MAX_LENGTH = 4e3;
 var RESOURCE_EVENT_TEXT_MAX_LENGTH = 8e3;
 var RESOURCE_EVENT_DATA_MAX_KEYS = 32;
 var RESOURCE_EVENT_DATA_MAX_JSON_BYTES = 4e3;
+var RESOURCE_EVENT_GUIDANCE_MAX_LENGTH = 1e3;
 var resourceEventDataSchema = z5.record(z5.string(), z5.unknown()).superRefine((value, context) => {
   const keys = Object.keys(value);
   if (keys.length > RESOURCE_EVENT_DATA_MAX_KEYS) {
@@ -339,7 +340,9 @@ var resourceEventDataSchema = z5.record(z5.string(), z5.unknown()).superRefine((
       message: `Resource event data may include at most ${RESOURCE_EVENT_DATA_MAX_KEYS} keys.`
     });
   }
-  const jsonBytes = new TextEncoder().encode(JSON.stringify(value)).byteLength;
+  const jsonBytes = new TextEncoder().encode(
+    JSON.stringify(value)
+  ).byteLength;
   if (jsonBytes > RESOURCE_EVENT_DATA_MAX_JSON_BYTES) {
     context.addIssue({
       code: "custom",
@@ -356,7 +359,11 @@ var resourceTypeSchema = z5.string().regex(/^[a-z][a-z0-9_]*$/).describe(
 var pluginResourceEventTypeSchema = z5.object({
   type: resourceTypeSchema,
   supportedEvents: z5.array(resourceEventTypeSchema).min(1),
-  suggestedEvents: z5.array(resourceEventTypeSchema).optional()
+  suggestedEvents: z5.array(resourceEventTypeSchema).optional(),
+  guidance: z5.record(
+    resourceEventTypeSchema,
+    z5.string().trim().min(1).max(RESOURCE_EVENT_GUIDANCE_MAX_LENGTH)
+  ).optional()
 }).strict().superRefine((resourceType, context) => {
   const supported = /* @__PURE__ */ new Set();
   resourceType.supportedEvents.forEach((eventType, index) => {
@@ -369,6 +376,15 @@ var pluginResourceEventTypeSchema = z5.object({
     }
     supported.add(eventType);
   });
+  for (const eventType of Object.keys(resourceType.guidance ?? {})) {
+    if (!supported.has(eventType)) {
+      context.addIssue({
+        code: "custom",
+        message: `Guidance resource event type "${eventType}" is not supported.`,
+        path: ["guidance", eventType]
+      });
+    }
+  }
   const suggested = /* @__PURE__ */ new Set();
   resourceType.suggestedEvents?.forEach((eventType, index) => {
     if (suggested.has(eventType)) {
@@ -421,6 +437,10 @@ var subscribableResourceSchema = z5.object({
   supportedEvents: z5.array(resourceEventTypeSchema),
   type: resourceTypeSchema
 }).strict();
+var resourceEventSubscriptionResultSchema = z5.object({
+  events: z5.array(resourceEventTypeSchema).min(1),
+  id: z5.string().min(1)
+}).strict();
 var resourceEventInputSchema = z5.object({
   eventKey: z5.string().min(1),
   eventType: resourceEventTypeSchema,
@@ -856,6 +876,7 @@ export {
   REQUIRED_TOOL_ANNOTATION_KEYS,
   RESOURCE_EVENT_DATA_MAX_JSON_BYTES,
   RESOURCE_EVENT_DATA_MAX_KEYS,
+  RESOURCE_EVENT_GUIDANCE_MAX_LENGTH,
   RESOURCE_EVENT_SUMMARY_MAX_LENGTH,
   RESOURCE_EVENT_TEXT_MAX_LENGTH,
   actorSchema,
@@ -913,6 +934,7 @@ export {
   resourceEventDataSchema,
   resourceEventInputSchema,
   resourceEventSchema,
+  resourceEventSubscriptionResultSchema,
   resourceEventTypeSchema,
   resourceLinkAnnotationSchema,
   resourceTypeSchema,

package/dist/resource-events.d.ts

@@ -3,6 +3,7 @@ export declare const RESOURCE_EVENT_SUMMARY_MAX_LENGTH = 4000;
 export declare const RESOURCE_EVENT_TEXT_MAX_LENGTH = 8000;
 export declare const RESOURCE_EVENT_DATA_MAX_KEYS = 32;
 export declare const RESOURCE_EVENT_DATA_MAX_JSON_BYTES = 4000;
+export declare const RESOURCE_EVENT_GUIDANCE_MAX_LENGTH = 1000;
 /** Small trusted facts from the plugin. The agent should not look these up again. */
 export declare const resourceEventDataSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 /** Canonical dotted event type published and selected across plugins. */
@@ -12,12 +13,14 @@ export declare const pluginResourceEventTypeSchema: z.ZodObject<{
     type: z.ZodString;
     supportedEvents: z.ZodArray<z.ZodString>;
     suggestedEvents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    guidance: z.ZodOptional<z.ZodRecord<z.ZodString, 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>>;
+        guidance: z.ZodOptional<z.ZodRecord<z.ZodString, 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>>;
@@ -35,6 +38,12 @@ export declare const subscribableResourceSchema: z.ZodObject<{
     type: z.ZodString;
 }, z.core.$strict>;
 export type SubscribableResource = z.output<typeof subscribableResourceSchema>;
+/** Result returned after a temporary resource subscription is created. */
+export declare const resourceEventSubscriptionResultSchema: z.ZodObject<{
+    events: z.ZodArray<z.ZodString>;
+    id: z.ZodString;
+}, z.core.$strict>;
+export type ResourceEventSubscriptionResult = z.output<typeof resourceEventSubscriptionResultSchema>;
 export declare const resourceEventInputSchema: z.ZodObject<{
     eventKey: z.ZodString;
     eventType: z.ZodString;

package/dist/tools.d.ts

@@ -2,6 +2,7 @@ import type { Actor, Identity, LocalInvocationContext, PluginContext, PluginEmbe
 import type { PluginCredentialSubject } from "./credentials";
 import type { PluginAnnotations } from "./annotations";
 import type { SlackConversationLink } from "./operations";
+import type { ResourceEventSubscriptionResult, SubscribableResource } from "./resource-events";
 import type { PluginState } from "./state";
 import { z, type ZodTypeAny } from "zod";
 export interface PluginEnv {
@@ -286,8 +287,14 @@ export interface SlackToolRegistrationHookContext {
     }>;
 }
 export interface PluginResourceEventToolContext {
-    /** Whether this invocation can create a working resource-event subscription. */
+    /** Whether this invocation can create a working resource subscription. */
     canSubscribe: boolean;
+    /** Create a temporary resource subscription for the current conversation. */
+    subscribe(input: {
+        events: string[];
+        intent: string;
+        resource: SubscribableResource;
+    }): Promise<ResourceEventSubscriptionResult>;
 }
 export interface PluginWorkspaceToolContext {
     /** Find named Workspaces that include one provider repository. */

package/package.json

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

package/src/resource-events.ts

@@ -4,6 +4,7 @@ export const RESOURCE_EVENT_SUMMARY_MAX_LENGTH = 4_000;
 export const RESOURCE_EVENT_TEXT_MAX_LENGTH = 8_000;
 export const RESOURCE_EVENT_DATA_MAX_KEYS = 32;
 export const RESOURCE_EVENT_DATA_MAX_JSON_BYTES = 4_000;
+export const RESOURCE_EVENT_GUIDANCE_MAX_LENGTH = 1_000;
 
 /** Small trusted facts from the plugin. The agent should not look these up again. */
 export const resourceEventDataSchema = z
@@ -16,7 +17,9 @@ export const resourceEventDataSchema = z
         message: `Resource event data may include at most ${RESOURCE_EVENT_DATA_MAX_KEYS} keys.`,
       });
     }
-    const jsonBytes = new TextEncoder().encode(JSON.stringify(value)).byteLength;
+    const jsonBytes = new TextEncoder().encode(
+      JSON.stringify(value),
+    ).byteLength;
     if (jsonBytes > RESOURCE_EVENT_DATA_MAX_JSON_BYTES) {
       context.addIssue({
         code: "custom",
@@ -45,6 +48,12 @@ export const pluginResourceEventTypeSchema = z
     type: resourceTypeSchema,
     supportedEvents: z.array(resourceEventTypeSchema).min(1),
     suggestedEvents: z.array(resourceEventTypeSchema).optional(),
+    guidance: z
+      .record(
+        resourceEventTypeSchema,
+        z.string().trim().min(1).max(RESOURCE_EVENT_GUIDANCE_MAX_LENGTH),
+      )
+      .optional(),
   })
   .strict()
   .superRefine((resourceType, context) => {
@@ -59,6 +68,15 @@ export const pluginResourceEventTypeSchema = z
       }
       supported.add(eventType);
     });
+    for (const eventType of Object.keys(resourceType.guidance ?? {})) {
+      if (!supported.has(eventType)) {
+        context.addIssue({
+          code: "custom",
+          message: `Guidance resource event type "${eventType}" is not supported.`,
+          path: ["guidance", eventType],
+        });
+      }
+    }
     const suggested = new Set<string>();
     resourceType.suggestedEvents?.forEach((eventType, index) => {
       if (suggested.has(eventType)) {
@@ -135,6 +153,18 @@ export const subscribableResourceSchema = z
 
 export type SubscribableResource = z.output<typeof subscribableResourceSchema>;
 
+/** Result returned after a temporary resource subscription is created. */
+export const resourceEventSubscriptionResultSchema = z
+  .object({
+    events: z.array(resourceEventTypeSchema).min(1),
+    id: z.string().min(1),
+  })
+  .strict();
+
+export type ResourceEventSubscriptionResult = z.output<
+  typeof resourceEventSubscriptionResultSchema
+>;
+
 export const resourceEventInputSchema = z
   .object({
     eventKey: z.string().min(1),

package/src/tools.ts

@@ -12,6 +12,10 @@ import type {
 import type { PluginCredentialSubject } from "./credentials";
 import type { PluginAnnotations } from "./annotations";
 import type { SlackConversationLink } from "./operations";
+import type {
+  ResourceEventSubscriptionResult,
+  SubscribableResource,
+} from "./resource-events";
 import type { PluginState } from "./state";
 import { z, type ZodTypeAny } from "zod";
 
@@ -516,8 +520,14 @@ export interface SlackToolRegistrationHookContext {
 }
 
 export interface PluginResourceEventToolContext {
-  /** Whether this invocation can create a working resource-event subscription. */
+  /** Whether this invocation can create a working resource subscription. */
   canSubscribe: boolean;
+  /** Create a temporary resource subscription for the current conversation. */
+  subscribe(input: {
+    events: string[];
+    intent: string;
+    resource: SubscribableResource;
+  }): Promise<ResourceEventSubscriptionResult>;
 }
 
 export interface PluginWorkspaceToolContext {