@sentry/junior-plugin-api 0.74.1 → 0.76.0

package/src/manifest.ts

@@ -0,0 +1,87 @@
+export interface PluginOAuthConfig {
+  authorizeEndpoint: string;
+  authorizeParams?: Record<string, string>;
+  clientIdEnv: string;
+  clientSecretEnv: string;
+  scope?: string;
+  /**
+   * Treat a provider token response with `scope: ""` like an omitted scope and
+   * fall back to the requested scope string when storing the token.
+   */
+  treatEmptyScopeAsUnreported?: boolean;
+  tokenAuthMethod?: "body" | "basic";
+  tokenEndpoint: string;
+  tokenExtraHeaders?: Record<string, string>;
+}
+
+export interface PluginOAuthBearerCredentials {
+  apiHeaders?: Record<string, string>;
+  authTokenEnv: string;
+  authTokenPlaceholder?: string;
+  domains: string[];
+  type: "oauth-bearer";
+}
+
+export type PluginCredentials = PluginOAuthBearerCredentials;
+
+export interface PluginNpmRuntimeDependency {
+  package: string;
+  type: "npm";
+  version: string;
+}
+
+export interface PluginSystemRuntimeDependency {
+  package: string;
+  type: "system";
+}
+
+export interface PluginSystemRuntimeDependencyFromUrl {
+  sha256: string;
+  type: "system";
+  url: string;
+}
+
+export type PluginRuntimeDependency =
+  | PluginNpmRuntimeDependency
+  | PluginSystemRuntimeDependency
+  | PluginSystemRuntimeDependencyFromUrl;
+
+export interface PluginRuntimePostinstallCommand {
+  args?: string[];
+  cmd: string;
+  sudo?: boolean;
+}
+
+export interface PluginMcpConfig {
+  allowedTools?: string[];
+  headers?: Record<string, string>;
+  transport: "http";
+  url: string;
+}
+
+export interface PluginEnvVarDeclaration {
+  default?: string;
+  exposeToCommandEnv?: boolean;
+}
+
+export interface PluginManifest {
+  apiHeaders?: Record<string, string>;
+  capabilities?: string[];
+  commandEnv?: Record<string, string>;
+  configKeys?: string[];
+  credentials?: PluginCredentials;
+  description: string;
+  displayName: string;
+  domains?: string[];
+  envVars?: Record<string, PluginEnvVarDeclaration>;
+  mcp?: PluginMcpConfig;
+  name: string;
+  oauth?: PluginOAuthConfig;
+  runtimeDependencies?: PluginRuntimeDependency[];
+  runtimePostinstall?: PluginRuntimePostinstallCommand[];
+  target?: {
+    commandFlags?: string[];
+    configKey: string;
+    type: string;
+  };
+}

package/src/operations.ts

@@ -0,0 +1,124 @@
+import type { PluginContext } from "./context";
+import type { Dispatch, DispatchOptions, DispatchResult } from "./dispatch";
+import type { PluginReadState, PluginState } from "./state";
+
+export type PluginConversationStatus =
+  | "active"
+  | "completed"
+  | "failed"
+  | "hung"
+  | "superseded";
+
+export interface PluginConversationSummary {
+  channelName?: string;
+  conversationId: string;
+  displayTitle: string;
+  lastActivityAt: string;
+  lastUpdatedAt: string;
+  source?: "api" | "internal" | "local" | "plugin" | "scheduler" | "slack";
+  status: PluginConversationStatus;
+}
+
+export interface PluginConversations {
+  listRecent(options?: {
+    limit?: number;
+  }): Promise<PluginConversationSummary[]>;
+}
+
+export interface HeartbeatHookContext extends PluginContext {
+  agent: {
+    dispatch(options: DispatchOptions): Promise<DispatchResult>;
+    get(id: string): Promise<Dispatch | undefined>;
+  };
+  nowMs: number;
+  state: PluginState;
+}
+
+export interface HeartbeatResult {
+  dispatchCount?: number;
+}
+
+export interface StorageMigrationResult {
+  existing: number;
+  migrated: number;
+  missing: number;
+  scanned: number;
+  skipped?: number;
+}
+
+export interface StorageMigrationContext extends PluginContext {
+  state: PluginState;
+}
+
+export type PluginOperationalTone = "danger" | "good" | "neutral" | "warning";
+
+export interface PluginOperationalMetric {
+  label: string;
+  tone?: PluginOperationalTone;
+  value: string;
+}
+
+export interface PluginOperationalField {
+  key: string;
+  label: string;
+}
+
+export interface PluginOperationalRecord {
+  id: string;
+  tone?: PluginOperationalTone;
+  values: Record<string, string>;
+}
+
+export interface PluginOperationalRecordSet {
+  fields?: PluginOperationalField[];
+  emptyText?: string;
+  records?: PluginOperationalRecord[];
+  title: string;
+}
+
+export interface PluginOperationalReportContent {
+  generatedAt?: string;
+  metrics?: PluginOperationalMetric[];
+  recordSets?: PluginOperationalRecordSet[];
+  title?: string;
+}
+
+export interface PluginOperationalReport extends PluginOperationalReportContent {
+  pluginName: string;
+}
+
+export interface OperationalReportHookContext extends PluginContext {
+  conversations: PluginConversations;
+  nowMs: number;
+  state: PluginReadState;
+}
+
+export type PluginRouteMethod =
+  | "GET"
+  | "POST"
+  | "PUT"
+  | "PATCH"
+  | "DELETE"
+  | "HEAD"
+  | "OPTIONS"
+  | "ALL";
+
+export type PluginRouteHandler = {
+  bivarianceHack(request: Request): Promise<Response> | Response;
+}["bivarianceHack"];
+
+export interface PluginRoute {
+  handler: PluginRouteHandler;
+  method?: PluginRouteMethod | PluginRouteMethod[];
+  path: string;
+}
+
+export interface RouteRegistrationHookContext extends PluginContext {}
+
+export interface SlackConversationLink {
+  url: string;
+}
+
+export interface SlackConversationLinkHookContext extends PluginContext {
+  conversationId: string;
+}

package/src/prompt.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import type {
+  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;
+  text: string;
+};

package/src/registration.ts

@@ -0,0 +1,72 @@
+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 = {
+  cli?: PluginCliDefinition;
+  hooks?: PluginHooks;
+  manifest: PluginManifest;
+  model?: PluginModelConfig;
+  packageName?: string;
+  tasks?: PluginTasks;
+};
+
+export interface PluginRegistration extends PluginRegistrationInput {}
+
+const PLUGIN_NAME_RE = /^[a-z][a-z0-9-]*$/;
+
+/** Define one Junior plugin registration for app and build-time wiring. */
+export function defineJuniorPlugin(
+  plugin: PluginRegistrationInput,
+): PluginRegistration {
+  if ("pluginConfig" in plugin) {
+    throw new Error(
+      "pluginConfig is no longer supported. Put runtime metadata in manifest or plugin registration fields.",
+    );
+  }
+  if ("name" in plugin) {
+    throw new Error("defineJuniorPlugin() uses manifest.name for identity.");
+  }
+  const manifest = plugin.manifest;
+  if (!manifest) {
+    throw new Error(
+      "defineJuniorPlugin() requires a manifest. Use a package name string in defineJuniorPlugins([...]) for plugin.yaml packages.",
+    );
+  }
+  const name = manifest.name;
+  if (!name) {
+    throw new Error("Junior plugin manifest.name is required.");
+  }
+  if (!PLUGIN_NAME_RE.test(name)) {
+    throw new Error(
+      `Junior plugin registration name "${name}" must be a lowercase plugin identifier.`,
+    );
+  }
+  if (
+    typeof manifest.displayName !== "string" ||
+    !manifest.displayName.trim()
+  ) {
+    throw new Error(
+      `Junior plugin "${name}" manifest.displayName is required.`,
+    );
+  }
+  if (
+    typeof manifest.description !== "string" ||
+    !manifest.description.trim()
+  ) {
+    throw new Error(
+      `Junior plugin "${name}" manifest.description is required.`,
+    );
+  }
+  return {
+    ...plugin,
+  };
+}

package/src/schemas.ts

@@ -0,0 +1,173 @@
+import { z } from "zod";
+
+const slackTeamIdSchema = z.string().regex(/^T[A-Z0-9]+$/);
+const slackConversationIdSchema = z.string().regex(/^(C|G|D)[A-Z0-9]+$/);
+const localConversationIdSchema = z
+  .string()
+  .regex(/^local:[a-z0-9_-]+:[a-z0-9][a-z0-9_-]*$/);
+const exactActorUserIdSchema = z
+  .string()
+  .min(1)
+  .refine(
+    (value) => value === value.trim() && value.toLowerCase() !== "unknown",
+  );
+
+export const nonBlankStringSchema = z
+  .string()
+  .refine((value) => value.trim().length > 0);
+
+/** 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,
+    channelId: slackConversationIdSchema,
+  })
+  .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({
+    platform: z.literal("local"),
+    conversationId: localConversationIdSchema,
+  })
+  .strict();
+
+/** Runtime-owned provider-neutral address for routing future work or side effects. */
+export const destinationSchema = z.discriminatedUnion("platform", [
+  slackDestinationSchema,
+  localDestinationSchema,
+]);
+
+/** Runtime-owned Slack coordinates for the inbound invocation. */
+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 = 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", [
+  slackSourceSchema,
+  localSourceSchema,
+]);
+
+/** Stable user credential subject shape accepted from plugins. */
+export const pluginCredentialSubjectSchema = z
+  .object({
+    type: z.literal("user"),
+    userId: exactActorUserIdSchema,
+    allowedWhen: z.literal("private-direct-conversation"),
+  })
+  .strict();
+
+/** Shared exact actor profile fields for platform-scoped requesters. */
+const requesterProfileSchema = {
+  email: nonBlankStringSchema.optional(),
+  fullName: nonBlankStringSchema.optional(),
+  userId: exactActorUserIdSchema,
+  userName: nonBlankStringSchema.optional(),
+};
+
+export const slackRequesterSchema = z
+  .object({
+    ...requesterProfileSchema,
+    platform: z.literal("slack"),
+    teamId: slackTeamIdSchema,
+  })
+  .strict();
+
+export const localRequesterSchema = z
+  .object({
+    ...requesterProfileSchema,
+    platform: z.literal("local"),
+  })
+  .strict();
+
+/** Runtime-provided requester identity visible to plugin hooks. */
+export const requesterSchema = z.discriminatedUnion("platform", [
+  slackRequesterSchema,
+  localRequesterSchema,
+]);
+
+const dispatchMetadataSchema = z
+  .record(z.string(), z.string())
+  .superRefine((metadata, ctx) => {
+    const entries = Object.entries(metadata);
+    if (entries.length > 20) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Dispatch metadata has too many keys",
+      });
+      return;
+    }
+    for (const [key, value] of entries) {
+      if (!key.trim()) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Dispatch metadata values must be strings",
+          path: [key],
+        });
+        continue;
+      }
+      if (key.length > 128) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Dispatch metadata key exceeds the maximum length",
+          path: [key],
+        });
+      }
+      if (/[\r\n]/.test(key)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Dispatch metadata keys must be single-line strings",
+          path: [key],
+        });
+      }
+      if (/[\r\n]/.test(value)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Dispatch metadata values must be single-line strings",
+          path: [key],
+        });
+      }
+      if (value.length > 512) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Dispatch metadata value exceeds the maximum length",
+          path: [key],
+        });
+      }
+    }
+  });
+
+/** Plugin dispatch request accepted by Junior core. */
+export const dispatchOptionsSchema = z
+  .object({
+    idempotencyKey: nonBlankStringSchema.pipe(z.string().max(512)),
+    credentialSubject: pluginCredentialSubjectSchema.optional(),
+    destination: slackDestinationSchema,
+    input: nonBlankStringSchema.pipe(z.string().max(32_000)),
+    metadata: dispatchMetadataSchema.optional(),
+    source: sourceSchema,
+  })
+  .strict();

package/src/state.ts

@@ -0,0 +1,15 @@
+export interface PluginState {
+  delete(key: string): Promise<void>;
+  get<T = unknown>(key: string): Promise<T | undefined>;
+  set(key: string, value: unknown, ttlMs?: number): Promise<void>;
+  setIfNotExists(key: string, value: unknown, ttlMs?: number): Promise<boolean>;
+  withLock<T>(
+    key: string,
+    ttlMs: number,
+    callback: () => Promise<T>,
+  ): Promise<T>;
+}
+
+export interface PluginReadState {
+  get<T = unknown>(key: string): Promise<T | undefined>;
+}

package/src/tasks.ts

@@ -0,0 +1,68 @@
+/**
+ * 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 { destinationSchema, requesterSchema, sourceSchema } from "./schemas";
+import type { PluginState } from "./state";
+
+/** One normalized transcript entry from the completed run exposed to plugin tasks. */
+export const pluginRunTranscriptEntrySchema = z.discriminatedUnion("type", [
+  z
+    .object({
+      type: z.literal("message"),
+      role: z.enum(["user", "assistant"]),
+      text: z.string().min(1),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal("toolResult"),
+      toolName: z.string().min(1),
+      isError: z.boolean(),
+      text: z.string().min(1).optional(),
+    })
+    .strict(),
+]);
+
+/** Runtime-owned completed-run projection exposed to plugin tasks. */
+export const pluginRunContextSchema = z
+  .object({
+    completedAtMs: z.number().finite(),
+    conversationId: z.string().min(1),
+    destination: destinationSchema,
+    requester: requesterSchema.optional(),
+    runId: z.string().min(1),
+    source: sourceSchema,
+    transcript: z.array(pluginRunTranscriptEntrySchema),
+  })
+  .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>;