@sentry/junior-plugin-api 0.198.0 → 0.199.0

package/src/hooks.ts

@@ -1,118 +0,0 @@
-import type {
-  ConversationSidebarHookContext,
-  ConversationSidebarResult,
-} from "./annotations";
-import type {
-  EgressHookContext,
-  EgressResponseHookContext,
-  IssueCredentialHookContext,
-  PluginCredentialResult,
-  PluginGrant,
-  PluginProviderAccount,
-  ResolveOAuthAccountHookContext,
-} from "./credentials";
-import type {
-  HeartbeatHookContext,
-  HeartbeatResult,
-  OperationalReportHookContext,
-  ProfileReportHookContext,
-  ApiRouteRegistrationHookContext,
-  PluginOperationalReportContent,
-  PluginRoute,
-  PluginRouteApp,
-  RouteRegistrationHookContext,
-  SlackConversationLink,
-  SlackConversationLinkHookContext,
-  UnfinishedWorkHookContext,
-  UnfinishedWorkResult,
-} from "./operations";
-import type {
-  AfterMcpToolHookContext,
-  BeforeToolExecuteHookContext,
-  PluginToolDefinition,
-  SandboxPrepareHookContext,
-  ToolRegistrationHookContext,
-  WorkspacePrepareHookContext,
-} from "./tools";
-import type {
-  PromptMessage,
-  SystemPromptContext,
-  UserPromptContext,
-  UserPromptContribution,
-} from "./prompt";
-
-/** Input for a pure Markdown rewrite before destination delivery formatting. */
-export interface FormatMarkdownHookContext {
-  text: string;
-}
-
-export interface PluginHooks {
-  conversationSidebar?(
-    ctx: ConversationSidebarHookContext,
-  ): Promise<ConversationSidebarResult> | ConversationSidebarResult;
-  systemPrompt?(
-    ctx: SystemPromptContext,
-  ): Promise<PromptMessage[]> | PromptMessage[];
-  userPrompt?(
-    ctx: UserPromptContext,
-  ):
-    | Promise<UserPromptContribution[] | undefined>
-    | UserPromptContribution[]
-    | undefined;
-  beforeToolExecute?(ctx: BeforeToolExecuteHookContext): Promise<void> | void;
-  /**
-   * Run after a successful hosted MCP tool call.
-   *
-   * Prefer this for junior-owned side effects such as conversation annotations.
-   * Do not use it to invent a parallel tool contract for the provider tool.
-   */
-  afterMcpTool?(ctx: AfterMcpToolHookContext): Promise<void> | void;
-  grantForEgress?(
-    ctx: EgressHookContext,
-  ): Promise<PluginGrant | undefined> | PluginGrant | undefined;
-  heartbeat?(
-    ctx: HeartbeatHookContext,
-  ): Promise<HeartbeatResult | void> | HeartbeatResult | void;
-  unfinishedWork?(
-    ctx: UnfinishedWorkHookContext,
-  ): Promise<UnfinishedWorkResult> | UnfinishedWorkResult;
-  issueCredential?(
-    ctx: IssueCredentialHookContext,
-  ): Promise<PluginCredentialResult> | PluginCredentialResult;
-  onEgressResponse?(ctx: EgressResponseHookContext): Promise<void> | void;
-  operationalReport?(
-    ctx: OperationalReportHookContext,
-  ):
-    | Promise<PluginOperationalReportContent | undefined>
-    | PluginOperationalReportContent
-    | undefined;
-  /**
-   * Return one person-scoped operational report for a profile page.
-   * Omit or return undefined when the plugin has nothing to show for the subject.
-   */
-  profileReport?(
-    ctx: ProfileReportHookContext,
-  ):
-    | Promise<PluginOperationalReportContent | undefined>
-    | PluginOperationalReportContent
-    | undefined;
-  /** Return plugin-owned product API routes mounted under Junior's authenticated plugin namespace. */
-  apiRoutes?(ctx: ApiRouteRegistrationHookContext): PluginRouteApp | undefined;
-  resolveOAuthAccount?(
-    ctx: ResolveOAuthAccountHookContext,
-  ):
-    | Promise<PluginProviderAccount | undefined>
-    | PluginProviderAccount
-    | undefined;
-  routes?(ctx: RouteRegistrationHookContext): PluginRoute[];
-  sandboxPrepare?(ctx: SandboxPrepareHookContext): Promise<void> | void;
-  workspacePrepare?(ctx: WorkspacePrepareHookContext): Promise<void> | void;
-  slackConversationLink?(
-    ctx: SlackConversationLinkHookContext,
-  ): SlackConversationLink | undefined;
-  /** Pure Markdown rewrite. Emit ordinary Markdown only. */
-  formatMarkdown?(ctx: FormatMarkdownHookContext): string;
-  tools?(
-    ctx: ToolRegistrationHookContext,
-  ): Record<string, PluginToolDefinition>;
-}

package/src/index.ts

@@ -1,29 +0,0 @@
-export * from "./annotations";
-export * from "./code";
-export * from "./conversation-events";
-export * from "./schemas";
-export * from "./context";
-export * from "./state";
-export {
-  definePromptContext,
-  promptContextSchema,
-  promptMessageSchema,
-  type PromptContext,
-  type PromptContextContribution,
-  type PromptMessage,
-  type SystemPromptContext,
-  type UserPromptContribution,
-  type UserPromptContext,
-} from "./prompt";
-export * from "./dispatch";
-export * from "./resource-events";
-export * from "./tasks";
-export * from "./tools";
-export * from "./operations";
-export * from "./credentials";
-export * from "./egress-policy";
-export * from "./hooks";
-export * from "./cli";
-export * from "./manifest";
-export * from "./registration";
-export * from "./user-pages";

package/src/manifest.ts

@@ -1,89 +0,0 @@
-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 {
-  /** Provider tools exposed directly to the model. */
-  allowedTools?: string[];
-  headers?: Record<string, string>;
-  transport: "http";
-  url: string;
-  /** Provider tools hidden from the model and callable only by plugin-owned wrapper tools. */
-  wrappedTools?: string[];
-}
-
-export interface PluginEnvVarDeclaration {
-  default?: string;
-  exposeToCommandEnv?: boolean;
-}
-
-export interface PluginManifest {
-  apiHeaders?: Record<string, 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

@@ -1,199 +0,0 @@
-import { z } from "zod";
-import type { PluginContext, User } from "./context";
-import type { Dispatch, DispatchOptions, DispatchResult } from "./dispatch";
-import { nonBlankStringSchema } from "./schemas";
-import type { PluginReadState, PluginState } from "./state";
-import type { ResourceEventPublisher } from "./resource-events";
-import type { PluginConversationAnnotations } from "./annotations";
-import type { PluginConversationEventStats } from "./conversation-events";
-import type { CodeChangePublisher } from "./code";
-
-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 UnfinishedWorkHookContext extends PluginContext {
-  /** Bounded conversation candidates selected by the host. */
-  conversationIds: string[];
-}
-
-export interface UnfinishedWorkResult {
-  /** Candidate conversations that have plugin-owned work to finish. */
-  conversationIds: string[];
-  /**
-   * Candidate conversations that have any associated plugin-owned work,
-   * finished or unfinished. Omit when the plugin cannot distinguish assignment.
-   *
-   * The host uses this with unfinished work and finish times to set feed
-   * `isPriority`. Finished assigned work stays out of Priority unless the
-   * conversation has activity after the finish time.
-   */
-  assignedConversationIds?: string[];
-  /**
-   * Latest time when all known work finished, keyed by conversation id.
-   * ISO-8601 timestamps. Used with conversation activity to decide whether
-   * finished work still belongs in Priority.
-   */
-  finishedWorkAtByConversationId?: Record<string, string>;
-}
-
-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 PluginOperationalChartSeries {
-  format?: "usd";
-  key: string;
-  label: string;
-  tone?: PluginOperationalTone;
-}
-
-export interface PluginOperationalChartCategory {
-  id: string;
-  label: string;
-  values: Record<string, number>;
-}
-
-export interface PluginOperationalBarChartWidget {
-  categories: PluginOperationalChartCategory[];
-  description?: string;
-  emptyText?: string;
-  id: string;
-  series: PluginOperationalChartSeries[];
-  timeRangeDays?: Array<1 | 7 | 30 | 90>;
-  title: string;
-  type: "bar_chart";
-}
-
-export interface PluginOperationalReportContent {
-  generatedAt?: string;
-  metrics?: PluginOperationalMetric[];
-  recordSets?: PluginOperationalRecordSet[];
-  title?: string;
-  widgets?: PluginOperationalBarChartWidget[];
-}
-
-export interface PluginOperationalReport extends PluginOperationalReportContent {
-  pluginName: string;
-}
-
-export interface OperationalReportHookContext extends PluginContext {
-  eventStats: PluginConversationEventStats;
-  nowMs: number;
-  state: PluginReadState;
-}
-
-/** Read-only context for one person-scoped plugin report on a profile page. */
-export interface ProfileReportHookContext extends PluginContext {
-  nowMs: number;
-  state: PluginReadState;
-  /** Canonical user for the profile being viewed. */
-  subject: User;
-  /** Canonical user for the authenticated viewer. */
-  viewer: User;
-}
-
-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;
-}
-
-/** Fetch-compatible plugin HTTP app mounted by Junior. */
-export type PluginRouteApp = {
-  fetch(
-    request: Request,
-    context?: PluginApiRouteRequestContext,
-  ): Promise<Response> | Response;
-};
-
-export interface RouteRegistrationHookContext extends PluginContext {
-  annotations: PluginConversationAnnotations;
-  /** Provider-neutral write boundary for Junior's native code index. */
-  codeChanges: CodeChangePublisher;
-  /** Core-owned delivery boundary for provider webhook events. */
-  resourceEvents: ResourceEventPublisher;
-}
-
-export interface ApiRouteRegistrationHookContext extends PluginContext {
-  eventStats: PluginConversationEventStats;
-  users: {
-    /** Resolve or create the canonical user for one verified email. */
-    resolve(email: string): Promise<User | undefined>;
-  };
-}
-
-/** Per-request context Junior passes to authenticated plugin product API routes. */
-export const pluginApiRouteRequestContextSchema = z
-  .object({
-    auth: z
-      .object({
-        user: z
-          .object({
-            email: z.string().nullable().optional(),
-            emailVerified: z.boolean().optional(),
-            name: z.string().nullable().optional(),
-          })
-          .strict(),
-      })
-      .strict(),
-    pluginName: nonBlankStringSchema,
-  })
-  .strict();
-
-export type PluginApiRouteRequestContext = z.output<
-  typeof pluginApiRouteRequestContextSchema
->;
-
-export interface SlackConversationLink {
-  url: string;
-}
-
-export interface SlackConversationLinkHookContext extends PluginContext {
-  conversationId: string;
-}

package/src/prompt.ts

@@ -1,99 +0,0 @@
-import { z } from "zod";
-import type {
-  Destination,
-  Platform,
-  PluginContext,
-  PluginEmbedder,
-  PluginModel,
-  Actor,
-  Identity,
-  Source,
-  User,
-} from "./context";
-import type { PluginState } from "./state";
-import type { PluginConversationEvents } from "./conversation-events";
-
-const promptContextKindSchema = z
-  .string()
-  .trim()
-  .min(1)
-  .max(64)
-  .regex(/^[a-z][a-z0-9_-]*$/);
-
-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>;
-
-export const promptContextSchema = z
-  .object({
-    kind: promptContextKindSchema,
-    version: z.number().int().positive(),
-    content: z.record(z.string(), z.unknown()),
-  })
-  .strict();
-
-/** Structured plugin context retained alongside its model-visible rendering. */
-export type PromptContext = z.output<typeof promptContextSchema>;
-
-/** Runtime contribution produced from one validated plugin context value. */
-export interface PromptContextContribution {
-  context: PromptContext;
-  renderPrompt(): string;
-}
-
-/** Define one typed, versioned plugin context contribution. */
-export function definePromptContext<
-  TSchema extends z.ZodType<Record<string, unknown>>,
->(definition: {
-  kind: string;
-  version: number;
-  schema: TSchema;
-  renderPrompt(content: z.output<TSchema>): string;
-}): (content: z.input<TSchema>) => PromptContextContribution {
-  const identity = promptContextSchema
-    .pick({ kind: true, version: true })
-    .parse({ kind: definition.kind, version: definition.version });
-  return (content) => {
-    const parsed = definition.schema.parse(content);
-    return {
-      context: { ...identity, content: parsed },
-      renderPrompt: () => definition.renderPrompt(parsed),
-    };
-  };
-}
-
-/** One request-scoped plugin contribution to the model-visible user prompt. */
-export type UserPromptContribution = PromptMessage | PromptContextContribution;
-
-/** 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;
-  /** Conversation-bound event writer when the prompt belongs to a durable turn. */
-  events?: PluginConversationEvents;
-  model: PluginModel;
-  /** Location associated with this Conversation. */
-  locationId?: string;
-  actor?: Actor;
-  source: Source;
-  state: PluginState;
-  text: string;
-  users: {
-    /** Resolve the current Actor's Identity and User. */
-    resolveActor(): Promise<{ identity: Identity; user?: User } | undefined>;
-  };
-};

package/src/registration.ts

@@ -1,173 +0,0 @@
-import type { PluginCliDefinition } from "./cli";
-import type { PluginConversationEventDefinition } from "./conversation-events";
-import type { PluginHooks } from "./hooks";
-import type { PluginManifest } from "./manifest";
-import type { PluginTasks } from "./tasks";
-import type { PluginUserPageDefinition } from "./user-pages";
-import {
-  pluginResourceEventsSchema,
-  type PluginResourceEvents,
-} from "./resource-events";
-
-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;
-  conversationEvents?: PluginConversationEventDefinition[];
-  hooks?: PluginHooks;
-  manifest: PluginManifest;
-  model?: PluginModelConfig;
-  packageName?: string;
-  resourceEvents?: PluginResourceEvents;
-  tasks?: PluginTasks;
-  userPages?: PluginUserPageDefinition[];
-};
-
-export interface PluginRegistration extends PluginRegistrationInput {}
-
-const PLUGIN_NAME_RE = /^[a-z][a-z0-9-]*$/;
-const USER_PAGE_ID_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 (name === "junior") {
-    throw new Error(
-      'Junior plugin registration name "junior" is reserved for native host events.',
-    );
-  }
-  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.`,
-    );
-  }
-  if (plugin.userPages !== undefined && !Array.isArray(plugin.userPages)) {
-    throw new Error(`Junior plugin "${name}" userPages must be an array.`);
-  }
-  if (
-    plugin.conversationEvents !== undefined &&
-    !Array.isArray(plugin.conversationEvents)
-  ) {
-    throw new Error(
-      `Junior plugin "${name}" conversationEvents must be an array.`,
-    );
-  }
-  if (plugin.resourceEvents !== undefined) {
-    const parsed = pluginResourceEventsSchema.safeParse(plugin.resourceEvents);
-    if (!parsed.success) {
-      throw new Error(`Junior plugin "${name}" resourceEvents is invalid.`, {
-        cause: parsed.error,
-      });
-    }
-  }
-  const conversationEventIds = new Set<string>();
-  for (const event of plugin.conversationEvents ?? []) {
-    if (
-      !event ||
-      (typeof event !== "object" && typeof event !== "function") ||
-      typeof event.parse !== "function" ||
-      typeof event.renderEvent !== "function"
-    ) {
-      throw new Error(
-        `Junior plugin "${name}" conversation event definitions must be created with defineConversationEvent().`,
-      );
-    }
-    const id = `${event.eventName}@${event.version}`;
-    if (conversationEventIds.has(id)) {
-      throw new Error(
-        `Junior plugin "${name}" has duplicate conversation event "${id}".`,
-      );
-    }
-    conversationEventIds.add(id);
-  }
-  const userPageIds = new Set<string>();
-  for (const page of plugin.userPages ?? []) {
-    if (!page || typeof page !== "object") {
-      throw new Error(`Junior plugin "${name}" user pages must be objects.`);
-    }
-    if (
-      typeof page.id !== "string" ||
-      page.id.length > 64 ||
-      !USER_PAGE_ID_RE.test(page.id)
-    ) {
-      throw new Error(
-        `Junior plugin "${name}" user page id "${page.id}" must be a lowercase identifier.`,
-      );
-    }
-    if (userPageIds.has(page.id)) {
-      throw new Error(
-        `Junior plugin "${name}" has duplicate user page id "${page.id}".`,
-      );
-    }
-    if (
-      typeof page.label !== "string" ||
-      !page.label.trim() ||
-      page.label.length > 80 ||
-      typeof page.description !== "string" ||
-      !page.description.trim() ||
-      page.description.length > 500
-    ) {
-      throw new Error(
-        `Junior plugin "${name}" user page "${page.id}" requires label and description.`,
-      );
-    }
-    if (
-      page.navigation !== undefined &&
-      page.navigation !== "primary" &&
-      page.navigation !== "profile"
-    ) {
-      throw new Error(
-        `Junior plugin "${name}" user page "${page.id}" navigation must be "primary" or "profile".`,
-      );
-    }
-    if (typeof page.read !== "function") {
-      throw new Error(
-        `Junior plugin "${name}" user page "${page.id}" requires a read function.`,
-      );
-    }
-    userPageIds.add(page.id);
-  }
-  return {
-    ...plugin,
-  };
-}