@sentry/junior-plugin-api 0.74.1 → 0.76.0

package/dist/index.js

@@ -1,4 +1,4 @@
-// src/index.ts
+// src/schemas.ts
 import { z } from "zod";
 var slackTeamIdSchema = z.string().regex(/^T[A-Z0-9]+$/);
 var slackConversationIdSchema = z.string().regex(/^(C|G|D)[A-Z0-9]+$/);
@@ -7,11 +7,14 @@ var exactActorUserIdSchema = z.string().min(1).refine(
   (value) => value === value.trim() && value.toLowerCase() !== "unknown"
 );
 var nonBlankStringSchema = z.string().refine((value) => value.trim().length > 0);
-var slackDestinationSchema = z.object({
+var platformSchema = z.enum(["slack", "local"]);
+var sourceTypeSchema = z.enum(["pub", "priv"]);
+var slackAddressSchema = z.object({
   platform: z.literal("slack"),
   teamId: slackTeamIdSchema,
   channelId: slackConversationIdSchema
 }).strict();
+var slackDestinationSchema = slackAddressSchema;
 var localDestinationSchema = z.object({
   platform: z.literal("local"),
   conversationId: localConversationIdSchema
@@ -20,19 +23,21 @@ var destinationSchema = z.discriminatedUnion("platform", [
   slackDestinationSchema,
   localDestinationSchema
 ]);
-var slackSourceSchema = z.object({
-  platform: z.literal("slack"),
-  teamId: slackTeamIdSchema,
-  channelId: slackConversationIdSchema,
+var slackSourceSchema = slackAddressSchema.extend({
+  type: sourceTypeSchema,
   messageTs: nonBlankStringSchema.optional(),
   threadTs: nonBlankStringSchema.optional()
 }).strict();
-var localSourceSchema = localDestinationSchema;
+var localSourceSchema = z.object({
+  platform: z.literal("local"),
+  type: z.literal("priv"),
+  conversationId: localConversationIdSchema
+}).strict();
 var sourceSchema = z.discriminatedUnion("platform", [
   slackSourceSchema,
   localSourceSchema
 ]);
-var agentPluginCredentialSubjectSchema = z.object({
+var pluginCredentialSubjectSchema = z.object({
   type: z.literal("user"),
   userId: exactActorUserIdSchema,
   allowedWhen: z.literal("private-direct-conversation")
@@ -81,6 +86,20 @@ var dispatchMetadataSchema = z.record(z.string(), z.string()).superRefine((metad
         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,
@@ -92,65 +111,147 @@ var dispatchMetadataSchema = z.record(z.string(), z.string()).superRefine((metad
 });
 var dispatchOptionsSchema = z.object({
   idempotencyKey: nonBlankStringSchema.pipe(z.string().max(512)),
-  credentialSubject: agentPluginCredentialSubjectSchema.optional(),
+  credentialSubject: pluginCredentialSubjectSchema.optional(),
   destination: slackDestinationSchema,
   input: nonBlankStringSchema.pipe(z.string().max(32e3)),
-  metadata: dispatchMetadataSchema.optional()
+  metadata: dispatchMetadataSchema.optional(),
+  source: sourceSchema
 }).strict();
-var AgentPluginToolInputError = class extends Error {
-  constructor(message, options) {
-    super(message, options);
-    this.name = "AgentPluginToolInputError";
+
+// src/context.ts
+function createSlackSource(input) {
+  return {
+    platform: "slack",
+    type: slackSourceType(input.channelId),
+    teamId: input.teamId,
+    channelId: input.channelId,
+    ...input.messageTs ? { messageTs: input.messageTs } : {},
+    ...input.threadTs ? { threadTs: input.threadTs } : {}
+  };
+}
+function slackSourceType(channelId) {
+  if (channelId.startsWith("C")) return "pub";
+  if (channelId.startsWith("D") || channelId.startsWith("G")) return "priv";
+  throw new Error(`Unsupported Slack channel ID prefix: ${channelId}`);
+}
+function createLocalSource(conversationId) {
+  return {
+    platform: "local",
+    type: "priv",
+    conversationId
+  };
+}
+function isPrivateSource(source) {
+  return source.type === "priv";
+}
+function getSourceKey(source) {
+  if (source.platform === "local") {
+    return source.conversationId;
   }
-};
+  const messageKey = source.threadTs ?? source.messageTs;
+  if (!messageKey) {
+    return void 0;
+  }
+  return `slack:${source.teamId}:${source.channelId}:${messageKey}`;
+}
 function isSlackDestination(destination) {
   return destination?.platform === "slack";
 }
-var agentPluginProviderNameSchema = z.string().regex(/^[a-z][a-z0-9-]*$/);
-var agentPluginGrantNameSchema = z.string().regex(/^[a-z][a-z0-9.-]*$/);
-var agentPluginGrantAccessSchema = z.union([
-  z.literal("read"),
-  z.literal("write")
+
+// src/prompt.ts
+import { z as z2 } from "zod";
+var promptMessageSchema = z2.object({
+  text: z2.string().trim().min(1).max(8e3)
+}).strict();
+
+// src/tasks.ts
+import { z as z3 } from "zod";
+var pluginRunTranscriptEntrySchema = z3.discriminatedUnion("type", [
+  z3.object({
+    type: z3.literal("message"),
+    role: z3.enum(["user", "assistant"]),
+    text: z3.string().min(1)
+  }).strict(),
+  z3.object({
+    type: z3.literal("toolResult"),
+    toolName: z3.string().min(1),
+    isError: z3.boolean(),
+    text: z3.string().min(1).optional()
+  }).strict()
 ]);
-var agentPluginAuthorizationSchema = z.object({
-  provider: agentPluginProviderNameSchema,
+var pluginRunContextSchema = z3.object({
+  completedAtMs: z3.number().finite(),
+  conversationId: z3.string().min(1),
+  destination: destinationSchema,
+  requester: requesterSchema.optional(),
+  runId: z3.string().min(1),
+  source: sourceSchema,
+  transcript: z3.array(pluginRunTranscriptEntrySchema)
+}).strict();
+
+// src/tools.ts
+var PluginToolInputError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "PluginToolInputError";
+  }
+};
+
+// src/credentials.ts
+import { z as z4 } from "zod";
+var pluginProviderNameSchema = z4.string().regex(/^[a-z][a-z0-9-]*$/);
+var pluginGrantNameSchema = z4.string().regex(/^[a-z][a-z0-9.-]*$/);
+var pluginGrantAccessSchema = z4.union([
+  z4.literal("read"),
+  z4.literal("write")
+]);
+var pluginAuthorizationSchema = z4.object({
+  provider: pluginProviderNameSchema,
   scope: nonBlankStringSchema.optional(),
-  type: z.literal("oauth")
+  type: z4.literal("oauth")
 }).strict();
-var agentPluginProviderAccountSchema = z.object({
+var pluginProviderAccountSchema = z4.object({
   id: nonBlankStringSchema,
   label: nonBlankStringSchema.optional(),
   url: nonBlankStringSchema.optional()
 }).strict();
-var agentPluginGrantSchema = z.object({
-  access: agentPluginGrantAccessSchema,
-  name: agentPluginGrantNameSchema,
+var pluginStoredTokensSchema = z4.object({
+  account: pluginProviderAccountSchema.optional(),
+  accessToken: nonBlankStringSchema,
+  expiresAt: z4.number().finite().optional(),
+  refreshToken: nonBlankStringSchema,
+  refreshTokenExpiresAt: z4.number().finite().optional(),
+  scope: nonBlankStringSchema.optional()
+}).strict();
+var pluginGrantSchema = z4.object({
+  access: pluginGrantAccessSchema,
+  name: pluginGrantNameSchema,
   reason: nonBlankStringSchema.optional(),
-  requirements: z.array(nonBlankStringSchema).min(1).optional()
-}).strict();
-var agentPluginCredentialHeaderTransformSchema = z.object({
-  domain: z.string().min(1),
-  headers: z.record(z.string(), z.string()).refine((headers) => Object.keys(headers).length > 0)
-}).strict();
-var agentPluginCredentialLeaseSchema = z.object({
-  account: agentPluginProviderAccountSchema.optional(),
-  authorization: agentPluginAuthorizationSchema.optional(),
-  expiresAt: z.string().refine((value) => Number.isFinite(Date.parse(value))),
-  headerTransforms: z.array(agentPluginCredentialHeaderTransformSchema).min(1)
-}).strict();
-var agentPluginCredentialResultSchema = z.discriminatedUnion("type", [
-  z.object({
-    lease: agentPluginCredentialLeaseSchema,
-    type: z.literal("lease")
+  requirements: z4.array(nonBlankStringSchema).min(1).optional()
+}).strict();
+var pluginCredentialHeaderTransformSchema = z4.object({
+  domain: z4.string().min(1),
+  headers: z4.record(z4.string(), z4.string()).refine((headers) => Object.keys(headers).length > 0)
+}).strict();
+var pluginCredentialLeaseSchema = z4.object({
+  account: pluginProviderAccountSchema.optional(),
+  authorization: pluginAuthorizationSchema.optional(),
+  expiresAt: z4.string().refine((value) => Number.isFinite(Date.parse(value))),
+  headerTransforms: z4.array(pluginCredentialHeaderTransformSchema).min(1)
+}).strict();
+var pluginCredentialResultSchema = z4.discriminatedUnion("type", [
+  z4.object({
+    lease: pluginCredentialLeaseSchema,
+    type: z4.literal("lease")
   }).strict(),
-  z.object({
-    authorization: agentPluginAuthorizationSchema.optional(),
+  z4.object({
+    authorization: pluginAuthorizationSchema.optional(),
     message: nonBlankStringSchema,
-    type: z.literal("needed")
+    type: z4.literal("needed")
   }).strict(),
-  z.object({
+  z4.object({
     message: nonBlankStringSchema,
-    type: z.literal("unavailable")
+    type: z4.literal("unavailable")
   }).strict()
 ]);
 var EgressAuthRequired = class extends Error {
@@ -161,24 +262,27 @@ var EgressAuthRequired = class extends Error {
     this.authorization = options?.authorization;
   }
 };
+
+// src/registration.ts
 var PLUGIN_NAME_RE = /^[a-z][a-z0-9-]*$/;
 function defineJuniorPlugin(plugin) {
   if ("pluginConfig" in plugin) {
     throw new Error(
-      "pluginConfig is no longer supported. Put runtime metadata in manifest and state prefixes on the plugin registration."
+      "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 = plugin.name ?? manifest.name;
+  const name = manifest.name;
   if (!name) {
-    throw new Error(
-      "Junior plugin registrations must include name or manifest.name."
-    );
+    throw new Error("Junior plugin manifest.name is required.");
   }
   if (!PLUGIN_NAME_RE.test(name)) {
     throw new Error(
@@ -195,36 +299,41 @@ function defineJuniorPlugin(plugin) {
       `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
+    ...plugin
   };
 }
 export {
-  AgentPluginToolInputError,
   EgressAuthRequired,
-  agentPluginAuthorizationSchema,
-  agentPluginCredentialHeaderTransformSchema,
-  agentPluginCredentialLeaseSchema,
-  agentPluginCredentialResultSchema,
-  agentPluginCredentialSubjectSchema,
-  agentPluginGrantSchema,
-  agentPluginProviderAccountSchema,
+  PluginToolInputError,
+  createLocalSource,
+  createSlackSource,
   defineJuniorPlugin,
   destinationSchema,
   dispatchOptionsSchema,
+  getSourceKey,
+  isPrivateSource,
   isSlackDestination,
   localDestinationSchema,
   localRequesterSchema,
   localSourceSchema,
+  nonBlankStringSchema,
+  platformSchema,
+  pluginAuthorizationSchema,
+  pluginCredentialHeaderTransformSchema,
+  pluginCredentialLeaseSchema,
+  pluginCredentialResultSchema,
+  pluginCredentialSubjectSchema,
+  pluginGrantSchema,
+  pluginProviderAccountSchema,
+  pluginRunContextSchema,
+  pluginRunTranscriptEntrySchema,
+  pluginStoredTokensSchema,
+  promptMessageSchema,
   requesterSchema,
   slackDestinationSchema,
   slackRequesterSchema,
   slackSourceSchema,
-  sourceSchema
+  sourceSchema,
+  sourceTypeSchema
 };

package/dist/manifest.d.ts

@@ -0,0 +1,74 @@
+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/dist/operations.d.ts

@@ -0,0 +1,91 @@
+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/dist/prompt.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import type { Destination, Platform, PluginContext, PluginEmbedder, Requester, Source } from "./context";
+import type { PluginState } from "./state";
+export declare const promptMessageSchema: z.ZodObject<{
+    text: z.ZodString;
+}, z.core.$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/dist/registration.d.ts

@@ -0,0 +1,22 @@
+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 {
+}
+/** Define one Junior plugin registration for app and build-time wiring. */
+export declare function defineJuniorPlugin(plugin: PluginRegistrationInput): PluginRegistration;