@sentry/junior-plugin-api 0.124.2 → 0.126.0

package/README.md

@@ -44,9 +44,17 @@ reports, and other typed hook surfaces exported by this package.
   database, logging, and only the host capabilities required by that hook.
 - Prompt hooks return bounded structured prompt messages rather than mutate the
   core prompt.
+- User prompt hooks for durable turns may emit registered structured events
+  through `ctx.events` for auxiliary work completed while building context.
 - Tool hooks return model-visible schemas aligned with their executor inputs.
 - Host-owned structured model and embedding calls do not expose provider
-  credentials to plugins.
+  credentials to plugins. Both return a best-effort provider cost estimate when
+  one is available.
+- Operational report and authenticated API hooks may aggregate `costUsd` from
+  their own registered conversation events through `ctx.eventStats`. Core
+  binds the plugin namespace and owns access to the conversation event log.
+  Event `costUsd` is additive operation cost and must not duplicate cost
+  already recorded in the conversation's agent model usage.
 - Authenticated API route apps receive one verified viewer in their request
   context. The registration hook exposes actor resolution for plugins whose
   viewer-owned data spans platform identities.
@@ -76,10 +84,14 @@ routing, response validation, rendering, confirmation, and query state.
 - Conversation-bound background tasks may emit registered structured events
   through `ctx.events`. Define each version with `defineConversationEvent()`;
   the host supplies the plugin namespace, conversation, turn, ordering, and
-  timestamps. Event definitions return bounded transcript presentation data,
-  while Junior owns browser rendering.
+  timestamps without treating background work as new conversation activity.
+  Event definitions return bounded transcript presentation data, while Junior
+  owns browser rendering.
 - `ctx.agent.dispatch` creates durable agent work with an explicit actor,
   destination, source, metadata, and idempotency identity.
+- Dispatches may include compact `replyAttribution` for destination-visible
+  context about what produced the reply. Core owns platform rendering; opaque
+  dispatch metadata remains internal.
 - Delegated credential subjects declare the narrow action that authorized them.
   Core owns runtime bindings; scheduler task subjects are accepted only from the
   scheduler plugin and are bound to the exact task id.
@@ -90,11 +102,14 @@ routing, response validation, rendering, confirmation, and query state.
 
 Register plugin-owned event definitions through `conversationEvents`. A
 definition owns one local name, version, content schema, and `renderEvent()`
-projection. The active plugin context supplies the namespace, so plugins cannot
-emit native events or impersonate another plugin. The `junior` plugin name is
-reserved for host-owned native events. Stored events remain durable when a
-plugin is removed, but normal transcript projection skips definitions that are
-not currently registered.
+projection. A renderer may return `undefined` when an event should remain
+durable without producing a transcript row. The active plugin context supplies
+the namespace, so plugins cannot emit native events or impersonate another
+plugin. The `junior` plugin name is reserved for host-owned native events.
+Versions of the same event name share one operation idempotency identity,
+so keep previous definitions registered when evolving an event. Stored events
+remain durable when a plugin is removed, but normal transcript projection skips
+definitions that are not currently registered.
 
 ## Database
 

package/dist/context.d.ts

@@ -14,7 +14,7 @@ export type SlackSource = Extract<Source, {
 export type LocalSource = Extract<Source, {
     platform: "local";
 }>;
-export type SourceType = Source["type"];
+export type SourceVisibility = Source["visibility"];
 export type Destination = z.output<typeof destinationSchema>;
 export type SlackDestination = Extract<Destination, {
     platform: "slack";
@@ -38,6 +38,8 @@ export interface PluginModel {
         schema: TSchema;
         system?: string;
     }): Promise<{
+        /** Best-effort estimated provider cost for this completion. */
+        costUsd?: number;
         object: z.infer<TSchema>;
     }>;
 }
@@ -46,6 +48,8 @@ export interface PluginEmbedder {
     embedTexts(input: {
         texts: string[];
     }): Promise<{
+        /** Best-effort estimated provider cost for this embedding call. */
+        costUsd?: number;
         dimensions: number;
         model: string;
         provider: string;
@@ -87,7 +91,7 @@ export declare function createSlackSource(input: {
     teamId: string;
     threadTs?: string;
     /** Runtime-normalized source visibility. */
-    type: SourceType;
+    visibility: SourceVisibility;
 }): SlackSource;
 /** Build a normalized local source from a local conversation id. */
 export declare function createLocalSource(conversationId: string): LocalSource;

package/dist/conversation-events.d.ts

@@ -39,12 +39,12 @@ export interface PluginConversationEventValue {
     readonly data: Record<string, unknown>;
     readonly definition: PluginConversationEventDefinition;
 }
-/** Registered schema and transcript presentation for one plugin event version. */
+/** Registered schema and optional transcript presentation for one event version. */
 export interface PluginConversationEventDefinition {
     readonly eventName: string;
     readonly version: number;
     parse(data: unknown): Record<string, unknown>;
-    renderEvent(data: Record<string, unknown>): ConversationEventPresentation;
+    renderEvent(data: Record<string, unknown>): ConversationEventPresentation | undefined;
 }
 /** Typed factory returned while authoring one plugin conversation event. */
 export interface DefinedConversationEvent<TInput> extends PluginConversationEventDefinition {
@@ -55,9 +55,21 @@ export declare function defineConversationEvent<TSchema extends z.ZodType<Record
     name: string;
     version: number;
     schema: TSchema;
-    renderEvent(event: z.output<TSchema>): z.input<typeof conversationEventPresentationSchema>;
+    renderEvent(event: z.output<TSchema>): z.input<typeof conversationEventPresentationSchema> | undefined;
 }): DefinedConversationEvent<z.input<TSchema>>;
 /** Conversation-bound event writer supplied by Junior core. */
 export interface PluginConversationEvents {
     emit(event: PluginConversationEventValue): Promise<void>;
 }
+export interface PluginConversationEventCostDay {
+    costUsd: number;
+    date: string;
+    events: number;
+}
+/** Read aggregate costs for events owned by the current plugin namespace. */
+export interface PluginConversationEventStats {
+    costsByDay(input: {
+        days: 7 | 30 | 90;
+        eventName: string;
+    }): Promise<PluginConversationEventCostDay[]>;
+}

package/dist/dispatch.d.ts

@@ -1,7 +1,9 @@
 import { z } from "zod";
-import { destinationVisibilitySchema, dispatchOptionsSchema } from "./schemas";
+import { destinationVisibilitySchema, dispatchOptionsSchema, replyAttributionSchema } from "./schemas";
 export type DestinationVisibility = z.output<typeof destinationVisibilitySchema>;
 export type DispatchOptions = z.output<typeof dispatchOptionsSchema>;
+/** Compact destination-visible context explaining what produced a reply. */
+export type ReplyAttribution = z.output<typeof replyAttributionSchema>;
 export interface DispatchResult {
     id: string;
     status: "created" | "already_exists";

package/dist/index.js

@@ -64,9 +64,8 @@ function defineConversationEvent(definition) {
     },
     renderEvent(data) {
       const parsed = definition.schema.parse(data);
-      return conversationEventPresentationSchema.parse(
-        definition.renderEvent(parsed)
-      );
+      const presentation = definition.renderEvent(parsed);
+      return presentation === void 0 ? void 0 : conversationEventPresentationSchema.parse(presentation);
     }
   });
   return eventDefinition;
@@ -85,7 +84,7 @@ var exactNonBlankStringSchema = nonBlankStringSchema.refine(
   (value) => value === value.trim()
 );
 var platformSchema = z3.enum(["slack", "local"]);
-var sourceTypeSchema = z3.enum(["pub", "priv"]);
+var sourceVisibilitySchema = z3.enum(["public", "private"]);
 var destinationVisibilitySchema = z3.enum(["public", "private"]);
 var slackAddressSchema = z3.object({
   platform: z3.literal("slack"),
@@ -102,13 +101,13 @@ var destinationSchema = z3.discriminatedUnion("platform", [
   localDestinationSchema
 ]);
 var slackSourceSchema = slackAddressSchema.extend({
-  type: sourceTypeSchema,
+  visibility: sourceVisibilitySchema,
   messageTs: nonBlankStringSchema.optional(),
   threadTs: nonBlankStringSchema.optional()
 }).strict();
 var localSourceSchema = z3.object({
   platform: z3.literal("local"),
-  type: z3.literal("priv"),
+  visibility: z3.literal("private"),
   conversationId: localConversationIdSchema
 }).strict();
 var sourceSchema = z3.discriminatedUnion("platform", [
@@ -203,6 +202,10 @@ var dispatchMetadataSchema = z3.record(z3.string(), z3.string()).superRefine((me
     }
   }
 });
+var replyAttributionSchema = z3.object({
+  label: exactNonBlankStringSchema.pipe(z3.string().max(48)).refine((value) => !/[\r\n]/.test(value)),
+  detail: exactNonBlankStringSchema.pipe(z3.string().max(128)).refine((value) => !/[\r\n]/.test(value)).optional()
+}).strict();
 var dispatchOptionsSchema = z3.object({
   idempotencyKey: nonBlankStringSchema.pipe(z3.string().max(512)),
   credentialSubject: pluginCredentialSubjectSchema.optional(),
@@ -210,6 +213,7 @@ var dispatchOptionsSchema = z3.object({
   destinationVisibility: destinationVisibilitySchema,
   input: nonBlankStringSchema.pipe(z3.string().max(32e3)),
   metadata: dispatchMetadataSchema.optional(),
+  replyAttribution: replyAttributionSchema.optional(),
   source: sourceSchema
 }).strict();
 
@@ -217,7 +221,7 @@ var dispatchOptionsSchema = z3.object({
 function createSlackSource(input) {
   return {
     platform: "slack",
-    type: input.type,
+    visibility: input.visibility,
     teamId: input.teamId,
     channelId: input.channelId,
     ...input.messageTs ? { messageTs: input.messageTs } : {},
@@ -227,12 +231,12 @@ function createSlackSource(input) {
 function createLocalSource(conversationId) {
   return {
     platform: "local",
-    type: "priv",
+    visibility: "private",
     conversationId
   };
 }
 function isPrivateSource(source) {
-  return source.type === "priv";
+  return source.visibility === "private";
 }
 function getSourceKey(source) {
   if (source.platform === "local") {
@@ -747,13 +751,14 @@ export {
   pluginUserPageLinksSchema,
   promptContextSchema,
   promptMessageSchema,
+  replyAttributionSchema,
   resourceEventSchema,
   resourceLinkAnnotationSchema,
   slackActorSchema,
   slackDestinationSchema,
   slackSourceSchema,
   sourceSchema,
-  sourceTypeSchema,
+  sourceVisibilitySchema,
   subscribableResourceSchema,
   systemActorSchema,
   toolApprovalModeSchema,

package/dist/operations.d.ts

@@ -4,6 +4,7 @@ import type { Dispatch, DispatchOptions, DispatchResult } from "./dispatch";
 import type { PluginReadState, PluginState } from "./state";
 import type { ResourceEventPublisher } from "./resource-events";
 import type { PluginConversationAnnotations } from "./annotations";
+import type { PluginConversationEventStats } from "./conversation-events";
 export interface HeartbeatHookContext extends PluginContext {
     agent: {
         dispatch(options: DispatchOptions): Promise<DispatchResult>;
@@ -37,6 +38,7 @@ export interface PluginOperationalRecordSet {
     title: string;
 }
 export interface PluginOperationalChartSeries {
+    format?: "usd";
     key: string;
     label: string;
     tone?: PluginOperationalTone;
@@ -67,6 +69,7 @@ export interface PluginOperationalReport extends PluginOperationalReportContent
     pluginName: string;
 }
 export interface OperationalReportHookContext extends PluginContext {
+    eventStats: PluginConversationEventStats;
     nowMs: number;
     state: PluginReadState;
 }
@@ -89,6 +92,7 @@ export interface RouteRegistrationHookContext extends PluginContext {
     resourceEvents: ResourceEventPublisher;
 }
 export interface ApiRouteRegistrationHookContext extends PluginContext {
+    eventStats: PluginConversationEventStats;
     viewer: {
         /** Resolve every runtime actor linked to one authenticated viewer email. */
         actors(email: string): Promise<Array<LocalActor | SlackActor>>;

package/dist/prompt.d.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import type { Destination, Platform, PluginContext, PluginEmbedder, PluginModel, Actor, Source } from "./context";
 import type { PluginState } from "./state";
+import type { PluginConversationEvents } from "./conversation-events";
 export declare const promptMessageSchema: z.ZodObject<{
     text: z.ZodString;
 }, z.core.$strict>;
@@ -36,6 +37,8 @@ export type UserPromptContext = Pick<PluginContext, "db" | "log" | "plugin"> & {
     conversationId?: string;
     destination: Destination;
     embedder: PluginEmbedder;
+    /** Conversation-bound event writer when the prompt belongs to a durable turn. */
+    events?: PluginConversationEvents;
     model: PluginModel;
     actor?: Actor;
     source: Source;

package/dist/schemas.d.ts

@@ -6,9 +6,9 @@ export declare const platformSchema: z.ZodEnum<{
     local: "local";
 }>;
 /** Runtime source visibility visible to plugins. */
-export declare const sourceTypeSchema: z.ZodEnum<{
-    pub: "pub";
-    priv: "priv";
+export declare const sourceVisibilitySchema: z.ZodEnum<{
+    public: "public";
+    private: "private";
 }>;
 /** Provider-neutral visibility of a routed destination. */
 export declare const destinationVisibilitySchema: z.ZodEnum<{
@@ -40,9 +40,9 @@ export declare const slackSourceSchema: z.ZodObject<{
     platform: z.ZodLiteral<"slack">;
     teamId: z.ZodString;
     channelId: z.ZodString;
-    type: z.ZodEnum<{
-        pub: "pub";
-        priv: "priv";
+    visibility: z.ZodEnum<{
+        public: "public";
+        private: "private";
     }>;
     messageTs: z.ZodOptional<z.ZodString>;
     threadTs: z.ZodOptional<z.ZodString>;
@@ -50,7 +50,7 @@ export declare const slackSourceSchema: z.ZodObject<{
 /** Runtime-owned local CLI coordinates for the inbound invocation. */
 export declare const localSourceSchema: z.ZodObject<{
     platform: z.ZodLiteral<"local">;
-    type: z.ZodLiteral<"priv">;
+    visibility: z.ZodLiteral<"private">;
     conversationId: z.ZodString;
 }, z.core.$strict>;
 /** Runtime-owned provider-neutral coordinates for the inbound invocation. */
@@ -58,15 +58,15 @@ export declare const sourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     platform: z.ZodLiteral<"slack">;
     teamId: z.ZodString;
     channelId: z.ZodString;
-    type: z.ZodEnum<{
-        pub: "pub";
-        priv: "priv";
+    visibility: z.ZodEnum<{
+        public: "public";
+        private: "private";
     }>;
     messageTs: z.ZodOptional<z.ZodString>;
     threadTs: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
     platform: z.ZodLiteral<"local">;
-    type: z.ZodLiteral<"priv">;
+    visibility: z.ZodLiteral<"private">;
     conversationId: z.ZodString;
 }, z.core.$strict>], "platform">;
 /** Stable user credential subject shape accepted from plugins. */
@@ -117,6 +117,11 @@ export declare const actorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     platform: z.ZodLiteral<"system">;
     name: z.ZodString;
 }, z.core.$strict>], "platform">;
+/** Compact destination-visible context explaining what produced a reply. */
+export declare const replyAttributionSchema: z.ZodObject<{
+    label: z.ZodPipe<z.ZodString, z.ZodString>;
+    detail: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
 /** Plugin dispatch request accepted by Junior core. */
 export declare const dispatchOptionsSchema: z.ZodObject<{
     idempotencyKey: z.ZodPipe<z.ZodString, z.ZodString>;
@@ -141,19 +146,23 @@ export declare const dispatchOptionsSchema: z.ZodObject<{
     }>;
     input: z.ZodPipe<z.ZodString, z.ZodString>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    replyAttribution: z.ZodOptional<z.ZodObject<{
+        label: z.ZodPipe<z.ZodString, z.ZodString>;
+        detail: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>;
     source: z.ZodDiscriminatedUnion<[z.ZodObject<{
         platform: z.ZodLiteral<"slack">;
         teamId: z.ZodString;
         channelId: z.ZodString;
-        type: z.ZodEnum<{
-            pub: "pub";
-            priv: "priv";
+        visibility: z.ZodEnum<{
+            public: "public";
+            private: "private";
         }>;
         messageTs: z.ZodOptional<z.ZodString>;
         threadTs: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>, z.ZodObject<{
         platform: z.ZodLiteral<"local">;
-        type: z.ZodLiteral<"priv">;
+        visibility: z.ZodLiteral<"private">;
         conversationId: z.ZodString;
     }, z.core.$strict>], "platform">;
 }, z.core.$strict>;

package/dist/tasks.d.ts

@@ -126,15 +126,15 @@ export declare const pluginRunContextSchema: z.ZodObject<{
         platform: z.ZodLiteral<"slack">;
         teamId: z.ZodString;
         channelId: z.ZodString;
-        type: z.ZodEnum<{
-            pub: "pub";
-            priv: "priv";
+        visibility: z.ZodEnum<{
+            public: "public";
+            private: "private";
         }>;
         messageTs: z.ZodOptional<z.ZodString>;
         threadTs: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>, z.ZodObject<{
         platform: z.ZodLiteral<"local">;
-        type: z.ZodLiteral<"priv">;
+        visibility: z.ZodLiteral<"private">;
         conversationId: z.ZodString;
     }, z.core.$strict>], "platform">;
     transcript: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{

package/package.json

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

package/src/context.ts

@@ -19,7 +19,7 @@ export type SystemActor = z.output<typeof systemActorSchema>;
 export type Source = z.output<typeof sourceSchema>;
 export type SlackSource = Extract<Source, { platform: "slack" }>;
 export type LocalSource = Extract<Source, { platform: "local" }>;
-export type SourceType = Source["type"];
+export type SourceVisibility = Source["visibility"];
 
 export type Destination = z.output<typeof destinationSchema>;
 
@@ -44,12 +44,18 @@ export interface PluginModel {
     prompt: string;
     schema: TSchema;
     system?: string;
-  }): Promise<{ object: z.infer<TSchema> }>;
+  }): Promise<{
+    /** Best-effort estimated provider cost for this completion. */
+    costUsd?: number;
+    object: z.infer<TSchema>;
+  }>;
 }
 
 export interface PluginEmbedder {
   /** Embed plugin-owned text for derived retrieval without exposing provider credentials. */
   embedTexts(input: { texts: string[] }): Promise<{
+    /** Best-effort estimated provider cost for this embedding call. */
+    costUsd?: number;
     dimensions: number;
     model: string;
     provider: string;
@@ -97,11 +103,11 @@ export function createSlackSource(input: {
   teamId: string;
   threadTs?: string;
   /** Runtime-normalized source visibility. */
-  type: SourceType;
+  visibility: SourceVisibility;
 }): SlackSource {
   return {
     platform: "slack",
-    type: input.type,
+    visibility: input.visibility,
     teamId: input.teamId,
     channelId: input.channelId,
     ...(input.messageTs ? { messageTs: input.messageTs } : {}),
@@ -113,14 +119,14 @@ export function createSlackSource(input: {
 export function createLocalSource(conversationId: string): LocalSource {
   return {
     platform: "local",
-    type: "priv",
+    visibility: "private",
     conversationId,
   };
 }
 
 /** Return whether a source is private to a person or restricted group. */
 export function isPrivateSource(source: Source): boolean {
-  return source.type === "priv";
+  return source.visibility === "private";
 }
 
 /** Return the stable source identity used for idempotency and attribution. */

package/src/conversation-events.ts

@@ -48,12 +48,14 @@ export interface PluginConversationEventValue {
   readonly definition: PluginConversationEventDefinition;
 }
 
-/** Registered schema and transcript presentation for one plugin event version. */
+/** Registered schema and optional transcript presentation for one event version. */
 export interface PluginConversationEventDefinition {
   readonly eventName: string;
   readonly version: number;
   parse(data: unknown): Record<string, unknown>;
-  renderEvent(data: Record<string, unknown>): ConversationEventPresentation;
+  renderEvent(
+    data: Record<string, unknown>,
+  ): ConversationEventPresentation | undefined;
 }
 
 /** Typed factory returned while authoring one plugin conversation event. */
@@ -72,7 +74,7 @@ export function defineConversationEvent<
   schema: TSchema;
   renderEvent(
     event: z.output<TSchema>,
-  ): z.input<typeof conversationEventPresentationSchema>;
+  ): z.input<typeof conversationEventPresentationSchema> | undefined;
 }): DefinedConversationEvent<z.input<TSchema>> {
   const identity = z
     .object({
@@ -96,9 +98,10 @@ export function defineConversationEvent<
     },
     renderEvent(data: Record<string, unknown>) {
       const parsed = definition.schema.parse(data);
-      return conversationEventPresentationSchema.parse(
-        definition.renderEvent(parsed),
-      );
+      const presentation = definition.renderEvent(parsed);
+      return presentation === undefined
+        ? undefined
+        : conversationEventPresentationSchema.parse(presentation);
     },
   });
   return eventDefinition;
@@ -108,3 +111,17 @@ export function defineConversationEvent<
 export interface PluginConversationEvents {
   emit(event: PluginConversationEventValue): Promise<void>;
 }
+
+export interface PluginConversationEventCostDay {
+  costUsd: number;
+  date: string;
+  events: number;
+}
+
+/** Read aggregate costs for events owned by the current plugin namespace. */
+export interface PluginConversationEventStats {
+  costsByDay(input: {
+    days: 7 | 30 | 90;
+    eventName: string;
+  }): Promise<PluginConversationEventCostDay[]>;
+}

package/src/dispatch.ts

@@ -2,12 +2,15 @@ import { z } from "zod";
 import {
   destinationVisibilitySchema,
   dispatchOptionsSchema,
+  replyAttributionSchema,
 } from "./schemas";
 
 export type DestinationVisibility = z.output<
   typeof destinationVisibilitySchema
 >;
 export type DispatchOptions = z.output<typeof dispatchOptionsSchema>;
+/** Compact destination-visible context explaining what produced a reply. */
+export type ReplyAttribution = z.output<typeof replyAttributionSchema>;
 
 export interface DispatchResult {
   id: string;

package/src/operations.ts

@@ -5,6 +5,7 @@ import { nonBlankStringSchema } from "./schemas";
 import type { PluginReadState, PluginState } from "./state";
 import type { ResourceEventPublisher } from "./resource-events";
 import type { PluginConversationAnnotations } from "./annotations";
+import type { PluginConversationEventStats } from "./conversation-events";
 
 export interface HeartbeatHookContext extends PluginContext {
   agent: {
@@ -46,6 +47,7 @@ export interface PluginOperationalRecordSet {
 }
 
 export interface PluginOperationalChartSeries {
+  format?: "usd";
   key: string;
   label: string;
   tone?: PluginOperationalTone;
@@ -81,6 +83,7 @@ export interface PluginOperationalReport extends PluginOperationalReportContent
 }
 
 export interface OperationalReportHookContext extends PluginContext {
+  eventStats: PluginConversationEventStats;
   nowMs: number;
   state: PluginReadState;
 }
@@ -120,6 +123,7 @@ export interface RouteRegistrationHookContext extends PluginContext {
 }
 
 export interface ApiRouteRegistrationHookContext extends PluginContext {
+  eventStats: PluginConversationEventStats;
   viewer: {
     /** Resolve every runtime actor linked to one authenticated viewer email. */
     actors(email: string): Promise<Array<LocalActor | SlackActor>>;

package/src/prompt.ts

@@ -9,6 +9,7 @@ import type {
   Source,
 } from "./context";
 import type { PluginState } from "./state";
+import type { PluginConversationEvents } from "./conversation-events";
 
 const promptContextKindSchema = z
   .string()
@@ -80,6 +81,8 @@ export type UserPromptContext = Pick<PluginContext, "db" | "log" | "plugin"> & {
   conversationId?: string;
   destination: Destination;
   embedder: PluginEmbedder;
+  /** Conversation-bound event writer when the prompt belongs to a durable turn. */
+  events?: PluginConversationEvents;
   model: PluginModel;
   actor?: Actor;
   source: Source;

package/src/schemas.ts

@@ -23,7 +23,7 @@ const exactNonBlankStringSchema = nonBlankStringSchema.refine(
 export const platformSchema = z.enum(["slack", "local"]);
 
 /** Runtime source visibility visible to plugins. */
-export const sourceTypeSchema = z.enum(["pub", "priv"]);
+export const sourceVisibilitySchema = z.enum(["public", "private"]);
 
 /** Provider-neutral visibility of a routed destination. */
 export const destinationVisibilitySchema = z.enum(["public", "private"]);
@@ -56,7 +56,7 @@ export const destinationSchema = z.discriminatedUnion("platform", [
 /** Runtime-owned Slack coordinates for the inbound invocation. */
 export const slackSourceSchema = slackAddressSchema
   .extend({
-    type: sourceTypeSchema,
+    visibility: sourceVisibilitySchema,
     messageTs: nonBlankStringSchema.optional(),
     threadTs: nonBlankStringSchema.optional(),
   })
@@ -66,7 +66,7 @@ export const slackSourceSchema = slackAddressSchema
 export const localSourceSchema = z
   .object({
     platform: z.literal("local"),
-    type: z.literal("priv"),
+    visibility: z.literal("private"),
     conversationId: localConversationIdSchema,
   })
   .strict();
@@ -187,6 +187,19 @@ const dispatchMetadataSchema = z
     }
   });
 
+/** Compact destination-visible context explaining what produced a reply. */
+export const replyAttributionSchema = z
+  .object({
+    label: exactNonBlankStringSchema
+      .pipe(z.string().max(48))
+      .refine((value) => !/[\r\n]/.test(value)),
+    detail: exactNonBlankStringSchema
+      .pipe(z.string().max(128))
+      .refine((value) => !/[\r\n]/.test(value))
+      .optional(),
+  })
+  .strict();
+
 /** Plugin dispatch request accepted by Junior core. */
 export const dispatchOptionsSchema = z
   .object({
@@ -196,6 +209,7 @@ export const dispatchOptionsSchema = z
     destinationVisibility: destinationVisibilitySchema,
     input: nonBlankStringSchema.pipe(z.string().max(32_000)),
     metadata: dispatchMetadataSchema.optional(),
+    replyAttribution: replyAttributionSchema.optional(),
     source: sourceSchema,
   })
   .strict();