@sentry/junior-plugin-api 0.75.0 → 0.76.0

package/dist/tasks.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Public plugin background-task contracts.
+ *
+ * Plugins register small task handlers, while Junior core owns durable
+ * scheduling, queue delivery, retries, and the bounded run projection.
+ */
+import { z } from "zod";
+import type { PluginContext, PluginEmbedder, PluginModel } from "./context";
+import type { PluginState } from "./state";
+/** One normalized transcript entry from the completed run exposed to plugin tasks. */
+export declare const pluginRunTranscriptEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"message">;
+    role: z.ZodEnum<{
+        user: "user";
+        assistant: "assistant";
+    }>;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"toolResult">;
+    toolName: z.ZodString;
+    isError: z.ZodBoolean;
+    text: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "type">;
+/** Runtime-owned completed-run projection exposed to plugin tasks. */
+export declare const pluginRunContextSchema: z.ZodObject<{
+    completedAtMs: z.ZodNumber;
+    conversationId: z.ZodString;
+    destination: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        platform: z.ZodLiteral<"slack">;
+        teamId: z.ZodString;
+        channelId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        platform: z.ZodLiteral<"local">;
+        conversationId: z.ZodString;
+    }, z.core.$strict>], "platform">;
+    requester: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        platform: z.ZodLiteral<"slack">;
+        teamId: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        fullName: z.ZodOptional<z.ZodString>;
+        userId: z.ZodString;
+        userName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        platform: z.ZodLiteral<"local">;
+        email: z.ZodOptional<z.ZodString>;
+        fullName: z.ZodOptional<z.ZodString>;
+        userId: z.ZodString;
+        userName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "platform">>;
+    runId: z.ZodString;
+    source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        platform: z.ZodLiteral<"slack">;
+        teamId: z.ZodString;
+        channelId: z.ZodString;
+        type: z.ZodEnum<{
+            pub: "pub";
+            priv: "priv";
+        }>;
+        messageTs: z.ZodOptional<z.ZodString>;
+        threadTs: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        platform: z.ZodLiteral<"local">;
+        type: z.ZodLiteral<"priv">;
+        conversationId: z.ZodString;
+    }, z.core.$strict>], "platform">;
+    transcript: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"message">;
+        role: z.ZodEnum<{
+            user: "user";
+            assistant: "assistant";
+        }>;
+        text: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"toolResult">;
+        toolName: z.ZodString;
+        isError: z.ZodBoolean;
+        text: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "type">>;
+}, z.core.$strict>;
+export type PluginRunTranscriptEntry = z.output<typeof pluginRunTranscriptEntrySchema>;
+export type PluginRunContext = z.output<typeof pluginRunContextSchema>;
+/** Runtime context passed to a plugin-owned background task. */
+export interface PluginTaskContext extends PluginContext {
+    embedder: PluginEmbedder;
+    id: string;
+    model: PluginModel;
+    name: string;
+    run: {
+        load(): Promise<PluginRunContext>;
+    };
+    state: PluginState;
+}
+/** Plugin task handler registered by name in a plugin manifest module. */
+export interface PluginTaskDefinition {
+    run(ctx: PluginTaskContext): Promise<void> | void;
+}
+/** Task handlers keyed by the plugin-owned task name. */
+export type PluginTasks = Record<string, PluginTaskDefinition>;

package/dist/tools.d.ts

@@ -1,4 +1,4 @@
-import type { PluginContext, LocalInvocationContext, Requester, SlackInvocationContext } from "./context";
+import type { PluginContext, LocalInvocationContext, PluginEmbedder, PluginModel, Requester, SlackInvocationContext } from "./context";
 import type { PluginCredentialSubject } from "./credentials";
 import type { PluginState } from "./state";
 export interface PluginEnv {
@@ -49,10 +49,17 @@ export interface BeforeToolExecuteHookContext extends PluginContext {
         name: string;
     };
 }
+export interface PluginToolExecuteOptions {
+    /**
+     * @deprecated Internal compatibility escape hatch for legacy tool bridges.
+     * Plugin tools should use typed input fields and runtime hook context instead.
+     */
+    experimental_context?: unknown;
+    /** 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: {
-        experimental_context?: unknown;
-    }): Promise<unknown> | unknown;
+    bivarianceHack(input: TInput, options: PluginToolExecuteOptions): Promise<unknown> | unknown;
 }["bivarianceHack"];
 export interface PluginToolDefinition<TInput = unknown> {
     annotations?: unknown;
@@ -94,6 +101,8 @@ interface BaseToolRegistrationHookContext extends PluginContext {
      * Do not parse as Slack unless the value starts with `slack:`.
      */
     conversationId?: string;
+    embedder: PluginEmbedder;
+    model: PluginModel;
     state: PluginState;
     userText?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-plugin-api",
-  "version": "0.75.0",
+  "version": "0.76.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -22,7 +22,7 @@
     "src"
   ],
   "dependencies": {
-    "drizzle-orm": "^0.45.2",
+    "commander": "^14.0.3",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/src/cli.ts

@@ -0,0 +1,54 @@
+/**
+ * Public Commander-based CLI contract for plugin-owned admin commands.
+ * Junior owns the root command, plugin namespaces, context injection, and exit
+ * normalization; plugins only configure subcommands under their namespace.
+ */
+import type { Command } from "commander";
+import type { PluginContext } from "./context";
+
+export interface PluginCliIo {
+  writeError(text: string): Promise<void> | void;
+  writeOutput(text: string): Promise<void> | void;
+}
+
+export interface PluginCliActionCommand {
+  name: string;
+  summary: string;
+}
+
+/** Host/admin context exposed to plugin-owned CLI command actions. */
+export interface PluginCliActionContext extends Pick<
+  PluginContext,
+  "db" | "log" | "plugin"
+> {
+  command: PluginCliActionCommand;
+  io: PluginCliIo;
+}
+
+/** Plugin action callback wrapped by the Junior host for context and exit codes. */
+export type PluginCliActionHandler<Args extends unknown[] = unknown[]> = (
+  ctx: PluginCliActionContext,
+  ...args: Args
+) => Promise<number | void> | number | void;
+
+export interface PluginCliHost {
+  /** Wrap a Commander action so Junior can inject context and normalize exits. */
+  action<Args extends unknown[]>(
+    handler: PluginCliActionHandler<Args>,
+  ): (...args: Args) => Promise<void>;
+}
+
+/** Plugin-owned top-level CLI command registration. */
+export interface PluginCliCommandDefinition {
+  /** Configure subcommands under the host-created top-level namespace. */
+  configure(command: Command, junior: PluginCliHost): void;
+  /** Unique host-level command namespace owned by this plugin. */
+  name: string;
+  /** One-line summary used in generated command help. */
+  summary: string;
+}
+
+/** Plugin-owned CLI command catalog. */
+export interface PluginCliDefinition {
+  commands: PluginCliCommandDefinition[];
+}

package/src/context.ts

@@ -1,19 +1,23 @@
 import { z } from "zod";
+import type { ZodTypeAny } from "zod";
 import {
   destinationSchema,
   localRequesterSchema,
+  platformSchema,
   requesterSchema,
   slackRequesterSchema,
   sourceSchema,
 } from "./schemas";
-import type { PluginDb } from "./database";
 
+/** Runtime platform name without source or destination coordinates. */
+export type Platform = z.output<typeof platformSchema>;
 export type Requester = z.output<typeof requesterSchema>;
 export type SlackRequester = z.output<typeof slackRequesterSchema>;
 export type LocalRequester = z.output<typeof localRequesterSchema>;
 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 Destination = z.output<typeof destinationSchema>;
 
@@ -31,9 +35,29 @@ export interface PluginLogger {
   warn(message: string, metadata?: Record<string, unknown>): void;
 }
 
+export interface PluginModel {
+  /** Run a host-owned structured model call without exposing provider credentials. */
+  completeObject<TSchema extends ZodTypeAny>(input: {
+    maxTokens?: number;
+    prompt: string;
+    schema: TSchema;
+    system?: string;
+  }): Promise<{ object: z.infer<TSchema> }>;
+}
+
+export interface PluginEmbedder {
+  /** Embed plugin-owned text for derived retrieval without exposing provider credentials. */
+  embedTexts(input: { texts: string[] }): Promise<{
+    dimensions: number;
+    model: string;
+    provider: string;
+    vectors: number[][];
+  }>;
+}
+
 export interface PluginContext {
-  /** Shared database connection for plugins that declare database access. */
-  db?: PluginDb;
+  /** Shared Drizzle database connection for plugin runtime code. */
+  db: unknown;
   log: PluginLogger;
   plugin: PluginMetadata;
 }
@@ -47,16 +71,16 @@ interface BaseInvocationContext {
 }
 
 export interface SlackInvocationContext extends BaseInvocationContext {
-  /** Runtime-owned default outbound destination for this invocation, if any. */
-  destination?: SlackDestination;
+  /** Runtime-owned default outbound destination for this invocation. */
+  destination: SlackDestination;
   requester?: SlackRequester;
   /** Runtime-owned source where the invocation came from. */
   source: SlackSource;
 }
 
 export interface LocalInvocationContext extends BaseInvocationContext {
-  /** Runtime-owned default outbound destination for this invocation, if any. */
-  destination?: LocalDestination;
+  /** Runtime-owned default outbound destination for this invocation. */
+  destination: LocalDestination;
   requester?: LocalRequester;
   /** Runtime-owned source where the invocation came from. */
   source: LocalSource;
@@ -64,6 +88,56 @@ export interface LocalInvocationContext extends BaseInvocationContext {
 
 export type InvocationContext = LocalInvocationContext | SlackInvocationContext;
 
+/** Build a normalized Slack source from runtime-owned Slack coordinates. */
+export function createSlackSource(input: {
+  channelId: string;
+  messageTs?: string;
+  teamId: string;
+  threadTs?: string;
+}): SlackSource {
+  return {
+    platform: "slack",
+    type: slackSourceType(input.channelId),
+    teamId: input.teamId,
+    channelId: input.channelId,
+    ...(input.messageTs ? { messageTs: input.messageTs } : {}),
+    ...(input.threadTs ? { threadTs: input.threadTs } : {}),
+  };
+}
+
+/** Classify Slack's documented C/D/G channel id prefixes into source visibility. */
+function slackSourceType(channelId: string): SourceType {
+  if (channelId.startsWith("C")) return "pub";
+  if (channelId.startsWith("D") || channelId.startsWith("G")) return "priv";
+  throw new Error(`Unsupported Slack channel ID prefix: ${channelId}`);
+}
+
+/** Build a normalized local source from a local conversation id. */
+export function createLocalSource(conversationId: string): LocalSource {
+  return {
+    platform: "local",
+    type: "priv",
+    conversationId,
+  };
+}
+
+/** Return whether a source is private to a person or restricted group. */
+export function isPrivateSource(source: Source): boolean {
+  return source.type === "priv";
+}
+
+/** Return the stable source identity used for idempotency and attribution. */
+export function getSourceKey(source: Source): string | undefined {
+  if (source.platform === "local") {
+    return source.conversationId;
+  }
+  const messageKey = source.threadTs ?? source.messageTs;
+  if (!messageKey) {
+    return undefined;
+  }
+  return `slack:${source.teamId}:${source.channelId}:${messageKey}`;
+}
+
 /** Narrow a runtime destination to the Slack-specific address shape. */
 export function isSlackDestination(
   destination: Destination | undefined,

package/src/credentials.ts

@@ -27,6 +27,18 @@ export const pluginProviderAccountSchema = z
   })
   .strict();
 
+/** Runtime schema for OAuth tokens stored by the host for plugin credentials. */
+export const pluginStoredTokensSchema = z
+  .object({
+    account: pluginProviderAccountSchema.optional(),
+    accessToken: nonBlankStringSchema,
+    expiresAt: z.number().finite().optional(),
+    refreshToken: nonBlankStringSchema,
+    refreshTokenExpiresAt: z.number().finite().optional(),
+    scope: nonBlankStringSchema.optional(),
+  })
+  .strict();
+
 /** Runtime schema for a plugin-defined outbound credential grant. */
 export const pluginGrantSchema = z
   .object({
@@ -169,17 +181,13 @@ export interface PluginResolvedCredentialUser {
   userId: string;
 }
 
-export interface PluginStoredTokens {
-  account?: PluginProviderAccount;
-  accessToken: string;
-  expiresAt?: number;
-  refreshToken: string;
-  scope?: string;
-}
+export type PluginStoredTokens = z.output<typeof pluginStoredTokensSchema>;
 
 export interface PluginUserTokenSlot {
   get(): Promise<PluginStoredTokens | undefined>;
   set(tokens: PluginStoredTokens): Promise<void>;
+  /** Run token refresh work after the host has serialized this user/provider slot, or throw after a bounded wait. */
+  withRefresh<T>(callback: () => Promise<T>): Promise<T>;
   userId: string;
 }
 

package/src/hooks.ts

@@ -25,8 +25,19 @@ import type {
   SandboxPrepareHookContext,
   ToolRegistrationHookContext,
 } from "./tools";
+import type {
+  PromptMessage,
+  SystemPromptContext,
+  UserPromptContext,
+} from "./prompt";
 
 export interface PluginHooks {
+  systemPrompt?(
+    ctx: SystemPromptContext,
+  ): Promise<PromptMessage[]> | PromptMessage[];
+  userPrompt?(
+    ctx: UserPromptContext,
+  ): Promise<PromptMessage[] | undefined> | PromptMessage[] | undefined;
   beforeToolExecute?(ctx: BeforeToolExecuteHookContext): Promise<void> | void;
   grantForEgress?(
     ctx: EgressHookContext,

package/src/index.ts

@@ -1,11 +1,18 @@
 export * from "./schemas";
 export * from "./context";
 export * from "./state";
+export {
+  promptMessageSchema,
+  type PromptMessage,
+  type SystemPromptContext,
+  type UserPromptContext,
+} from "./prompt";
 export * from "./dispatch";
-export * from "./database";
+export * from "./tasks";
 export * from "./tools";
 export * from "./operations";
 export * from "./credentials";
 export * from "./hooks";
+export * from "./cli";
 export * from "./manifest";
 export * from "./registration";

package/src/operations.ts

@@ -1,5 +1,4 @@
 import type { PluginContext } from "./context";
-import type { PluginDb } from "./database";
 import type { Dispatch, DispatchOptions, DispatchResult } from "./dispatch";
 import type { PluginReadState, PluginState } from "./state";
 
@@ -48,7 +47,6 @@ export interface StorageMigrationResult {
 }
 
 export interface StorageMigrationContext extends PluginContext {
-  db: PluginDb;
   state: PluginState;
 }
 

package/src/prompt.ts

@@ -1,59 +1,38 @@
-import type { InvocationContext, PluginContext } from "./context";
+import { z } from "zod";
 import type {
-  PluginSessionState,
-  PluginSessionStateAppend,
-  PluginState,
-} from "./state";
-
-export interface UserPromptContribution {
-  id: string;
-  text: string;
-}
-
-export interface UserPromptContributionResult {
-  contributions?: UserPromptContribution[];
-  sessionState?: PluginSessionStateAppend[];
-}
-
-export type UserPromptHookContext = PluginContext &
-  InvocationContext & {
-    isFirstPrompt: boolean;
-    session: PluginSessionState;
-    state: PluginState;
-    userText: string;
-  };
-
-export interface PluginTaskEnqueueOptions {
-  idempotencyKey: string;
-  name: string;
-  payload?: unknown;
-}
-
-export interface PluginTaskEnqueueResult {
-  id: string;
-  status: "created" | "already_exists";
-}
-
-export interface PluginTaskQueue {
-  enqueue(options: PluginTaskEnqueueOptions): Promise<PluginTaskEnqueueResult>;
-}
-
-export type TurnObservationHookContext = PluginContext &
-  InvocationContext & {
-    observationId: string;
-    tasks: PluginTaskQueue;
-  };
-
-export interface PluginTaskContext extends PluginContext {
-  id: string;
-  name: string;
-  observation?: {
-    load(): Promise<unknown | undefined>;
-  };
-  payload?: unknown;
+  Destination,
+  Platform,
+  PluginContext,
+  PluginEmbedder,
+  Requester,
+  Source,
+} from "./context";
+import type { PluginState } from "./state";
+
+export const promptMessageSchema = z
+  .object({
+    text: z.string().trim().min(1).max(8_000),
+  })
+  .strict();
+
+/** Small plugin-owned prompt text block rendered by Junior core. */
+export type PromptMessage = z.output<typeof promptMessageSchema>;
+
+/** Stable platform context for plugin system prompt guidance. */
+export type SystemPromptContext = Pick<
+  PluginContext,
+  "db" | "log" | "plugin"
+> & {
+  platform: Platform;
+};
+
+/** Runtime facts available while building plugin user prompt context. */
+export type UserPromptContext = Pick<PluginContext, "db" | "log" | "plugin"> & {
+  conversationId?: string;
+  destination: Destination;
+  embedder: PluginEmbedder;
+  requester?: Requester;
+  source: Source;
   state: PluginState;
-}
-
-export type PluginTaskHandler = (
-  ctx: PluginTaskContext,
-) => Promise<void> | void;
+  text: string;
+};

package/src/registration.ts

@@ -1,12 +1,22 @@
-import type { PluginDatabaseConfig } from "./database";
+import type { PluginCliDefinition } from "./cli";
 import type { PluginHooks } from "./hooks";
 import type { PluginManifest } from "./manifest";
+import type { PluginTasks } from "./tasks";
+
+export interface PluginModelConfig {
+  /** Host model family used when no explicit structured model id is configured. */
+  structuredModel?: "default" | "fast";
+  /** Host model id used for this plugin's structured model calls. */
+  structuredModelId?: string;
+}
 
 export type PluginRegistrationInput = {
-  database?: PluginDatabaseConfig;
+  cli?: PluginCliDefinition;
   hooks?: PluginHooks;
   manifest: PluginManifest;
+  model?: PluginModelConfig;
   packageName?: string;
+  tasks?: PluginTasks;
 };
 
 export interface PluginRegistration extends PluginRegistrationInput {}

package/src/schemas.ts

@@ -16,8 +16,13 @@ export const nonBlankStringSchema = z
   .string()
   .refine((value) => value.trim().length > 0);
 
-/** Runtime-owned Slack address for routing future work or side effects. */
-export const slackDestinationSchema = z
+/** Runtime platform names supported by plugin public contracts. */
+export const platformSchema = z.enum(["slack", "local"]);
+
+/** Runtime source visibility visible to plugins. */
+export const sourceTypeSchema = z.enum(["pub", "priv"]);
+
+const slackAddressSchema = z
   .object({
     platform: z.literal("slack"),
     teamId: slackTeamIdSchema,
@@ -25,6 +30,9 @@ export const slackDestinationSchema = z
   })
   .strict();
 
+/** Runtime-owned Slack address for routing future work or side effects. */
+export const slackDestinationSchema = slackAddressSchema;
+
 /** Runtime-owned local CLI conversation address. */
 export const localDestinationSchema = z
   .object({
@@ -40,18 +48,22 @@ export const destinationSchema = z.discriminatedUnion("platform", [
 ]);
 
 /** Runtime-owned Slack coordinates for the inbound invocation. */
-export const slackSourceSchema = z
-  .object({
-    platform: z.literal("slack"),
-    teamId: slackTeamIdSchema,
-    channelId: slackConversationIdSchema,
+export const slackSourceSchema = slackAddressSchema
+  .extend({
+    type: sourceTypeSchema,
     messageTs: nonBlankStringSchema.optional(),
     threadTs: nonBlankStringSchema.optional(),
   })
   .strict();
 
 /** Runtime-owned local CLI coordinates for the inbound invocation. */
-export const localSourceSchema = localDestinationSchema;
+export const localSourceSchema = z
+  .object({
+    platform: z.literal("local"),
+    type: z.literal("priv"),
+    conversationId: localConversationIdSchema,
+  })
+  .strict();
 
 /** Runtime-owned provider-neutral coordinates for the inbound invocation. */
 export const sourceSchema = z.discriminatedUnion("platform", [

package/src/state.ts

@@ -13,14 +13,3 @@ export interface PluginState {
 export interface PluginReadState {
   get<T = unknown>(key: string): Promise<T | undefined>;
 }
-
-export interface PluginSessionStateAppend {
-  key: string;
-  value: unknown;
-}
-
-export interface PluginSessionState {
-  list<T = unknown>(
-    key: string,
-  ): Promise<Array<{ createdAtMs: number; value: T }>>;
-}