@sentry/junior-plugin-api 0.124.1 → 0.125.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,8 +84,9 @@ 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.
 - Delegated credential subjects declare the narrow action that authorized them.
@@ -90,11 +99,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

@@ -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;

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/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;

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/package.json

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

package/src/context.ts

@@ -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;

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/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;