@sentry/junior-plugin-api 0.74.1 → 0.76.0

package/dist/schemas.d.ts

@@ -0,0 +1,133 @@
+import { z } from "zod";
+export declare const nonBlankStringSchema: z.ZodString;
+/** Runtime platform names supported by plugin public contracts. */
+export declare const platformSchema: z.ZodEnum<{
+    slack: "slack";
+    local: "local";
+}>;
+/** Runtime source visibility visible to plugins. */
+export declare const sourceTypeSchema: z.ZodEnum<{
+    pub: "pub";
+    priv: "priv";
+}>;
+/** Runtime-owned Slack address for routing future work or side effects. */
+export declare const slackDestinationSchema: z.ZodObject<{
+    platform: z.ZodLiteral<"slack">;
+    teamId: z.ZodString;
+    channelId: z.ZodString;
+}, z.core.$strict>;
+/** Runtime-owned local CLI conversation address. */
+export declare const localDestinationSchema: z.ZodObject<{
+    platform: z.ZodLiteral<"local">;
+    conversationId: z.ZodString;
+}, z.core.$strict>;
+/** Runtime-owned provider-neutral address for routing future work or side effects. */
+export declare const destinationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    platform: z.ZodLiteral<"slack">;
+    teamId: z.ZodString;
+    channelId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    platform: z.ZodLiteral<"local">;
+    conversationId: z.ZodString;
+}, z.core.$strict>], "platform">;
+/** Runtime-owned Slack coordinates for the inbound invocation. */
+export declare const slackSourceSchema: z.ZodObject<{
+    platform: z.ZodLiteral<"slack">;
+    teamId: z.ZodString;
+    channelId: z.ZodString;
+    type: z.ZodEnum<{
+        pub: "pub";
+        priv: "priv";
+    }>;
+    messageTs: z.ZodOptional<z.ZodString>;
+    threadTs: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Runtime-owned local CLI coordinates for the inbound invocation. */
+export declare const localSourceSchema: z.ZodObject<{
+    platform: z.ZodLiteral<"local">;
+    type: z.ZodLiteral<"priv">;
+    conversationId: z.ZodString;
+}, z.core.$strict>;
+/** Runtime-owned provider-neutral coordinates for the inbound invocation. */
+export declare const sourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    platform: z.ZodLiteral<"slack">;
+    teamId: z.ZodString;
+    channelId: z.ZodString;
+    type: z.ZodEnum<{
+        pub: "pub";
+        priv: "priv";
+    }>;
+    messageTs: z.ZodOptional<z.ZodString>;
+    threadTs: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    platform: z.ZodLiteral<"local">;
+    type: z.ZodLiteral<"priv">;
+    conversationId: z.ZodString;
+}, z.core.$strict>], "platform">;
+/** Stable user credential subject shape accepted from plugins. */
+export declare const pluginCredentialSubjectSchema: z.ZodObject<{
+    type: z.ZodLiteral<"user">;
+    userId: z.ZodString;
+    allowedWhen: z.ZodLiteral<"private-direct-conversation">;
+}, z.core.$strict>;
+export declare const slackRequesterSchema: z.ZodObject<{
+    platform: z.ZodLiteral<"slack">;
+    teamId: z.ZodString;
+    email: z.ZodOptional<z.ZodString>;
+    fullName: z.ZodOptional<z.ZodString>;
+    userId: z.ZodString;
+    userName: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const localRequesterSchema: z.ZodObject<{
+    platform: z.ZodLiteral<"local">;
+    email: z.ZodOptional<z.ZodString>;
+    fullName: z.ZodOptional<z.ZodString>;
+    userId: z.ZodString;
+    userName: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Runtime-provided requester identity visible to plugin hooks. */
+export declare const requesterSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    platform: z.ZodLiteral<"slack">;
+    teamId: z.ZodString;
+    email: z.ZodOptional<z.ZodString>;
+    fullName: z.ZodOptional<z.ZodString>;
+    userId: z.ZodString;
+    userName: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    platform: z.ZodLiteral<"local">;
+    email: z.ZodOptional<z.ZodString>;
+    fullName: z.ZodOptional<z.ZodString>;
+    userId: z.ZodString;
+    userName: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "platform">;
+/** 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<{
+        type: z.ZodLiteral<"user">;
+        userId: z.ZodString;
+        allowedWhen: z.ZodLiteral<"private-direct-conversation">;
+    }, z.core.$strict>>;
+    destination: z.ZodObject<{
+        platform: z.ZodLiteral<"slack">;
+        teamId: z.ZodString;
+        channelId: z.ZodString;
+    }, z.core.$strict>;
+    input: z.ZodPipe<z.ZodString, z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        platform: z.ZodLiteral<"slack">;
+        teamId: z.ZodString;
+        channelId: z.ZodString;
+        type: z.ZodEnum<{
+            pub: "pub";
+            priv: "priv";
+        }>;
+        messageTs: z.ZodOptional<z.ZodString>;
+        threadTs: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        platform: z.ZodLiteral<"local">;
+        type: z.ZodLiteral<"priv">;
+        conversationId: z.ZodString;
+    }, z.core.$strict>], "platform">;
+}, z.core.$strict>;

package/dist/state.d.ts

@@ -0,0 +1,10 @@
+export interface PluginState {
+    delete(key: string): Promise<void>;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown, ttlMs?: number): Promise<void>;
+    setIfNotExists(key: string, value: unknown, ttlMs?: number): Promise<boolean>;
+    withLock<T>(key: string, ttlMs: number, callback: () => Promise<T>): Promise<T>;
+}
+export interface PluginReadState {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+}

package/dist/tasks.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Public plugin background-task contracts.
+ *
+ * Plugins register small task handlers, while Junior core owns durable
+ * scheduling, queue delivery, retries, and the bounded run projection.
+ */
+import { z } from "zod";
+import type { PluginContext, PluginEmbedder, PluginModel } from "./context";
+import type { PluginState } from "./state";
+/** One normalized transcript entry from the completed run exposed to plugin tasks. */
+export declare const pluginRunTranscriptEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"message">;
+    role: z.ZodEnum<{
+        user: "user";
+        assistant: "assistant";
+    }>;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"toolResult">;
+    toolName: z.ZodString;
+    isError: z.ZodBoolean;
+    text: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "type">;
+/** Runtime-owned completed-run projection exposed to plugin tasks. */
+export declare const pluginRunContextSchema: z.ZodObject<{
+    completedAtMs: z.ZodNumber;
+    conversationId: z.ZodString;
+    destination: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        platform: z.ZodLiteral<"slack">;
+        teamId: z.ZodString;
+        channelId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        platform: z.ZodLiteral<"local">;
+        conversationId: z.ZodString;
+    }, z.core.$strict>], "platform">;
+    requester: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        platform: z.ZodLiteral<"slack">;
+        teamId: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        fullName: z.ZodOptional<z.ZodString>;
+        userId: z.ZodString;
+        userName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        platform: z.ZodLiteral<"local">;
+        email: z.ZodOptional<z.ZodString>;
+        fullName: z.ZodOptional<z.ZodString>;
+        userId: z.ZodString;
+        userName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "platform">>;
+    runId: z.ZodString;
+    source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        platform: z.ZodLiteral<"slack">;
+        teamId: z.ZodString;
+        channelId: z.ZodString;
+        type: z.ZodEnum<{
+            pub: "pub";
+            priv: "priv";
+        }>;
+        messageTs: z.ZodOptional<z.ZodString>;
+        threadTs: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        platform: z.ZodLiteral<"local">;
+        type: z.ZodLiteral<"priv">;
+        conversationId: z.ZodString;
+    }, z.core.$strict>], "platform">;
+    transcript: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"message">;
+        role: z.ZodEnum<{
+            user: "user";
+            assistant: "assistant";
+        }>;
+        text: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"toolResult">;
+        toolName: z.ZodString;
+        isError: z.ZodBoolean;
+        text: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "type">>;
+}, z.core.$strict>;
+export type PluginRunTranscriptEntry = z.output<typeof pluginRunTranscriptEntrySchema>;
+export type PluginRunContext = z.output<typeof pluginRunContextSchema>;
+/** Runtime context passed to a plugin-owned background task. */
+export interface PluginTaskContext extends PluginContext {
+    embedder: PluginEmbedder;
+    id: string;
+    model: PluginModel;
+    name: string;
+    run: {
+        load(): Promise<PluginRunContext>;
+    };
+    state: PluginState;
+}
+/** Plugin task handler registered by name in a plugin manifest module. */
+export interface PluginTaskDefinition {
+    run(ctx: PluginTaskContext): Promise<void> | void;
+}
+/** Task handlers keyed by the plugin-owned task name. */
+export type PluginTasks = Record<string, PluginTaskDefinition>;

package/dist/tools.d.ts

@@ -0,0 +1,116 @@
+import type { PluginContext, LocalInvocationContext, PluginEmbedder, PluginModel, Requester, SlackInvocationContext } from "./context";
+import type { PluginCredentialSubject } from "./credentials";
+import type { PluginState } from "./state";
+export interface PluginEnv {
+    get(key: string): string | undefined;
+    set(key: string, value: string): void;
+}
+export interface PluginDecision {
+    deny(message: string): void;
+    replaceInput(input: Record<string, unknown>): void;
+}
+/** Thrown when a plugin tool rejects invalid model or user input. */
+export declare class PluginToolInputError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface PluginSandbox {
+    juniorRoot: string;
+    root: string;
+    readFile(path: string): Promise<Uint8Array | null>;
+    run(input: {
+        args?: string[];
+        cmd: string;
+        cwd?: string;
+        env?: Record<string, string>;
+        sudo?: boolean;
+    }): Promise<{
+        exitCode: number;
+        stderr: string;
+        stdout: string;
+    }>;
+    writeFile(input: {
+        content: string | Uint8Array;
+        mode?: number;
+        path: string;
+    }): Promise<void>;
+}
+export interface SandboxPrepareHookContext extends PluginContext {
+    requester?: Requester;
+    sandbox: PluginSandbox;
+}
+export interface BeforeToolExecuteHookContext extends PluginContext {
+    decision: PluginDecision;
+    env: PluginEnv;
+    requester?: Requester;
+    tool: {
+        input: Record<string, unknown>;
+        name: string;
+    };
+}
+export interface PluginToolExecuteOptions {
+    /**
+     * @deprecated Internal compatibility escape hatch for legacy tool bridges.
+     * Plugin tools should use typed input fields and runtime hook context instead.
+     */
+    experimental_context?: unknown;
+    /** Stable runtime tool-call id; durable create tools should derive idempotency keys from it. */
+    toolCallId?: string;
+}
+export type PluginToolExecute<TInput = unknown> = {
+    bivarianceHack(input: TInput, options: PluginToolExecuteOptions): Promise<unknown> | unknown;
+}["bivarianceHack"];
+export interface PluginToolDefinition<TInput = unknown> {
+    annotations?: unknown;
+    description: string;
+    executionMode?: unknown;
+    inputSchema: unknown;
+    prepareArguments?: (args: unknown) => unknown;
+    /**
+     * @deprecated Put tool-selection and usage guidance directly in `description`
+     * and parameter descriptions. Retained for compatibility; may be removed in a
+     * future major version.
+     */
+    promptGuidelines?: string[];
+    /**
+     * @deprecated Put tool-selection and usage guidance directly in `description`
+     * and parameter descriptions. Retained for compatibility; may be removed in a
+     * future major version.
+     */
+    promptSnippet?: string;
+    execute?: PluginToolExecute<TInput>;
+}
+export interface SlackToolRegistrationHookContext {
+    /**
+     * Capabilities of the source Slack conversation exposed to this plugin.
+     * Recomputed from `source.channelId`, not from `destination`.
+     */
+    channelCapabilities: {
+        canAddReactions: boolean;
+        canCreateCanvas: boolean;
+        canPostToChannel: boolean;
+    };
+    credentialSubject?: PluginCredentialSubject;
+}
+interface BaseToolRegistrationHookContext extends PluginContext {
+    /**
+     * Opaque Junior conversation/session identity for this turn.
+     * Interactive Slack turns use `slack:{channelId}:{threadTs}`.
+     * Scheduled/API turns use an internal id such as `agent-dispatch:{id}`.
+     * Do not parse as Slack unless the value starts with `slack:`.
+     */
+    conversationId?: string;
+    embedder: PluginEmbedder;
+    model: PluginModel;
+    state: PluginState;
+    userText?: string;
+}
+interface SlackToolRegistrationContext extends BaseToolRegistrationHookContext, SlackInvocationContext {
+    slack: SlackToolRegistrationHookContext;
+}
+interface LocalToolRegistrationContext extends BaseToolRegistrationHookContext, LocalInvocationContext {
+    slack?: never;
+}
+export type ToolRegistrationHookContext = LocalToolRegistrationContext | SlackToolRegistrationContext;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-plugin-api",
-  "version": "0.74.1",
+  "version": "0.76.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -22,6 +22,7 @@
     "src"
   ],
   "dependencies": {
+    "commander": "^14.0.3",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/src/cli.ts

@@ -0,0 +1,54 @@
+/**
+ * Public Commander-based CLI contract for plugin-owned admin commands.
+ * Junior owns the root command, plugin namespaces, context injection, and exit
+ * normalization; plugins only configure subcommands under their namespace.
+ */
+import type { Command } from "commander";
+import type { PluginContext } from "./context";
+
+export interface PluginCliIo {
+  writeError(text: string): Promise<void> | void;
+  writeOutput(text: string): Promise<void> | void;
+}
+
+export interface PluginCliActionCommand {
+  name: string;
+  summary: string;
+}
+
+/** Host/admin context exposed to plugin-owned CLI command actions. */
+export interface PluginCliActionContext extends Pick<
+  PluginContext,
+  "db" | "log" | "plugin"
+> {
+  command: PluginCliActionCommand;
+  io: PluginCliIo;
+}
+
+/** Plugin action callback wrapped by the Junior host for context and exit codes. */
+export type PluginCliActionHandler<Args extends unknown[] = unknown[]> = (
+  ctx: PluginCliActionContext,
+  ...args: Args
+) => Promise<number | void> | number | void;
+
+export interface PluginCliHost {
+  /** Wrap a Commander action so Junior can inject context and normalize exits. */
+  action<Args extends unknown[]>(
+    handler: PluginCliActionHandler<Args>,
+  ): (...args: Args) => Promise<void>;
+}
+
+/** Plugin-owned top-level CLI command registration. */
+export interface PluginCliCommandDefinition {
+  /** Configure subcommands under the host-created top-level namespace. */
+  configure(command: Command, junior: PluginCliHost): void;
+  /** Unique host-level command namespace owned by this plugin. */
+  name: string;
+  /** One-line summary used in generated command help. */
+  summary: string;
+}
+
+/** Plugin-owned CLI command catalog. */
+export interface PluginCliDefinition {
+  commands: PluginCliCommandDefinition[];
+}

package/src/context.ts

@@ -0,0 +1,146 @@
+import { z } from "zod";
+import type { ZodTypeAny } from "zod";
+import {
+  destinationSchema,
+  localRequesterSchema,
+  platformSchema,
+  requesterSchema,
+  slackRequesterSchema,
+  sourceSchema,
+} from "./schemas";
+
+/** Runtime platform name without source or destination coordinates. */
+export type Platform = z.output<typeof platformSchema>;
+export type Requester = z.output<typeof requesterSchema>;
+export type SlackRequester = z.output<typeof slackRequesterSchema>;
+export type LocalRequester = z.output<typeof localRequesterSchema>;
+export type Source = z.output<typeof sourceSchema>;
+export type SlackSource = Extract<Source, { platform: "slack" }>;
+export type LocalSource = Extract<Source, { platform: "local" }>;
+export type SourceType = Source["type"];
+
+export type Destination = z.output<typeof destinationSchema>;
+
+export type SlackDestination = Extract<Destination, { platform: "slack" }>;
+
+export type LocalDestination = Extract<Destination, { platform: "local" }>;
+
+export interface PluginMetadata {
+  name: string;
+}
+
+export interface PluginLogger {
+  error(message: string, metadata?: Record<string, unknown>): void;
+  info(message: string, metadata?: Record<string, unknown>): void;
+  warn(message: string, metadata?: Record<string, unknown>): void;
+}
+
+export interface PluginModel {
+  /** Run a host-owned structured model call without exposing provider credentials. */
+  completeObject<TSchema extends ZodTypeAny>(input: {
+    maxTokens?: number;
+    prompt: string;
+    schema: TSchema;
+    system?: string;
+  }): Promise<{ object: z.infer<TSchema> }>;
+}
+
+export interface PluginEmbedder {
+  /** Embed plugin-owned text for derived retrieval without exposing provider credentials. */
+  embedTexts(input: { texts: string[] }): Promise<{
+    dimensions: number;
+    model: string;
+    provider: string;
+    vectors: number[][];
+  }>;
+}
+
+export interface PluginContext {
+  /** Shared Drizzle database connection for plugin runtime code. */
+  db: unknown;
+  log: PluginLogger;
+  plugin: PluginMetadata;
+}
+
+interface BaseInvocationContext {
+  /**
+   * Opaque Junior conversation/session identity for this invocation.
+   * Interactive Slack turns use `slack:{channelId}:{threadTs}`.
+   */
+  conversationId?: string;
+}
+
+export interface SlackInvocationContext extends BaseInvocationContext {
+  /** Runtime-owned default outbound destination for this invocation. */
+  destination: SlackDestination;
+  requester?: SlackRequester;
+  /** Runtime-owned source where the invocation came from. */
+  source: SlackSource;
+}
+
+export interface LocalInvocationContext extends BaseInvocationContext {
+  /** Runtime-owned default outbound destination for this invocation. */
+  destination: LocalDestination;
+  requester?: LocalRequester;
+  /** Runtime-owned source where the invocation came from. */
+  source: LocalSource;
+}
+
+export type InvocationContext = LocalInvocationContext | SlackInvocationContext;
+
+/** Build a normalized Slack source from runtime-owned Slack coordinates. */
+export function createSlackSource(input: {
+  channelId: string;
+  messageTs?: string;
+  teamId: string;
+  threadTs?: string;
+}): SlackSource {
+  return {
+    platform: "slack",
+    type: slackSourceType(input.channelId),
+    teamId: input.teamId,
+    channelId: input.channelId,
+    ...(input.messageTs ? { messageTs: input.messageTs } : {}),
+    ...(input.threadTs ? { threadTs: input.threadTs } : {}),
+  };
+}
+
+/** Classify Slack's documented C/D/G channel id prefixes into source visibility. */
+function slackSourceType(channelId: string): SourceType {
+  if (channelId.startsWith("C")) return "pub";
+  if (channelId.startsWith("D") || channelId.startsWith("G")) return "priv";
+  throw new Error(`Unsupported Slack channel ID prefix: ${channelId}`);
+}
+
+/** Build a normalized local source from a local conversation id. */
+export function createLocalSource(conversationId: string): LocalSource {
+  return {
+    platform: "local",
+    type: "priv",
+    conversationId,
+  };
+}
+
+/** Return whether a source is private to a person or restricted group. */
+export function isPrivateSource(source: Source): boolean {
+  return source.type === "priv";
+}
+
+/** Return the stable source identity used for idempotency and attribution. */
+export function getSourceKey(source: Source): string | undefined {
+  if (source.platform === "local") {
+    return source.conversationId;
+  }
+  const messageKey = source.threadTs ?? source.messageTs;
+  if (!messageKey) {
+    return undefined;
+  }
+  return `slack:${source.teamId}:${source.channelId}:${messageKey}`;
+}
+
+/** Narrow a runtime destination to the Slack-specific address shape. */
+export function isSlackDestination(
+  destination: Destination | undefined,
+): destination is SlackDestination {
+  return destination?.platform === "slack";
+}