@sentry/junior-plugin-api 0.267.0 → 0.269.0

package/README.md

@@ -1,185 +1,11 @@
 # @sentry/junior-plugin-api
 
-This package defines the public contract between Junior and code plugins. The
-exported TypeScript types and runtime validators are authoritative.
+Types and helpers for Junior code plugins. Use `defineJuniorPlugin()` to
+declare a manifest, hooks, tasks, CLI commands, user pages, and conversation
+events.
 
-## Registration
+```bash
+pnpm add @sentry/junior-plugin-api
+```
 
-Use
-`defineJuniorPlugin({ manifest, hooks, tasks, cli, model, conversationEvents })`.
-A plugin name is a lowercase identifier and is unique within the enabled app
-plugin set.
-
-Packages with JavaScript registration export one callable factory named
-`<domain>Plugin`, such as `githubPlugin(options?)`. Do not use a public
-`create<Domain>Plugin` alias or export a prebuilt registration. Call the factory
-even when it accepts no options.
-
-A plugin may instead be a declarative `plugin.yaml` package when it has no
-host-executed hooks. Do not combine an inline manifest with a second YAML
-definition for the same plugin.
-
-## Manifest
-
-The manifest declares runtime metadata such as:
-
-- plugin identity and description;
-- skill roots and MCP tool sources;
-- provider domains, grants, OAuth, API-header transformations, and safe command
-  environment placeholders;
-- runtime dependencies and snapshot installation steps;
-- configuration fields;
-- signed-in user pages backed by core-owned discovery and read routes.
-
-Manifest values are validated before runtime activation. Secret deployment
-values remain host-only; sandbox-exposed command environment must be explicitly
-safe.
-
-## Hooks
-
-Plugins may contribute tools, prompt messages, lifecycle work, operational
-reports, and other typed hook surfaces exported by this package.
-
-- Hook context carries the active source, actor, conversation, plugin metadata,
-  database, logging, and only the host capabilities required by that hook.
-- Source uses `kind` to state what produced the input. Events,
-  scheduled automations, event automations, Plugin dispatches, and Agent invocations do not
-  name a provider. Actor and Destination still use `platform` to name one.
-- Prompt hooks return bounded structured prompt messages rather than mutate the
-  core prompt.
-- `formatMarkdown` is a pure text rewrite into ordinary Markdown before delivery.
-- `conversationTitleContext` returns short facts about objects that the first
-  human message refers to, such as an issue number and title. The hook gets the
-  plugin's config values, such as a default repository. It must read provider
-  data through `ctx.egress`, which uses Junior's system identity and never
-  starts authorization. Only the title model sees the facts. Junior bounds the
-  wait and ignores a failed hook.
-- User prompt hooks for durable turns may emit registered structured events
-  through `ctx.events` for auxiliary work completed while building context.
-- Tool hooks return model-visible schemas aligned with their executor inputs.
-- Tool registration hooks may use `ctx.sandbox` for plugin-owned workspace
-  files and commands; Junior still owns sandbox lifecycle, cancellation,
-  provider egress, and authorization recovery.
-- Host-owned structured model and embedding calls do not expose provider
-  credentials to plugins. Both return a best-effort provider cost estimate when
-  one is available.
-- Operational report and authenticated API hooks may aggregate `costUsd` from
-  their own registered conversation events through `ctx.eventStats`. Core
-  binds the plugin namespace and owns access to the conversation event log.
-  Event `costUsd` is additive operation cost and must not duplicate cost
-  already recorded in the conversation's agent model usage.
-- Profile report hooks return the same bounded operational report content for
-  one subject user on a person profile. Core owns viewer authorization,
-  collection, sanitization, and browser rendering.
-- Tool hooks may resolve the active Actor's Identity and User through
-  `ctx.users.resolveActor()`, and the Actor's timezone through
-  `ctx.users.resolveTimezone()`.
-- Authenticated API route hooks receive `ctx.users.resolve(email)` for lazy
-  User lookup. Routes that do not need User data do not query identity storage.
-- User page readers receive the signed-in `User`. Plugins return limited data.
-  They do not mount their own page routes or browser code.
-
-## User Pages
-
-Register signed-in pages through `userPages` beside `hooks`, `tasks`, and `cli`.
-Each definition owns its navigation metadata and `read(ctx, input)` function,
-so a page cannot be advertised without an implementation. List readers receive
-validated search and cursor input and may return an opaque continuation cursor.
-Set `navigation: "primary"` for a top-level dashboard navigation item. The
-default `profile` placement keeps account-oriented pages in the signed-in user
-menu. Junior always renders core System navigation after plugin pages.
-Set `navigation: "admin"` for setup that only Junior admins may use. Core lists
-these pages on the dashboard Admin page and serves them only to admins. Core
-reads the admin role from the user record on every request.
-Records may expose bounded `DELETE` actions inside their own authenticated
-plugin API namespace. Records may also expose `GET` actions. The dashboard opens
-them as normal browser links, for example to start an OAuth sign-in. Core owns
-discovery, authentication, user resolution, routing, response validation,
-rendering, confirmation, and query state.
-
-Authenticated plugin API routes receive `context.auth.user.isAdmin`. Core sets
-it from the stored user on every request. Admin-only routes must check it on
-the server, because a hidden link does not protect a route.
-
-## Durable Work
-
-- Heartbeat hooks perform bounded periodic maintenance and must be safe to run
-  repeatedly.
-- Background tasks are registered by name, receive validated parameters, and
-  execute through the host queue/callback lifecycle.
-- Conversation-bound background tasks may emit registered structured events
-  through `ctx.events`. Define each version with `defineConversationEvent()`;
-  the host supplies the plugin namespace, conversation, turn, ordering, and
-  timestamps without treating background work as new conversation activity.
-  Event definitions return bounded transcript presentation data, while Junior
-  owns browser rendering.
-- `ctx.agent.dispatch` creates durable agent work with an explicit actor,
-  destination, source, metadata, and idempotency identity.
-- Dispatches may include compact `replyAttribution` for destination-visible
-  context about what produced the reply. Core owns platform rendering; opaque
-  dispatch metadata remains internal.
-- Delegated credential subjects declare the narrow action that authorized them.
-  Core owns runtime bindings; scheduler task subjects are accepted only from the
-  scheduler plugin and are bound to the exact task id.
-- Completed dispatch and task projections are durable plugin inputs, not an
-  invitation to inspect unrestricted conversation state.
-
-## Conversation Events
-
-Register plugin-owned event definitions through `conversationEvents`. A
-definition owns one local name, version, content schema, and `renderEvent()`
-projection. A renderer may return `undefined` when an event should remain
-durable without producing a transcript row. The active plugin context supplies
-the namespace, so plugins cannot emit native events or impersonate another
-plugin. The `junior` plugin name is reserved for host-owned native events.
-Versions of the same event name share one operation idempotency identity,
-so keep previous definitions registered when evolving an event. Stored events
-remain durable when a plugin is removed, but normal transcript projection skips
-definitions that are not currently registered.
-
-## Database
-
-- Packaged migrations create plugin-owned tables through the host migration
-  runner.
-- Generate migration artifacts from the package schema; do not hand-maintain a
-  second schema contract.
-- Runtime hooks and CLI actions use host-provided `ctx.db`.
-- Migrations are expand-first, deterministic, ordered by plugin name, and safe
-  to retry. A failure blocks upgrade rather than partially enabling the plugin.
-- Cross-plugin or core-table access is a review boundary for trusted app code;
-  introduce a facade only when a concrete security or lifecycle boundary
-  requires it.
-
-## CLI
-
-Code plugins may register one namespaced host CLI command with one or more
-subcommands. Core command names win. Actions use the host action wrapper and
-receive plugin metadata, configuration, database, safe output writers, and
-logging—not model, Slack, sandbox, or provider credential context.
-
-## Security
-
-Plugins and skills follow `../../policies/security.md`,
-`../../policies/data-redaction.md`, and
-`../../policies/provider-boundaries.md`. Skills explain capability use; they do
-not bootstrap runtimes or credentials.
-
-## Object annotations
-
-A tool can return `objectAnnotations` through `pluginToolOutputSchema` to save
-object facts and attach a card to the next visible reply. The host assigns the
-plugin owner. Use a stable `key` within the plugin, a compact `label`, a `title`,
-a verified HTTP(S) `url` (or null), and an `objectType`: `task`, `code_change`,
-`automation`, or `item`. Status and description are optional. Automations also
-use `trigger` and `warning`. Do not send Slack layout JSON or infer facts that
-the provider did not return.
-
-Show at most four fact attributes plus status. Hide code-change size counts
-and source update times without removing them from saved annotations.
-
-The `afterMcpTool` hook can return `{ objectAnnotations }` after a successful
-hosted tool call. Use `ctx.annotations.upsert` instead when facts must change
-without selecting a reply card, such as a background webhook update. Only return
-facts that can be shared with the current Conversation. Message cards reference
-the latest saved annotation. Tool results remain immutable for agent history.
-Neither cards nor annotations grant access to the provider.
+Build a plugin: https://junior.sentry.dev/extend/build-a-plugin/

package/dist/index.d.ts

@@ -9,7 +9,7 @@ import { Command } from "commander";
  * selects the fields it needs; preview rules must not remove saved facts.
  *
  * Keep raw responses, diffs, logs, credentials, and comments out of this schema.
- * See "Object facts" in packages/junior/src/chat/conversations/README.md.
+ * See "Object annotations and Message cards" in packages/junior/src/chat/conversations/AGENTS.md.
  */
 export declare const objectAnnotationSchema: z.ZodObject<{
   kind: z.ZodLiteral<"object">;
@@ -1869,6 +1869,44 @@ export interface IssueCredentialHookContext extends PluginContext {
   grant: PluginGrant;
   tokens: PluginTokenStore;
 }
+/** A notice that a plugin puts on the review desk. */
+export interface PluginReviewNotice {
+  /** Junior assigns the User linked to each Identity. */
+  assigneeIdentityIds: string[];
+  /** Markdown details for the person. */
+  body: string;
+  /**
+   * Stable key for what the notice is about. A plugin has at most one open
+   * item for each key.
+   */
+  dedupeKey: string;
+  /** What the notice is about, such as a pull request. Search matches `id`. */
+  subject?: {
+    id: string;
+    title?: string;
+    url?: string;
+  };
+  title: string;
+}
+/**
+ * Review items that a plugin adds and closes from its own events. Each item
+ * belongs to one Conversation. Core owns visibility, assignment rules, and
+ * the Slack cards.
+ */
+export interface PluginReviewItems {
+  /** Add an open notice, or replace the content of the open one with the key. */
+  upsert(notice: PluginReviewNotice): Promise<void>;
+  /** Close the open item with the key. Do nothing when no item is open. */
+  close(input: {
+    dedupeKey: string;
+    reason: string;
+    status: "done" | "dismissed";
+  }): Promise<void>;
+}
+/** Review items of a plugin, for the Conversation that each item belongs to. */
+export interface PluginConversationReviewItems {
+  forConversation(conversationId: string): PluginReviewItems;
+}
 export interface HeartbeatHookContext extends PluginContext {
   agent: {
     dispatch(options: DispatchOptions): Promise<DispatchResult>;
@@ -1988,6 +2026,8 @@ export interface RouteRegistrationHookContext extends PluginContext {
   codeChanges: CodeChangePublisher;
   /** Core-owned delivery boundary for provider webhook events. */
   events: EventPublisher;
+  /** Review desk items that the plugin adds and closes from its events. */
+  reviewItems: PluginConversationReviewItems;
   users: {
     /**
      * Read one stored identity and the user it links to now, with every
@@ -2534,6 +2574,11 @@ export interface PluginHooks {
    * that changes per request in `userPrompt`. See `policies/system-prompt.md`.
    */
   systemPrompt?(ctx: SystemPromptContext): Promise<PromptMessage[]> | PromptMessage[];
+  /**
+   * Return per-request context for a new prompt, such as recalled memories.
+   * Junior runs this hook at the same time as Turn routing and sandbox setup,
+   * so it must not depend on either.
+   */
   userPrompt?(ctx: UserPromptContext): Promise<UserPromptContribution[] | undefined> | UserPromptContribution[] | undefined;
   beforeToolExecute?(ctx: BeforeToolExecuteHookContext): Promise<void> | void;
   /**

package/dist/index.js

@@ -157,7 +157,7 @@ function objectIconPath(icon) {
 * selects the fields it needs; preview rules must not remove saved facts.
 *
 * Keep raw responses, diffs, logs, credentials, and comments out of this schema.
-* See "Object facts" in packages/junior/src/chat/conversations/README.md.
+* See "Object annotations and Message cards" in packages/junior/src/chat/conversations/AGENTS.md.
 */
 const objectAnnotationSchema = z.object({
 	kind: z.literal("object"),

package/package.json

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