@sentry/junior-plugin-api 0.100.0 → 0.102.0

package/README.md

@@ -0,0 +1,82 @@
+# @sentry/junior-plugin-api
+
+This package defines the public contract between Junior and code plugins. The
+exported TypeScript types and runtime validators are authoritative.
+
+## Registration
+
+Use `defineJuniorPlugin({ manifest, hooks, tasks, cli, model })`. A plugin name
+is a lowercase identifier and is unique within the enabled app plugin set.
+
+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.
+
+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, migrations, 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.
+- Prompt hooks return bounded structured prompt messages rather than mutate the
+  core prompt.
+- Tool hooks return model-visible schemas aligned with their executor inputs.
+- Host-owned structured model and embedding calls do not expose provider
+  credentials to plugins.
+
+## 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.
+- `ctx.agent.dispatch` creates durable agent work with an explicit actor,
+  destination, source, metadata, and idempotency identity.
+- 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.
+
+## 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.

package/dist/index.js

@@ -7,6 +7,9 @@ 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 exactNonBlankStringSchema = nonBlankStringSchema.refine(
+  (value) => value === value.trim()
+);
 var platformSchema = z.enum(["slack", "local"]);
 var sourceTypeSchema = z.enum(["pub", "priv"]);
 var slackAddressSchema = z.object({
@@ -37,11 +40,22 @@ var sourceSchema = z.discriminatedUnion("platform", [
   slackSourceSchema,
   localSourceSchema
 ]);
-var pluginCredentialSubjectSchema = z.object({
-  type: z.literal("user"),
-  userId: exactActorUserIdSchema,
-  allowedWhen: z.literal("private-direct-conversation")
-}).strict();
+var pluginCredentialSubjectSchema = z.discriminatedUnion(
+  "allowedWhen",
+  [
+    z.object({
+      type: z.literal("user"),
+      userId: exactActorUserIdSchema,
+      allowedWhen: z.literal("private-direct-conversation")
+    }).strict(),
+    z.object({
+      type: z.literal("user"),
+      userId: exactActorUserIdSchema,
+      allowedWhen: z.literal("scheduled-task"),
+      taskId: exactNonBlankStringSchema
+    }).strict()
+  ]
+);
 var actorProfileSchema = {
   email: nonBlankStringSchema.optional(),
   fullName: nonBlankStringSchema.optional(),

package/dist/schemas.d.ts

@@ -65,11 +65,16 @@ export declare const sourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     conversationId: z.ZodString;
 }, z.core.$strict>], "platform">;
 /** Stable user credential subject shape accepted from plugins. */
-export declare const pluginCredentialSubjectSchema: z.ZodObject<{
+export declare const pluginCredentialSubjectSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"user">;
     userId: z.ZodString;
     allowedWhen: z.ZodLiteral<"private-direct-conversation">;
-}, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"user">;
+    userId: z.ZodString;
+    allowedWhen: z.ZodLiteral<"scheduled-task">;
+    taskId: z.ZodString;
+}, z.core.$strict>], "allowedWhen">;
 export declare const slackActorSchema: z.ZodObject<{
     platform: z.ZodLiteral<"slack">;
     teamId: z.ZodString;
@@ -110,11 +115,16 @@ export declare const actorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 /** Plugin dispatch request accepted by Junior core. */
 export declare const dispatchOptionsSchema: z.ZodObject<{
     idempotencyKey: z.ZodPipe<z.ZodString, z.ZodString>;
-    credentialSubject: z.ZodOptional<z.ZodObject<{
+    credentialSubject: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"user">;
         userId: z.ZodString;
         allowedWhen: z.ZodLiteral<"private-direct-conversation">;
-    }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"user">;
+        userId: z.ZodString;
+        allowedWhen: z.ZodLiteral<"scheduled-task">;
+        taskId: z.ZodString;
+    }, z.core.$strict>], "allowedWhen">>;
     destination: z.ZodObject<{
         platform: z.ZodLiteral<"slack">;
         teamId: z.ZodString;

package/dist/tools.d.ts

@@ -153,7 +153,9 @@ export interface SlackToolRegistrationHookContext {
         canCreateCanvas: boolean;
         canPostToChannel: boolean;
     };
-    credentialSubject?: PluginCredentialSubject;
+    credentialSubject?: Extract<PluginCredentialSubject, {
+        allowedWhen: "private-direct-conversation";
+    }>;
 }
 interface BaseToolRegistrationHookContext extends PluginContext {
     /**

package/package.json

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

package/src/schemas.ts

@@ -15,6 +15,9 @@ const exactActorUserIdSchema = z
 export const nonBlankStringSchema = z
   .string()
   .refine((value) => value.trim().length > 0);
+const exactNonBlankStringSchema = nonBlankStringSchema.refine(
+  (value) => value === value.trim(),
+);
 
 /** Runtime platform names supported by plugin public contracts. */
 export const platformSchema = z.enum(["slack", "local"]);
@@ -72,13 +75,26 @@ export const sourceSchema = z.discriminatedUnion("platform", [
 ]);
 
 /** 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();
+export const pluginCredentialSubjectSchema = z.discriminatedUnion(
+  "allowedWhen",
+  [
+    z
+      .object({
+        type: z.literal("user"),
+        userId: exactActorUserIdSchema,
+        allowedWhen: z.literal("private-direct-conversation"),
+      })
+      .strict(),
+    z
+      .object({
+        type: z.literal("user"),
+        userId: exactActorUserIdSchema,
+        allowedWhen: z.literal("scheduled-task"),
+        taskId: exactNonBlankStringSchema,
+      })
+      .strict(),
+  ],
+);
 
 /** Shared exact actor profile fields for platform-scoped actors. */
 const actorProfileSchema = {

package/src/tools.ts

@@ -277,7 +277,10 @@ export interface SlackToolRegistrationHookContext {
     canCreateCanvas: boolean;
     canPostToChannel: boolean;
   };
-  credentialSubject?: PluginCredentialSubject;
+  credentialSubject?: Extract<
+    PluginCredentialSubject,
+    { allowedWhen: "private-direct-conversation" }
+  >;
 }
 
 interface BaseToolRegistrationHookContext extends PluginContext {