@sentry/junior-plugin-api 0.189.0 → 0.190.0

package/README.md

@@ -42,6 +42,9 @@ reports, and other typed hook surfaces exported by this package.
 
 - Hook context carries the active source, actor, conversation, plugin metadata,
   database, logging, and only the host capabilities required by that hook.
+- Source uses `kind` to state what produced the input, including input such as
+  a Resource event that has no provider platform. Actor and Destination keep
+  `platform` for their provider scope.
 - Prompt hooks return bounded structured prompt messages rather than mutate the
   core prompt.
 - `formatMarkdown` is a pure text rewrite into ordinary Markdown before delivery.

package/dist/context.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import type { ZodTypeAny } from "zod";
-import { destinationSchema, identitySchema, locationSchema, webActorSchema, localActorSchema, platformSchema, actorSchema, slackActorSchema, systemActorSchema, sourceSchema, slackLocationSchema, userSchema } from "./schemas";
+import { destinationSchema, identitySchema, locationSchema, webActorSchema, localActorSchema, platformSchema, actorSchema, slackActorSchema, systemActorSchema, sourceSchema, sourceVisibilitySchema, slackLocationSchema, 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>;
@@ -16,15 +16,18 @@ export type Location = z.output<typeof locationSchema>;
 /** Complete Slack Location associated with a Conversation. */
 export type SlackLocation = z.output<typeof slackLocationSchema>;
 export type SlackSource = Extract<Source, {
-    platform: "slack";
+    kind: "slack";
 }>;
 export type LocalSource = Extract<Source, {
-    platform: "local";
+    kind: "local";
 }>;
 export type WebSource = Extract<Source, {
-    platform: "web";
+    kind: "web";
+}>;
+export type ResourceEventSource = Extract<Source, {
+    kind: "resource_event";
 }>;
-export type SourceVisibility = Source["visibility"];
+export type SourceVisibility = z.output<typeof sourceVisibilitySchema>;
 export type Destination = z.output<typeof destinationSchema>;
 export type SlackDestination = Extract<Destination, {
     platform: "slack";
@@ -102,7 +105,14 @@ export interface WebInvocationContext extends BaseInvocationContext {
     /** Runtime-owned dashboard/web source for this invocation. */
     source: WebSource;
 }
-export type InvocationContext = LocalInvocationContext | SlackInvocationContext | WebInvocationContext;
+export interface ResourceEventInvocationContext extends BaseInvocationContext {
+    /** Existing conversation destination used for tool context. */
+    destination: Destination;
+    actor?: SystemActor;
+    /** Runtime-owned Resource event Source for this invocation. */
+    source: ResourceEventSource;
+}
+export type InvocationContext = LocalInvocationContext | ResourceEventInvocationContext | SlackInvocationContext | WebInvocationContext;
 /** Build a normalized Slack source from runtime-owned Slack coordinates. */
 export declare function createSlackSource(input: {
     channelId: string;
@@ -116,6 +126,13 @@ export declare function createSlackSource(input: {
 export declare function createLocalSource(conversationId: string): LocalSource;
 /** Build a normalized web/dashboard source from a conversation id. */
 export declare function createWebSource(conversationId: string, visibility?: SourceVisibility): WebSource;
+/** Build a normalized Resource event Source from one matched event. */
+export declare function createResourceEventSource(input: {
+    eventKey: string;
+    eventType: string;
+    identifier: string;
+    namespace: string;
+}): ResourceEventSource;
 /** Return whether a source is private to a person or restricted group. */
 export declare function isPrivateSource(source: Source): boolean;
 /** Return the stable source identity used for idempotency and attribution. */

package/dist/index.js

@@ -150,29 +150,55 @@ var destinationSchema = z4.discriminatedUnion("platform", [
   slackDestinationSchema,
   localDestinationSchema
 ]);
-var slackSourceSchema = slackAddressSchema.extend({
+var slackSourceSchema = z4.object({
+  kind: z4.literal("slack"),
+  teamId: slackTeamIdSchema,
+  channelId: slackConversationIdSchema,
   visibility: sourceVisibilitySchema,
   messageTs: nonBlankStringSchema.optional(),
   threadTs: nonBlankStringSchema.optional()
 }).strict();
 var localSourceSchema = z4.object({
-  platform: z4.literal("local"),
+  kind: z4.literal("local"),
   visibility: z4.literal("private"),
   conversationId: localConversationIdSchema
 }).strict();
 var webSourceSchema = z4.object({
-  platform: z4.literal("web"),
+  kind: z4.literal("web"),
   visibility: sourceVisibilitySchema,
   // Web can continue any existing conversation id, including Slack roots.
   conversationId: exactNonBlankStringSchema
 }).strict();
-var sourceWithLegacyLocationSchema = z4.discriminatedUnion("platform", [
-  slackSourceSchema.extend({ location: locationSchema.optional() }).strict(),
-  localSourceSchema.extend({ location: locationSchema.optional() }).strict(),
-  webSourceSchema.extend({ location: locationSchema.optional() }).strict()
+var resourceEventSourceSchema = z4.object({
+  kind: z4.literal("resource_event"),
+  eventKey: exactNonBlankStringSchema,
+  eventType: exactNonBlankStringSchema,
+  identifier: exactNonBlankStringSchema,
+  namespace: exactNonBlankStringSchema
+}).strict();
+var currentSourceSchema = z4.discriminatedUnion("kind", [
+  slackSourceSchema,
+  localSourceSchema,
+  webSourceSchema,
+  resourceEventSourceSchema
 ]);
-var sourceSchema = sourceWithLegacyLocationSchema.transform(
-  ({ location: _legacyLocation, ...source }) => source
+function normalizeStoredSource(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return value;
+  }
+  const source = value;
+  if ("kind" in source || !("platform" in source)) {
+    return value;
+  }
+  if (source.platform !== "slack" && source.platform !== "local" && source.platform !== "web") {
+    return value;
+  }
+  const { location: _location, platform: kind, ...fields } = source;
+  return { ...fields, kind };
+}
+var sourceSchema = z4.preprocess(
+  normalizeStoredSource,
+  currentSourceSchema
 );
 var pluginCredentialSubjectSchema = z4.discriminatedUnion(
   "allowedWhen",
@@ -299,7 +325,7 @@ var dispatchOptionsSchema = z4.object({
 // src/context.ts
 function createSlackSource(input) {
   return {
-    platform: "slack",
+    kind: "slack",
     visibility: input.visibility,
     teamId: input.teamId,
     channelId: input.channelId,
@@ -309,23 +335,32 @@ function createSlackSource(input) {
 }
 function createLocalSource(conversationId) {
   return {
-    platform: "local",
+    kind: "local",
     visibility: "private",
     conversationId
   };
 }
 function createWebSource(conversationId, visibility = "public") {
   return {
-    platform: "web",
+    kind: "web",
     visibility,
     conversationId
   };
 }
+function createResourceEventSource(input) {
+  return {
+    kind: "resource_event",
+    eventKey: input.eventKey,
+    eventType: input.eventType,
+    identifier: input.identifier,
+    namespace: input.namespace
+  };
+}
 function isPrivateSource(source) {
-  return source.visibility === "private";
+  return "visibility" in source && source.visibility === "private";
 }
 function getSourceKey(source) {
-  switch (source.platform) {
+  switch (source.kind) {
     case "web":
     case "local":
       return source.conversationId;
@@ -336,6 +371,8 @@ function getSourceKey(source) {
       }
       return `slack:${source.teamId}:${source.channelId}:${messageKey}`;
     }
+    case "resource_event":
+      return `resource-event:${source.namespace}:${source.eventKey}`;
   }
 }
 function isSlackDestination(destination) {
@@ -1015,6 +1052,7 @@ export {
   conversationSidebarAnnotationSchema,
   conversationSidebarIconSchema,
   createLocalSource,
+  createResourceEventSource,
   createSlackSource,
   createWebSource,
   defineConversationEvent,
@@ -1071,6 +1109,7 @@ export {
   resourceEventMatchSchema,
   resourceEventMatches,
   resourceEventSchema,
+  resourceEventSourceSchema,
   resourceEventSubscriptionResultSchema,
   resourceEventTypeSchema,
   resourceLinkAnnotationSchema,

package/dist/schemas.d.ts

@@ -53,9 +53,9 @@ export declare const destinationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     platform: z.ZodLiteral<"local">;
     conversationId: z.ZodString;
 }, z.core.$strict>], "platform">;
-/** Runtime-owned Slack coordinates for the inbound invocation. */
+/** Runtime-owned Slack input Source. */
 export declare const slackSourceSchema: z.ZodObject<{
-    platform: z.ZodLiteral<"slack">;
+    kind: z.ZodLiteral<"slack">;
     teamId: z.ZodString;
     channelId: z.ZodString;
     visibility: z.ZodEnum<{
@@ -65,24 +65,32 @@ export declare const slackSourceSchema: z.ZodObject<{
     messageTs: z.ZodOptional<z.ZodString>;
     threadTs: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
-/** Runtime-owned local CLI coordinates for the inbound invocation. */
+/** Runtime-owned local CLI input Source. */
 export declare const localSourceSchema: z.ZodObject<{
-    platform: z.ZodLiteral<"local">;
+    kind: z.ZodLiteral<"local">;
     visibility: z.ZodLiteral<"private">;
     conversationId: z.ZodString;
 }, z.core.$strict>;
-/** Runtime-owned dashboard/web coordinates for the inbound invocation. */
+/** Runtime-owned dashboard input Source. */
 export declare const webSourceSchema: z.ZodObject<{
-    platform: z.ZodLiteral<"web">;
+    kind: z.ZodLiteral<"web">;
     visibility: z.ZodEnum<{
         public: "public";
         private: "private";
     }>;
     conversationId: z.ZodString;
 }, z.core.$strict>;
-/** Runtime-owned input Source. Legacy stored Location is accepted and removed. */
-export declare const sourceSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[z.ZodObject<{
-    platform: z.ZodLiteral<"slack">;
+/** Runtime-owned Resource event input Source. */
+export declare const resourceEventSourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"resource_event">;
+    eventKey: z.ZodString;
+    eventType: z.ZodString;
+    identifier: z.ZodString;
+    namespace: z.ZodString;
+}, z.core.$strict>;
+/** Runtime-owned input Source. Stored `platform` and Location fields normalize on read. */
+export declare const sourceSchema: z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"slack">;
     teamId: z.ZodString;
     channelId: z.ZodString;
     visibility: z.ZodEnum<{
@@ -91,90 +99,24 @@ export declare const sourceSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[z.ZodObjec
     }>;
     messageTs: z.ZodOptional<z.ZodString>;
     threadTs: z.ZodOptional<z.ZodString>;
-    location: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-        id: z.ZodString;
-        provider: z.ZodLiteral<"slack">;
-        teamId: z.ZodString;
-        channelId: z.ZodString;
-        threadTs: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>], "provider">>;
 }, z.core.$strict>, z.ZodObject<{
-    platform: z.ZodLiteral<"local">;
+    kind: z.ZodLiteral<"local">;
     visibility: z.ZodLiteral<"private">;
     conversationId: z.ZodString;
-    location: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-        id: z.ZodString;
-        provider: z.ZodLiteral<"slack">;
-        teamId: z.ZodString;
-        channelId: z.ZodString;
-        threadTs: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>], "provider">>;
 }, z.core.$strict>, z.ZodObject<{
-    platform: z.ZodLiteral<"web">;
+    kind: z.ZodLiteral<"web">;
     visibility: z.ZodEnum<{
         public: "public";
         private: "private";
     }>;
     conversationId: z.ZodString;
-    location: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-        id: z.ZodString;
-        provider: z.ZodLiteral<"slack">;
-        teamId: z.ZodString;
-        channelId: z.ZodString;
-        threadTs: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>], "provider">>;
-}, z.core.$strict>], "platform">, z.ZodTransform<{
-    platform: "slack";
-    teamId: string;
-    channelId: string;
-    visibility: "public" | "private";
-    messageTs?: string | undefined;
-    threadTs?: string | undefined;
-} | {
-    platform: "local";
-    visibility: "private";
-    conversationId: string;
-} | {
-    platform: "web";
-    visibility: "public" | "private";
-    conversationId: string;
-}, {
-    platform: "slack";
-    teamId: string;
-    channelId: string;
-    visibility: "public" | "private";
-    messageTs?: string | undefined;
-    threadTs?: string | undefined;
-    location?: {
-        id: string;
-        provider: "slack";
-        teamId: string;
-        channelId: string;
-        threadTs?: string | undefined;
-    } | undefined;
-} | {
-    platform: "local";
-    visibility: "private";
-    conversationId: string;
-    location?: {
-        id: string;
-        provider: "slack";
-        teamId: string;
-        channelId: string;
-        threadTs?: string | undefined;
-    } | undefined;
-} | {
-    platform: "web";
-    visibility: "public" | "private";
-    conversationId: string;
-    location?: {
-        id: string;
-        provider: "slack";
-        teamId: string;
-        channelId: string;
-        threadTs?: string | undefined;
-    } | undefined;
-}>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"resource_event">;
+    eventKey: z.ZodString;
+    eventType: z.ZodString;
+    identifier: z.ZodString;
+    namespace: z.ZodString;
+}, z.core.$strict>], "kind">>;
 /** Stable user credential subject shape accepted from plugins. */
 export declare const pluginCredentialSubjectSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"user">;
@@ -292,8 +234,8 @@ export declare const dispatchOptionsSchema: z.ZodObject<{
         label: z.ZodPipe<z.ZodString, z.ZodString>;
         detail: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
     }, z.core.$strict>>;
-    source: z.ZodPipe<z.ZodDiscriminatedUnion<[z.ZodObject<{
-        platform: z.ZodLiteral<"slack">;
+    source: z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"slack">;
         teamId: z.ZodString;
         channelId: z.ZodString;
         visibility: z.ZodEnum<{
@@ -302,88 +244,22 @@ export declare const dispatchOptionsSchema: z.ZodObject<{
         }>;
         messageTs: z.ZodOptional<z.ZodString>;
         threadTs: z.ZodOptional<z.ZodString>;
-        location: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-            id: z.ZodString;
-            provider: z.ZodLiteral<"slack">;
-            teamId: z.ZodString;
-            channelId: z.ZodString;
-            threadTs: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>], "provider">>;
     }, z.core.$strict>, z.ZodObject<{
-        platform: z.ZodLiteral<"local">;
+        kind: z.ZodLiteral<"local">;
         visibility: z.ZodLiteral<"private">;
         conversationId: z.ZodString;
-        location: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-            id: z.ZodString;
-            provider: z.ZodLiteral<"slack">;
-            teamId: z.ZodString;
-            channelId: z.ZodString;
-            threadTs: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>], "provider">>;
     }, z.core.$strict>, z.ZodObject<{
-        platform: z.ZodLiteral<"web">;
+        kind: z.ZodLiteral<"web">;
         visibility: z.ZodEnum<{
             public: "public";
             private: "private";
         }>;
         conversationId: z.ZodString;
-        location: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-            id: z.ZodString;
-            provider: z.ZodLiteral<"slack">;
-            teamId: z.ZodString;
-            channelId: z.ZodString;
-            threadTs: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>], "provider">>;
-    }, z.core.$strict>], "platform">, z.ZodTransform<{
-        platform: "slack";
-        teamId: string;
-        channelId: string;
-        visibility: "public" | "private";
-        messageTs?: string | undefined;
-        threadTs?: string | undefined;
-    } | {
-        platform: "local";
-        visibility: "private";
-        conversationId: string;
-    } | {
-        platform: "web";
-        visibility: "public" | "private";
-        conversationId: string;
-    }, {
-        platform: "slack";
-        teamId: string;
-        channelId: string;
-        visibility: "public" | "private";
-        messageTs?: string | undefined;
-        threadTs?: string | undefined;
-        location?: {
-            id: string;
-            provider: "slack";
-            teamId: string;
-            channelId: string;
-            threadTs?: string | undefined;
-        } | undefined;
-    } | {
-        platform: "local";
-        visibility: "private";
-        conversationId: string;
-        location?: {
-            id: string;
-            provider: "slack";
-            teamId: string;
-            channelId: string;
-            threadTs?: string | undefined;
-        } | undefined;
-    } | {
-        platform: "web";
-        visibility: "public" | "private";
-        conversationId: string;
-        location?: {
-            id: string;
-            provider: "slack";
-            teamId: string;
-            channelId: string;
-            threadTs?: string | undefined;
-        } | undefined;
-    }>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"resource_event">;
+        eventKey: z.ZodString;
+        eventType: z.ZodString;
+        identifier: z.ZodString;
+        namespace: z.ZodString;
+    }, z.core.$strict>], "kind">>;
 }, z.core.$strict>;

package/dist/tasks.d.ts

@@ -148,8 +148,8 @@ export declare const pluginRunContextSchema: z.ZodObject<{
         name: z.ZodString;
     }, z.core.$strict>], "platform">>;
     runId: z.ZodString;
-    source: z.ZodPipe<z.ZodDiscriminatedUnion<[z.ZodObject<{
-        platform: z.ZodLiteral<"slack">;
+    source: z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"slack">;
         teamId: z.ZodString;
         channelId: z.ZodString;
         visibility: z.ZodEnum<{
@@ -158,90 +158,24 @@ export declare const pluginRunContextSchema: z.ZodObject<{
         }>;
         messageTs: z.ZodOptional<z.ZodString>;
         threadTs: z.ZodOptional<z.ZodString>;
-        location: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-            id: z.ZodString;
-            provider: z.ZodLiteral<"slack">;
-            teamId: z.ZodString;
-            channelId: z.ZodString;
-            threadTs: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>], "provider">>;
     }, z.core.$strict>, z.ZodObject<{
-        platform: z.ZodLiteral<"local">;
+        kind: z.ZodLiteral<"local">;
         visibility: z.ZodLiteral<"private">;
         conversationId: z.ZodString;
-        location: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-            id: z.ZodString;
-            provider: z.ZodLiteral<"slack">;
-            teamId: z.ZodString;
-            channelId: z.ZodString;
-            threadTs: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>], "provider">>;
     }, z.core.$strict>, z.ZodObject<{
-        platform: z.ZodLiteral<"web">;
+        kind: z.ZodLiteral<"web">;
         visibility: z.ZodEnum<{
             public: "public";
             private: "private";
         }>;
         conversationId: z.ZodString;
-        location: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-            id: z.ZodString;
-            provider: z.ZodLiteral<"slack">;
-            teamId: z.ZodString;
-            channelId: z.ZodString;
-            threadTs: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>], "provider">>;
-    }, z.core.$strict>], "platform">, z.ZodTransform<{
-        platform: "slack";
-        teamId: string;
-        channelId: string;
-        visibility: "public" | "private";
-        messageTs?: string | undefined;
-        threadTs?: string | undefined;
-    } | {
-        platform: "local";
-        visibility: "private";
-        conversationId: string;
-    } | {
-        platform: "web";
-        visibility: "public" | "private";
-        conversationId: string;
-    }, {
-        platform: "slack";
-        teamId: string;
-        channelId: string;
-        visibility: "public" | "private";
-        messageTs?: string | undefined;
-        threadTs?: string | undefined;
-        location?: {
-            id: string;
-            provider: "slack";
-            teamId: string;
-            channelId: string;
-            threadTs?: string | undefined;
-        } | undefined;
-    } | {
-        platform: "local";
-        visibility: "private";
-        conversationId: string;
-        location?: {
-            id: string;
-            provider: "slack";
-            teamId: string;
-            channelId: string;
-            threadTs?: string | undefined;
-        } | undefined;
-    } | {
-        platform: "web";
-        visibility: "public" | "private";
-        conversationId: string;
-        location?: {
-            id: string;
-            provider: "slack";
-            teamId: string;
-            channelId: string;
-            threadTs?: string | undefined;
-        } | undefined;
-    }>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"resource_event">;
+        eventKey: z.ZodString;
+        eventType: z.ZodString;
+        identifier: z.ZodString;
+        namespace: z.ZodString;
+    }, z.core.$strict>], "kind">>;
     transcript: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"message">;
         role: z.ZodEnum<{

package/dist/tools.d.ts

@@ -1,4 +1,4 @@
-import type { Actor, Identity, LocalInvocationContext, PluginContext, PluginEmbedder, PluginModel, SlackInvocationContext, User, WebInvocationContext } from "./context";
+import type { Actor, Identity, LocalInvocationContext, ResourceEventInvocationContext, PluginContext, PluginEmbedder, PluginModel, SlackInvocationContext, User, WebInvocationContext } from "./context";
 import type { PluginCredentialSubject } from "./credentials";
 import type { PluginAnnotations } from "./annotations";
 import type { SlackConversationLink } from "./operations";
@@ -343,5 +343,8 @@ interface LocalToolRegistrationContext extends BaseToolRegistrationHookContext,
 interface WebToolRegistrationContext extends BaseToolRegistrationHookContext, WebInvocationContext {
     slack?: never;
 }
-export type ToolRegistrationHookContext = LocalToolRegistrationContext | SlackToolRegistrationContext | WebToolRegistrationContext;
+interface ResourceEventToolRegistrationContext extends BaseToolRegistrationHookContext, ResourceEventInvocationContext {
+    slack?: never;
+}
+export type ToolRegistrationHookContext = LocalToolRegistrationContext | ResourceEventToolRegistrationContext | SlackToolRegistrationContext | WebToolRegistrationContext;
 export {};

package/package.json

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

package/src/context.ts

@@ -11,6 +11,7 @@ import {
   slackActorSchema,
   systemActorSchema,
   sourceSchema,
+  sourceVisibilitySchema,
   slackLocationSchema,
   userSchema,
 } from "./schemas";
@@ -29,10 +30,11 @@ export type Source = z.output<typeof sourceSchema>;
 export type Location = z.output<typeof locationSchema>;
 /** Complete Slack Location associated with a Conversation. */
 export type SlackLocation = z.output<typeof slackLocationSchema>;
-export type SlackSource = Extract<Source, { platform: "slack" }>;
-export type LocalSource = Extract<Source, { platform: "local" }>;
-export type WebSource = Extract<Source, { platform: "web" }>;
-export type SourceVisibility = Source["visibility"];
+export type SlackSource = Extract<Source, { kind: "slack" }>;
+export type LocalSource = Extract<Source, { kind: "local" }>;
+export type WebSource = Extract<Source, { kind: "web" }>;
+export type ResourceEventSource = Extract<Source, { kind: "resource_event" }>;
+export type SourceVisibility = z.output<typeof sourceVisibilitySchema>;
 
 export type Destination = z.output<typeof destinationSchema>;
 
@@ -117,8 +119,17 @@ export interface WebInvocationContext extends BaseInvocationContext {
   source: WebSource;
 }
 
+export interface ResourceEventInvocationContext extends BaseInvocationContext {
+  /** Existing conversation destination used for tool context. */
+  destination: Destination;
+  actor?: SystemActor;
+  /** Runtime-owned Resource event Source for this invocation. */
+  source: ResourceEventSource;
+}
+
 export type InvocationContext =
   | LocalInvocationContext
+  | ResourceEventInvocationContext
   | SlackInvocationContext
   | WebInvocationContext;
 
@@ -132,7 +143,7 @@ export function createSlackSource(input: {
   visibility: SourceVisibility;
 }): SlackSource {
   return {
-    platform: "slack",
+    kind: "slack",
     visibility: input.visibility,
     teamId: input.teamId,
     channelId: input.channelId,
@@ -144,7 +155,7 @@ export function createSlackSource(input: {
 /** Build a normalized local source from a local conversation id. */
 export function createLocalSource(conversationId: string): LocalSource {
   return {
-    platform: "local",
+    kind: "local",
     visibility: "private",
     conversationId,
   };
@@ -156,20 +167,36 @@ export function createWebSource(
   visibility: SourceVisibility = "public",
 ): WebSource {
   return {
-    platform: "web",
+    kind: "web",
     visibility,
     conversationId,
   };
 }
 
+/** Build a normalized Resource event Source from one matched event. */
+export function createResourceEventSource(input: {
+  eventKey: string;
+  eventType: string;
+  identifier: string;
+  namespace: string;
+}): ResourceEventSource {
+  return {
+    kind: "resource_event",
+    eventKey: input.eventKey,
+    eventType: input.eventType,
+    identifier: input.identifier,
+    namespace: input.namespace,
+  };
+}
+
 /** Return whether a source is private to a person or restricted group. */
 export function isPrivateSource(source: Source): boolean {
-  return source.visibility === "private";
+  return "visibility" in source && source.visibility === "private";
 }
 
 /** Return the stable source identity used for idempotency and attribution. */
 export function getSourceKey(source: Source): string | undefined {
-  switch (source.platform) {
+  switch (source.kind) {
     case "web":
     case "local":
       return source.conversationId;
@@ -180,6 +207,8 @@ export function getSourceKey(source: Source): string | undefined {
       }
       return `slack:${source.teamId}:${source.channelId}:${messageKey}`;
     }
+    case "resource_event":
+      return `resource-event:${source.namespace}:${source.eventKey}`;
   }
 }
 

package/src/schemas.ts

@@ -79,47 +79,80 @@ export const destinationSchema = z.discriminatedUnion("platform", [
   localDestinationSchema,
 ]);
 
-/** Runtime-owned Slack coordinates for the inbound invocation. */
-export const slackSourceSchema = slackAddressSchema
-  .extend({
+/** Runtime-owned Slack input Source. */
+export const slackSourceSchema = z
+  .object({
+    kind: z.literal("slack"),
+    teamId: slackTeamIdSchema,
+    channelId: slackConversationIdSchema,
     visibility: sourceVisibilitySchema,
     messageTs: nonBlankStringSchema.optional(),
     threadTs: nonBlankStringSchema.optional(),
   })
   .strict();
 
-/** Runtime-owned local CLI coordinates for the inbound invocation. */
+/** Runtime-owned local CLI input Source. */
 export const localSourceSchema = z
   .object({
-    platform: z.literal("local"),
+    kind: z.literal("local"),
     visibility: z.literal("private"),
     conversationId: localConversationIdSchema,
   })
   .strict();
 
-/** Runtime-owned dashboard/web coordinates for the inbound invocation. */
+/** Runtime-owned dashboard input Source. */
 export const webSourceSchema = z
   .object({
-    platform: z.literal("web"),
+    kind: z.literal("web"),
     visibility: sourceVisibilitySchema,
     // Web can continue any existing conversation id, including Slack roots.
     conversationId: exactNonBlankStringSchema,
   })
   .strict();
 
-// TODO(dcramer): Replace Source.platform with Source.kind after every input
-// owner emits a first-class Source kind and deployed readers accept it.
-const sourceWithLegacyLocationSchema = z.discriminatedUnion("platform", [
-  slackSourceSchema.extend({ location: locationSchema.optional() }).strict(),
-  localSourceSchema.extend({ location: locationSchema.optional() }).strict(),
-  webSourceSchema.extend({ location: locationSchema.optional() }).strict(),
+/** Runtime-owned Resource event input Source. */
+export const resourceEventSourceSchema = z
+  .object({
+    kind: z.literal("resource_event"),
+    eventKey: exactNonBlankStringSchema,
+    eventType: exactNonBlankStringSchema,
+    identifier: exactNonBlankStringSchema,
+    namespace: exactNonBlankStringSchema,
+  })
+  .strict();
+
+const currentSourceSchema = z.discriminatedUnion("kind", [
+  slackSourceSchema,
+  localSourceSchema,
+  webSourceSchema,
+  resourceEventSourceSchema,
 ]);
 
-/** Runtime-owned input Source. Legacy stored Location is accepted and removed. */
-// TODO(dcramer): Parse sourceSchema directly from the three Source schemas after
-// no stored SQL, Redis, queue, or public Source can contain Location.
-export const sourceSchema = sourceWithLegacyLocationSchema.transform(
-  ({ location: _legacyLocation, ...source }) => source,
+function normalizeStoredSource(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return value;
+  }
+  const source = value as Record<string, unknown>;
+  if ("kind" in source || !("platform" in source)) {
+    return value;
+  }
+  if (
+    source.platform !== "slack" &&
+    source.platform !== "local" &&
+    source.platform !== "web"
+  ) {
+    return value;
+  }
+  const { location: _location, platform: kind, ...fields } = source;
+  return { ...fields, kind };
+}
+
+/** Runtime-owned input Source. Stored `platform` and Location fields normalize on read. */
+// TODO(dcramer): Remove stored Source normalization after deployed SQL, Redis,
+// queue, and OAuth values can only contain `kind` and no Location copy.
+export const sourceSchema = z.preprocess(
+  normalizeStoredSource,
+  currentSourceSchema,
 );
 
 /** Stable user credential subject shape accepted from plugins. */

package/src/tools.ts

@@ -2,6 +2,7 @@ import type {
   Actor,
   Identity,
   LocalInvocationContext,
+  ResourceEventInvocationContext,
   PluginContext,
   PluginEmbedder,
   PluginModel,
@@ -582,7 +583,13 @@ interface WebToolRegistrationContext
   slack?: never;
 }
 
+interface ResourceEventToolRegistrationContext
+  extends BaseToolRegistrationHookContext, ResourceEventInvocationContext {
+  slack?: never;
+}
+
 export type ToolRegistrationHookContext =
   | LocalToolRegistrationContext
+  | ResourceEventToolRegistrationContext
   | SlackToolRegistrationContext
   | WebToolRegistrationContext;