@sentry/junior-plugin-api 0.74.0 → 0.75.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,126 @@
+import type { PluginContext } from "./context";
+import type { PluginDb } from "./database";
+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 {
+  db: PluginDb;
+  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,59 @@
+import type { InvocationContext, PluginContext } from "./context";
+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;
+  state: PluginState;
+}
+
+export type PluginTaskHandler = (
+  ctx: PluginTaskContext,
+) => Promise<void> | void;

package/src/registration.ts

@@ -0,0 +1,62 @@
+import type { PluginDatabaseConfig } from "./database";
+import type { PluginHooks } from "./hooks";
+import type { PluginManifest } from "./manifest";
+
+export type PluginRegistrationInput = {
+  database?: PluginDatabaseConfig;
+  hooks?: PluginHooks;
+  manifest: PluginManifest;
+  packageName?: string;
+};
+
+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,161 @@
+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-owned Slack address for routing future work or side effects. */
+export const slackDestinationSchema = z
+  .object({
+    platform: z.literal("slack"),
+    teamId: slackTeamIdSchema,
+    channelId: slackConversationIdSchema,
+  })
+  .strict();
+
+/** 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 = z
+  .object({
+    platform: z.literal("slack"),
+    teamId: slackTeamIdSchema,
+    channelId: slackConversationIdSchema,
+    messageTs: nonBlankStringSchema.optional(),
+    threadTs: nonBlankStringSchema.optional(),
+  })
+  .strict();
+
+/** Runtime-owned local CLI coordinates for the inbound invocation. */
+export const localSourceSchema = localDestinationSchema;
+
+/** 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,26 @@
+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>;
+}
+
+export interface PluginSessionStateAppend {
+  key: string;
+  value: unknown;
+}
+
+export interface PluginSessionState {
+  list<T = unknown>(
+    key: string,
+  ): Promise<Array<{ createdAtMs: number; value: T }>>;
+}

package/src/tools.ts

@@ -0,0 +1,130 @@
+import type {
+  PluginContext,
+  LocalInvocationContext,
+  Requester,
+  SlackInvocationContext,
+} from "./context";
+import type { PluginCredentialSubject } from "./credentials";
+import type { PluginState } from "./state";
+
+export interface PluginEnv {
+  get(key: string): string | undefined;
+  set(key: string, value: string): void;
+}
+
+export interface PluginDecision {
+  deny(message: string): void;
+  replaceInput(input: Record<string, unknown>): void;
+}
+
+/** Thrown when a plugin tool rejects invalid model or user input. */
+export class PluginToolInputError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "PluginToolInputError";
+  }
+}
+
+export interface PluginSandbox {
+  juniorRoot: string;
+  root: string;
+  readFile(path: string): Promise<Uint8Array | null>;
+  run(input: {
+    args?: string[];
+    cmd: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    sudo?: boolean;
+  }): Promise<{
+    exitCode: number;
+    stderr: string;
+    stdout: string;
+  }>;
+  writeFile(input: {
+    content: string | Uint8Array;
+    mode?: number;
+    path: string;
+  }): Promise<void>;
+}
+
+export interface SandboxPrepareHookContext extends PluginContext {
+  requester?: Requester;
+  sandbox: PluginSandbox;
+}
+
+export interface BeforeToolExecuteHookContext extends PluginContext {
+  decision: PluginDecision;
+  env: PluginEnv;
+  requester?: Requester;
+  tool: {
+    input: Record<string, unknown>;
+    name: string;
+  };
+}
+
+export type PluginToolExecute<TInput = unknown> = {
+  bivarianceHack(
+    input: TInput,
+    options: { experimental_context?: unknown },
+  ): Promise<unknown> | unknown;
+}["bivarianceHack"];
+
+export interface PluginToolDefinition<TInput = unknown> {
+  annotations?: unknown;
+  description: string;
+  executionMode?: unknown;
+  inputSchema: unknown;
+  prepareArguments?: (args: unknown) => unknown;
+  /**
+   * @deprecated Put tool-selection and usage guidance directly in `description`
+   * and parameter descriptions. Retained for compatibility; may be removed in a
+   * future major version.
+   */
+  promptGuidelines?: string[];
+  /**
+   * @deprecated Put tool-selection and usage guidance directly in `description`
+   * and parameter descriptions. Retained for compatibility; may be removed in a
+   * future major version.
+   */
+  promptSnippet?: string;
+  execute?: PluginToolExecute<TInput>;
+}
+
+export interface SlackToolRegistrationHookContext {
+  /**
+   * Capabilities of the source Slack conversation exposed to this plugin.
+   * Recomputed from `source.channelId`, not from `destination`.
+   */
+  channelCapabilities: {
+    canAddReactions: boolean;
+    canCreateCanvas: boolean;
+    canPostToChannel: boolean;
+  };
+  credentialSubject?: PluginCredentialSubject;
+}
+
+interface BaseToolRegistrationHookContext extends PluginContext {
+  /**
+   * Opaque Junior conversation/session identity for this turn.
+   * Interactive Slack turns use `slack:{channelId}:{threadTs}`.
+   * Scheduled/API turns use an internal id such as `agent-dispatch:{id}`.
+   * Do not parse as Slack unless the value starts with `slack:`.
+   */
+  conversationId?: string;
+  state: PluginState;
+  userText?: string;
+}
+
+interface SlackToolRegistrationContext
+  extends BaseToolRegistrationHookContext, SlackInvocationContext {
+  slack: SlackToolRegistrationHookContext;
+}
+
+interface LocalToolRegistrationContext
+  extends BaseToolRegistrationHookContext, LocalInvocationContext {
+  slack?: never;
+}
+
+export type ToolRegistrationHookContext =
+  | LocalToolRegistrationContext
+  | SlackToolRegistrationContext;