@sentry/junior-plugin-api 0.74.1 → 0.76.0

package/dist/cli.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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/dist/context.d.ts

@@ -0,0 +1,97 @@
+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 declare function createSlackSource(input: {
+    channelId: string;
+    messageTs?: string;
+    teamId: string;
+    threadTs?: string;
+}): SlackSource;
+/** Build a normalized local source from a local conversation id. */
+export declare function createLocalSource(conversationId: string): LocalSource;
+/** Return whether a source is private to a person or restricted group. */
+export declare function isPrivateSource(source: Source): boolean;
+/** Return the stable source identity used for idempotency and attribution. */
+export declare function getSourceKey(source: Source): string | undefined;
+/** Narrow a runtime destination to the Slack-specific address shape. */
+export declare function isSlackDestination(destination: Destination | undefined): destination is SlackDestination;
+export {};

package/dist/credentials.d.ts

@@ -0,0 +1,167 @@
+import { z } from "zod";
+import type { PluginContext } from "./context";
+import { pluginCredentialSubjectSchema } from "./schemas";
+declare const pluginGrantAccessSchema: z.ZodUnion<readonly [z.ZodLiteral<"read">, z.ZodLiteral<"write">]>;
+/** Runtime schema for provider authorization a plugin may request. */
+export declare const pluginAuthorizationSchema: z.ZodObject<{
+    provider: z.ZodString;
+    scope: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"oauth">;
+}, z.core.$strict>;
+/** Runtime schema for a provider account attached to stored OAuth tokens. */
+export declare const pluginProviderAccountSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Runtime schema for OAuth tokens stored by the host for plugin credentials. */
+export declare const pluginStoredTokensSchema: z.ZodObject<{
+    account: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    accessToken: z.ZodString;
+    expiresAt: z.ZodOptional<z.ZodNumber>;
+    refreshToken: z.ZodString;
+    refreshTokenExpiresAt: z.ZodOptional<z.ZodNumber>;
+    scope: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Runtime schema for a plugin-defined outbound credential grant. */
+export declare const pluginGrantSchema: z.ZodObject<{
+    access: z.ZodUnion<readonly [z.ZodLiteral<"read">, z.ZodLiteral<"write">]>;
+    name: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+    requirements: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+/** Runtime schema for plugin-issued header mutations. */
+export declare const pluginCredentialHeaderTransformSchema: z.ZodObject<{
+    domain: z.ZodString;
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>;
+/** Runtime schema for a short-lived plugin-issued credential lease. */
+export declare const pluginCredentialLeaseSchema: z.ZodObject<{
+    account: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    authorization: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        scope: z.ZodOptional<z.ZodString>;
+        type: z.ZodLiteral<"oauth">;
+    }, z.core.$strict>>;
+    expiresAt: z.ZodString;
+    headerTransforms: z.ZodArray<z.ZodObject<{
+        domain: z.ZodString;
+        headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Runtime schema for the result returned by a plugin credential hook. */
+export declare const pluginCredentialResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    lease: z.ZodObject<{
+        account: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+            url: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        authorization: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodString;
+            scope: z.ZodOptional<z.ZodString>;
+            type: z.ZodLiteral<"oauth">;
+        }, z.core.$strict>>;
+        expiresAt: z.ZodString;
+        headerTransforms: z.ZodArray<z.ZodObject<{
+            domain: z.ZodString;
+            headers: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    type: z.ZodLiteral<"lease">;
+}, z.core.$strict>, z.ZodObject<{
+    authorization: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        scope: z.ZodOptional<z.ZodString>;
+        type: z.ZodLiteral<"oauth">;
+    }, z.core.$strict>>;
+    message: z.ZodString;
+    type: z.ZodLiteral<"needed">;
+}, z.core.$strict>, z.ZodObject<{
+    message: z.ZodString;
+    type: z.ZodLiteral<"unavailable">;
+}, z.core.$strict>], "type">;
+export type PluginCredentialSubject = z.output<typeof pluginCredentialSubjectSchema>;
+export type PluginGrantAccess = z.output<typeof pluginGrantAccessSchema>;
+/** Provider authorization Junior can start when a plugin-owned grant is missing. */
+export type PluginAuthorization = z.output<typeof pluginAuthorizationSchema>;
+/** Interrupt sandbox egress so Junior can start provider authorization. */
+export declare class EgressAuthRequired extends Error {
+    authorization?: PluginAuthorization;
+    constructor(message: string, options?: {
+        authorization?: PluginAuthorization;
+        cause?: unknown;
+    });
+}
+/** Provider account identity resolved by a plugin OAuth hook. */
+export type PluginProviderAccount = z.output<typeof pluginProviderAccountSchema>;
+/** Plugin-defined grant required before Junior can forward one outbound request. */
+export type PluginGrant = z.output<typeof pluginGrantSchema>;
+/** Request details available while selecting the grant for sandbox egress. */
+export interface PluginEgressRequest {
+    /** Capped request body text when the host exposes it for provider-specific grant classification. */
+    bodyText?: string;
+    method: string;
+    url: string;
+}
+export interface EgressHookContext extends PluginContext {
+    request: PluginEgressRequest;
+}
+export interface PluginEgressResponse {
+    /** Snapshot of upstream response headers; mutations do not affect pass-through. */
+    headers: Headers;
+    readText(maxBytes: number): Promise<string | undefined>;
+    status: number;
+}
+export interface EgressResponseHookContext extends PluginContext {
+    grant: PluginGrant;
+    permissionDenied(message: string): void;
+    request: Omit<PluginEgressRequest, "bodyText">;
+    response: PluginEgressResponse;
+}
+/** Header mutations a plugin-issued credential lease may apply to owned domains. */
+export type PluginCredentialHeaderTransform = z.output<typeof pluginCredentialHeaderTransformSchema>;
+/** Short-lived credential headers issued by a plugin for a selected grant. */
+export type PluginCredentialLease = z.output<typeof pluginCredentialLeaseSchema>;
+export type PluginCredentialResult = z.output<typeof pluginCredentialResultSchema>;
+export type PluginCredentialActor = {
+    type: "system";
+    id: string;
+} | {
+    type: "user";
+    userId: string;
+};
+export interface PluginResolvedCredentialUser {
+    type: "user";
+    userId: string;
+}
+export type PluginStoredTokens = z.output<typeof pluginStoredTokensSchema>;
+export interface PluginUserTokenSlot {
+    get(): Promise<PluginStoredTokens | undefined>;
+    set(tokens: PluginStoredTokens): Promise<void>;
+    /** Run token refresh work after the host has serialized this user/provider slot, or throw after a bounded wait. */
+    withRefresh<T>(callback: () => Promise<T>): Promise<T>;
+    userId: string;
+}
+export interface PluginTokenStore {
+    credentialSubject?: PluginUserTokenSlot;
+    currentUser?: PluginUserTokenSlot;
+}
+export interface ResolveOAuthAccountHookContext extends PluginContext {
+    tokens: PluginStoredTokens;
+}
+export interface IssueCredentialHookContext extends PluginContext {
+    actor: PluginCredentialActor;
+    credentialSubject?: PluginResolvedCredentialUser;
+    grant: PluginGrant;
+    tokens: PluginTokenStore;
+}
+export {};

package/dist/dispatch.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { dispatchOptionsSchema } from "./schemas";
+export type DispatchOptions = z.output<typeof dispatchOptionsSchema>;
+export interface DispatchResult {
+    id: string;
+    status: "created" | "already_exists";
+}
+export interface Dispatch {
+    errorMessage?: string;
+    id: string;
+    resultMessageTs?: string;
+    status: "pending" | "running" | "awaiting_resume" | "completed" | "failed" | "blocked";
+}

package/dist/hooks.d.ts

@@ -0,0 +1,20 @@
+import type { EgressHookContext, EgressResponseHookContext, IssueCredentialHookContext, PluginCredentialResult, PluginGrant, PluginProviderAccount, ResolveOAuthAccountHookContext } from "./credentials";
+import type { HeartbeatHookContext, HeartbeatResult, OperationalReportHookContext, PluginOperationalReportContent, PluginRoute, RouteRegistrationHookContext, SlackConversationLink, SlackConversationLinkHookContext, StorageMigrationContext, StorageMigrationResult } from "./operations";
+import type { BeforeToolExecuteHookContext, PluginToolDefinition, SandboxPrepareHookContext, ToolRegistrationHookContext } from "./tools";
+import type { PromptMessage, SystemPromptContext, UserPromptContext } from "./prompt";
+export interface PluginHooks {
+    systemPrompt?(ctx: SystemPromptContext): Promise<PromptMessage[]> | PromptMessage[];
+    userPrompt?(ctx: UserPromptContext): Promise<PromptMessage[] | undefined> | PromptMessage[] | undefined;
+    beforeToolExecute?(ctx: BeforeToolExecuteHookContext): Promise<void> | void;
+    grantForEgress?(ctx: EgressHookContext): Promise<PluginGrant | undefined> | PluginGrant | undefined;
+    heartbeat?(ctx: HeartbeatHookContext): Promise<HeartbeatResult | void> | HeartbeatResult | void;
+    issueCredential?(ctx: IssueCredentialHookContext): Promise<PluginCredentialResult> | PluginCredentialResult;
+    onEgressResponse?(ctx: EgressResponseHookContext): Promise<void> | void;
+    operationalReport?(ctx: OperationalReportHookContext): Promise<PluginOperationalReportContent | undefined> | PluginOperationalReportContent | undefined;
+    resolveOAuthAccount?(ctx: ResolveOAuthAccountHookContext): Promise<PluginProviderAccount | undefined> | PluginProviderAccount | undefined;
+    routes?(ctx: RouteRegistrationHookContext): PluginRoute[];
+    sandboxPrepare?(ctx: SandboxPrepareHookContext): Promise<void> | void;
+    slackConversationLink?(ctx: SlackConversationLinkHookContext): SlackConversationLink | undefined;
+    tools?(ctx: ToolRegistrationHookContext): Record<string, PluginToolDefinition>;
+    migrateStorage?(ctx: StorageMigrationContext): Promise<StorageMigrationResult | undefined> | StorageMigrationResult | undefined;
+}