@sentry/junior-plugin-api 0.62.0 → 0.64.0

package/dist/index.d.ts

@@ -146,20 +146,117 @@ export interface HeartbeatHookContext extends AgentPluginContext {
 export interface HeartbeatResult {
     dispatchCount?: number;
 }
+export type AgentPluginRouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "ALL";
+export type AgentPluginRouteHandler = {
+    bivarianceHack(request: Request): Promise<Response> | Response;
+}["bivarianceHack"];
+export interface AgentPluginRoute {
+    handler: AgentPluginRouteHandler;
+    method?: AgentPluginRouteMethod | AgentPluginRouteMethod[];
+    path: string;
+}
+export interface RouteRegistrationHookContext extends AgentPluginContext {
+}
+export interface SlackConversationLink {
+    url: string;
+}
+export interface SlackConversationLinkHookContext extends AgentPluginContext {
+    conversationId: string;
+}
 export interface AgentPluginHooks {
     sandboxPrepare?(ctx: SandboxPrepareHookContext): Promise<void> | void;
     beforeToolExecute?(ctx: BeforeToolExecuteHookContext): Promise<void> | void;
+    routes?(ctx: RouteRegistrationHookContext): AgentPluginRoute[];
     tools?(ctx: ToolRegistrationHookContext): Record<string, AgentPluginToolDefinition>;
     heartbeat?(ctx: HeartbeatHookContext): Promise<HeartbeatResult | void> | HeartbeatResult | void;
+    slackConversationLink?(ctx: SlackConversationLinkHookContext): SlackConversationLink | undefined;
 }
-export interface JuniorPluginConfig {
-    legacyStatePrefixes?: string[];
-    packages?: string[];
+export interface JuniorPluginOAuthConfig {
+    authorizeEndpoint: string;
+    authorizeParams?: Record<string, string>;
+    clientIdEnv: string;
+    clientSecretEnv: string;
+    scope?: string;
+    tokenAuthMethod?: "body" | "basic";
+    tokenEndpoint: string;
+    tokenExtraHeaders?: Record<string, string>;
+}
+export interface JuniorPluginOAuthBearerCredentials {
+    apiHeaders?: Record<string, string>;
+    authTokenEnv: string;
+    authTokenPlaceholder?: string;
+    domains: string[];
+    type: "oauth-bearer";
+}
+export interface JuniorPluginGitHubAppCredentials {
+    apiHeaders?: Record<string, string>;
+    appIdEnv: string;
+    authTokenEnv: string;
+    authTokenPlaceholder?: string;
+    domains: string[];
+    installationIdEnv: string;
+    privateKeyEnv: string;
+    type: "github-app";
+}
+export type JuniorPluginCredentials = JuniorPluginOAuthBearerCredentials | JuniorPluginGitHubAppCredentials;
+export interface JuniorPluginNpmRuntimeDependency {
+    package: string;
+    type: "npm";
+    version: string;
+}
+export interface JuniorPluginSystemRuntimeDependency {
+    package: string;
+    type: "system";
 }
-export interface JuniorPlugin {
+export interface JuniorPluginSystemRuntimeDependencyFromUrl {
+    sha256: string;
+    type: "system";
+    url: string;
+}
+export type JuniorPluginRuntimeDependency = JuniorPluginNpmRuntimeDependency | JuniorPluginSystemRuntimeDependency | JuniorPluginSystemRuntimeDependencyFromUrl;
+export interface JuniorPluginRuntimePostinstallCommand {
+    args?: string[];
+    cmd: string;
+    sudo?: boolean;
+}
+export interface JuniorPluginMcpConfig {
+    allowedTools?: string[];
+    headers?: Record<string, string>;
+    transport: "http";
+    url: string;
+}
+export interface JuniorPluginEnvVarDeclaration {
+    default?: string;
+}
+export interface JuniorPluginManifest {
+    apiHeaders?: Record<string, string>;
+    capabilities?: string[];
+    commandEnv?: Record<string, string>;
+    configKeys?: string[];
+    credentials?: JuniorPluginCredentials;
+    description: string;
+    domains?: string[];
+    envVars?: Record<string, JuniorPluginEnvVarDeclaration>;
+    mcp?: JuniorPluginMcpConfig;
+    name: string;
+    oauth?: JuniorPluginOAuthConfig;
+    runtimeDependencies?: JuniorPluginRuntimeDependency[];
+    runtimePostinstall?: JuniorPluginRuntimePostinstallCommand[];
+    target?: {
+        commandFlags?: string[];
+        configKey: string;
+        type: string;
+    };
+}
+export type JuniorPluginRegistrationInput = {
     hooks?: AgentPluginHooks;
+    legacyStatePrefixes?: string[];
+    manifest: JuniorPluginManifest;
+    name?: string;
+    packageName?: string;
+};
+export interface JuniorPluginRegistration extends JuniorPluginRegistrationInput {
     name: string;
-    pluginConfig?: JuniorPluginConfig;
 }
-/** Define a trusted Junior plugin with optional package config and agent hooks. */
-export declare function defineJuniorPlugin(plugin: JuniorPlugin): JuniorPlugin;
+/** Define one Junior plugin registration for app and build-time wiring. */
+export declare function defineJuniorPlugin(plugin: JuniorPluginRegistrationInput): JuniorPluginRegistration;

package/dist/index.js

@@ -5,8 +5,44 @@ var AgentPluginToolInputError = class extends Error {
     this.name = "AgentPluginToolInputError";
   }
 };
+var PLUGIN_NAME_RE = /^[a-z][a-z0-9-]*$/;
 function defineJuniorPlugin(plugin) {
-  return plugin;
+  if ("pluginConfig" in plugin) {
+    throw new Error(
+      "pluginConfig is no longer supported. Put runtime metadata in manifest and trusted state prefixes on the plugin registration."
+    );
+  }
+  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 = plugin.name ?? manifest.name;
+  if (!name) {
+    throw new Error(
+      "Junior plugin registrations must include name or manifest.name."
+    );
+  }
+  if (!PLUGIN_NAME_RE.test(name)) {
+    throw new Error(
+      `Junior plugin registration name "${name}" must be a lowercase plugin identifier.`
+    );
+  }
+  if (typeof manifest.description !== "string" || !manifest.description.trim()) {
+    throw new Error(
+      `Junior plugin "${name}" manifest.description is required.`
+    );
+  }
+  if (plugin.name && manifest.name && plugin.name !== manifest.name) {
+    throw new Error(
+      `Junior plugin registration name "${plugin.name}" must match manifest.name "${manifest.name}".`
+    );
+  }
+  return {
+    ...plugin,
+    name
+  };
 }
 export {
   AgentPluginToolInputError,

package/package.json

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

package/src/index.ts

@@ -177,29 +177,200 @@ export interface HeartbeatResult {
   dispatchCount?: number;
 }
 
+export type AgentPluginRouteMethod =
+  | "GET"
+  | "POST"
+  | "PUT"
+  | "PATCH"
+  | "DELETE"
+  | "HEAD"
+  | "OPTIONS"
+  | "ALL";
+
+export type AgentPluginRouteHandler = {
+  bivarianceHack(request: Request): Promise<Response> | Response;
+}["bivarianceHack"];
+
+export interface AgentPluginRoute {
+  handler: AgentPluginRouteHandler;
+  method?: AgentPluginRouteMethod | AgentPluginRouteMethod[];
+  path: string;
+}
+
+export interface RouteRegistrationHookContext extends AgentPluginContext {}
+
+export interface SlackConversationLink {
+  url: string;
+}
+
+export interface SlackConversationLinkHookContext extends AgentPluginContext {
+  conversationId: string;
+}
+
 export interface AgentPluginHooks {
   sandboxPrepare?(ctx: SandboxPrepareHookContext): Promise<void> | void;
   beforeToolExecute?(ctx: BeforeToolExecuteHookContext): Promise<void> | void;
+  routes?(ctx: RouteRegistrationHookContext): AgentPluginRoute[];
   tools?(
     ctx: ToolRegistrationHookContext,
   ): Record<string, AgentPluginToolDefinition>;
   heartbeat?(
     ctx: HeartbeatHookContext,
   ): Promise<HeartbeatResult | void> | HeartbeatResult | void;
+  slackConversationLink?(
+    ctx: SlackConversationLinkHookContext,
+  ): SlackConversationLink | undefined;
 }
 
-export interface JuniorPluginConfig {
-  legacyStatePrefixes?: string[];
-  packages?: string[];
+export interface JuniorPluginOAuthConfig {
+  authorizeEndpoint: string;
+  authorizeParams?: Record<string, string>;
+  clientIdEnv: string;
+  clientSecretEnv: string;
+  scope?: string;
+  tokenAuthMethod?: "body" | "basic";
+  tokenEndpoint: string;
+  tokenExtraHeaders?: Record<string, string>;
+}
+
+export interface JuniorPluginOAuthBearerCredentials {
+  apiHeaders?: Record<string, string>;
+  authTokenEnv: string;
+  authTokenPlaceholder?: string;
+  domains: string[];
+  type: "oauth-bearer";
+}
+
+export interface JuniorPluginGitHubAppCredentials {
+  apiHeaders?: Record<string, string>;
+  appIdEnv: string;
+  authTokenEnv: string;
+  authTokenPlaceholder?: string;
+  domains: string[];
+  installationIdEnv: string;
+  privateKeyEnv: string;
+  type: "github-app";
+}
+
+export type JuniorPluginCredentials =
+  | JuniorPluginOAuthBearerCredentials
+  | JuniorPluginGitHubAppCredentials;
+
+export interface JuniorPluginNpmRuntimeDependency {
+  package: string;
+  type: "npm";
+  version: string;
+}
+
+export interface JuniorPluginSystemRuntimeDependency {
+  package: string;
+  type: "system";
+}
+
+export interface JuniorPluginSystemRuntimeDependencyFromUrl {
+  sha256: string;
+  type: "system";
+  url: string;
 }
 
-export interface JuniorPlugin {
+export type JuniorPluginRuntimeDependency =
+  | JuniorPluginNpmRuntimeDependency
+  | JuniorPluginSystemRuntimeDependency
+  | JuniorPluginSystemRuntimeDependencyFromUrl;
+
+export interface JuniorPluginRuntimePostinstallCommand {
+  args?: string[];
+  cmd: string;
+  sudo?: boolean;
+}
+
+export interface JuniorPluginMcpConfig {
+  allowedTools?: string[];
+  headers?: Record<string, string>;
+  transport: "http";
+  url: string;
+}
+
+export interface JuniorPluginEnvVarDeclaration {
+  default?: string;
+}
+
+export interface JuniorPluginManifest {
+  apiHeaders?: Record<string, string>;
+  capabilities?: string[];
+  commandEnv?: Record<string, string>;
+  configKeys?: string[];
+  credentials?: JuniorPluginCredentials;
+  description: string;
+  domains?: string[];
+  envVars?: Record<string, JuniorPluginEnvVarDeclaration>;
+  mcp?: JuniorPluginMcpConfig;
+  name: string;
+  oauth?: JuniorPluginOAuthConfig;
+  runtimeDependencies?: JuniorPluginRuntimeDependency[];
+  runtimePostinstall?: JuniorPluginRuntimePostinstallCommand[];
+  target?: {
+    commandFlags?: string[];
+    configKey: string;
+    type: string;
+  };
+}
+
+export type JuniorPluginRegistrationInput = {
   hooks?: AgentPluginHooks;
+  legacyStatePrefixes?: string[];
+  manifest: JuniorPluginManifest;
+  name?: string;
+  packageName?: string;
+};
+
+export interface JuniorPluginRegistration extends JuniorPluginRegistrationInput {
   name: string;
-  pluginConfig?: JuniorPluginConfig;
 }
 
-/** Define a trusted Junior plugin with optional package config and agent hooks. */
-export function defineJuniorPlugin(plugin: JuniorPlugin): JuniorPlugin {
-  return plugin;
+const PLUGIN_NAME_RE = /^[a-z][a-z0-9-]*$/;
+
+/** Define one Junior plugin registration for app and build-time wiring. */
+export function defineJuniorPlugin(
+  plugin: JuniorPluginRegistrationInput,
+): JuniorPluginRegistration {
+  if ("pluginConfig" in plugin) {
+    throw new Error(
+      "pluginConfig is no longer supported. Put runtime metadata in manifest and trusted state prefixes on the plugin registration.",
+    );
+  }
+  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 = plugin.name ?? manifest.name;
+  if (!name) {
+    throw new Error(
+      "Junior plugin registrations must include name or manifest.name.",
+    );
+  }
+  if (!PLUGIN_NAME_RE.test(name)) {
+    throw new Error(
+      `Junior plugin registration name "${name}" must be a lowercase plugin identifier.`,
+    );
+  }
+  if (
+    typeof manifest.description !== "string" ||
+    !manifest.description.trim()
+  ) {
+    throw new Error(
+      `Junior plugin "${name}" manifest.description is required.`,
+    );
+  }
+  if (plugin.name && manifest.name && plugin.name !== manifest.name) {
+    throw new Error(
+      `Junior plugin registration name "${plugin.name}" must match manifest.name "${manifest.name}".`,
+    );
+  }
+  return {
+    ...plugin,
+    name,
+  };
 }