@sentry/junior-plugin-api 0.197.0 → 0.199.0

package/src/context.ts

@@ -1,241 +0,0 @@
-import { z } from "zod";
-import type { ZodTypeAny } from "zod";
-import {
-  destinationSchema,
-  identitySchema,
-  locationSchema,
-  webActorSchema,
-  localActorSchema,
-  platformSchema,
-  actorSchema,
-  slackActorSchema,
-  systemActorSchema,
-  sourceSchema,
-  sourceVisibilitySchema,
-  slackLocationSchema,
-  userSchema,
-} from "./schemas";
-
-/** Runtime platform name without source or destination coordinates. */
-export type Platform = z.output<typeof platformSchema>;
-export type Actor = z.output<typeof actorSchema>;
-export type SlackActor = z.output<typeof slackActorSchema>;
-export type LocalActor = z.output<typeof localActorSchema>;
-export type WebActor = z.output<typeof webActorSchema>;
-export type SystemActor = z.output<typeof systemActorSchema>;
-export type Identity = z.output<typeof identitySchema>;
-export type User = z.output<typeof userSchema>;
-export type Source = z.output<typeof sourceSchema>;
-/** Validated Location associated with a Conversation. */
-export type Location = z.output<typeof locationSchema>;
-/** Complete Slack Location associated with a Conversation. */
-export type SlackLocation = z.output<typeof slackLocationSchema>;
-export type SlackSource = Extract<Source, { kind: "slack" }>;
-export type LocalSource = Extract<Source, { kind: "local" }>;
-export type WebSource = Extract<Source, { kind: "web" }>;
-export type ResourceEventSource = Extract<Source, { kind: "resource_event" }>;
-export type ScheduledTaskSource = Extract<Source, { kind: "scheduled_task" }>;
-export type EventTaskSource = Extract<Source, { kind: "event_task" }>;
-export type PluginDispatchSource = Extract<Source, { kind: "plugin_dispatch" }>;
-export type AgentInvocationSource = Extract<
-  Source,
-  { kind: "agent_invocation" }
->;
-export type SourceVisibility = z.output<typeof sourceVisibilitySchema>;
-
-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<{
-    /** Best-effort estimated provider cost for this completion. */
-    costUsd?: number;
-    object: z.infer<TSchema>;
-  }>;
-}
-
-export interface PluginEmbedder {
-  /** Embed plugin-owned text for derived retrieval without exposing provider credentials. */
-  embedTexts(input: { texts: string[] }): Promise<{
-    /** Best-effort estimated provider cost for this embedding call. */
-    costUsd?: number;
-    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;
-  /** Location associated with this Conversation. */
-  locationId?: string;
-}
-
-export interface SlackInvocationContext extends BaseInvocationContext {
-  /** Runtime-owned default outbound destination for this invocation. */
-  destination: SlackDestination;
-  actor?: SlackActor;
-  /** 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;
-  actor?: LocalActor;
-  /** Runtime-owned source where the invocation came from. */
-  source: LocalSource;
-}
-
-export interface WebInvocationContext extends BaseInvocationContext {
-  /** Existing conversation destination used for location and tool context. */
-  destination: Destination;
-  actor?: WebActor;
-  /** Runtime-owned dashboard/web source for this invocation. */
-  source: WebSource;
-}
-
-export interface ResourceEventInvocationContext extends BaseInvocationContext {
-  /** Existing conversation destination used for tool context. */
-  destination: Destination;
-  actor?: Actor;
-  /** Runtime-owned Resource event Source for this invocation. */
-  source: ResourceEventSource;
-}
-
-export type InvocationContext =
-  | LocalInvocationContext
-  | SlackInvocationContext
-  | WebInvocationContext
-  | (BaseInvocationContext & {
-      destination: Destination;
-      actor?: Actor;
-      source:
-        | AgentInvocationSource
-        | EventTaskSource
-        | PluginDispatchSource
-        | ResourceEventSource
-        | ScheduledTaskSource;
-    });
-
-/** Build a normalized Slack source from runtime-owned Slack coordinates. */
-export function createSlackSource(input: {
-  channelId: string;
-  messageTs?: string;
-  teamId: string;
-  threadTs?: string;
-  /** Runtime-normalized source visibility. */
-  visibility: SourceVisibility;
-}): SlackSource {
-  return {
-    kind: "slack",
-    visibility: input.visibility,
-    teamId: input.teamId,
-    channelId: input.channelId,
-    ...(input.messageTs ? { messageTs: input.messageTs } : undefined),
-    ...(input.threadTs ? { threadTs: input.threadTs } : undefined),
-  };
-}
-
-/** Build a normalized local source from a local conversation id. */
-export function createLocalSource(conversationId: string): LocalSource {
-  return {
-    kind: "local",
-    visibility: "private",
-    conversationId,
-  };
-}
-
-/** Build a normalized web/dashboard source from a conversation id. */
-export function createWebSource(
-  conversationId: string,
-  visibility: SourceVisibility = "public",
-): WebSource {
-  return {
-    kind: "web",
-    visibility,
-    conversationId,
-  };
-}
-
-/** Build a normalized Resource event Source from one matched event. */
-export function createResourceEventSource(input: {
-  eventKey: string;
-  eventType: string;
-  identifier: string;
-  namespace: string;
-}): ResourceEventSource {
-  return {
-    kind: "resource_event",
-    eventKey: input.eventKey,
-    eventType: input.eventType,
-    identifier: input.identifier,
-    namespace: input.namespace,
-  };
-}
-
-/** Return whether a source is private to a person or restricted group. */
-export function isPrivateSource(source: Source): boolean {
-  return "visibility" in source && source.visibility === "private";
-}
-
-/** Return the stable source identity used for idempotency and attribution. */
-export function getSourceKey(source: Source): string | undefined {
-  switch (source.kind) {
-    case "web":
-    case "local":
-      return source.conversationId;
-    case "slack": {
-      const messageKey = source.threadTs ?? source.messageTs;
-      if (!messageKey) {
-        return undefined;
-      }
-      return `slack:${source.teamId}:${source.channelId}:${messageKey}`;
-    }
-    case "resource_event":
-      return `resource-event:${source.namespace}:${source.eventKey}`;
-    case "scheduled_task":
-    case "event_task":
-    case "plugin_dispatch":
-    case "agent_invocation":
-      return undefined;
-  }
-}
-
-/** Narrow a runtime destination to the Slack-specific address shape. */
-export function isSlackDestination(
-  destination: Destination | undefined,
-): destination is SlackDestination {
-  return destination?.platform === "slack";
-}

package/src/conversation-events.ts

@@ -1,136 +0,0 @@
-import { z } from "zod";
-
-const conversationEventNameSchema = z
-  .string()
-  .trim()
-  .min(1)
-  .max(64)
-  .regex(/^[a-z][a-z0-9_]*$/);
-
-export const conversationEventIconSchema = z.enum([
-  "activity",
-  "brain",
-  "calendar",
-  "check",
-  "database",
-  "info",
-  "key",
-  "link",
-  "sparkles",
-  "warning",
-]);
-
-const conversationEventDetailSchema = z
-  .object({
-    content: z
-      .string()
-      .min(1)
-      .max(32 * 1024)
-      .optional(),
-    description: z.string().trim().min(1).max(2_000).optional(),
-    metadata: z.array(z.string().trim().min(1).max(120)).max(8).optional(),
-    title: z.string().trim().min(1).max(4_000),
-  })
-  .strict();
-
-/** Safe, core-rendered presentation for one plugin conversation event. */
-export const conversationEventPresentationSchema = z
-  .object({
-    details: z.array(conversationEventDetailSchema).max(100).optional(),
-    icon: conversationEventIconSchema.optional(),
-    preview: z.string().trim().min(1).max(500).optional(),
-    title: z.string().trim().min(1).max(120),
-  })
-  .strict();
-
-export type ConversationEventPresentation = z.output<
-  typeof conversationEventPresentationSchema
->;
-
-/** One validated plugin event value waiting for conversation-bound emission. */
-export interface PluginConversationEventValue {
-  readonly data: Record<string, unknown>;
-  readonly definition: PluginConversationEventDefinition;
-}
-
-/** Registered schema and optional transcript presentation for one event version. */
-export interface PluginConversationEventDefinition {
-  readonly eventName: string;
-  readonly version: number;
-  parse(data: unknown): Record<string, unknown>;
-  renderEvent(
-    data: Record<string, unknown>,
-  ): ConversationEventPresentation | undefined;
-}
-
-/** Typed factory returned while authoring one plugin conversation event. */
-export interface DefinedConversationEvent<
-  TInput,
-> extends PluginConversationEventDefinition {
-  (data: TInput): PluginConversationEventValue;
-}
-
-/** Define one typed, versioned plugin-owned conversation event. */
-export function defineConversationEvent<
-  TSchema extends z.ZodType<Record<string, unknown>>,
->(definition: {
-  name: string;
-  version: number;
-  schema: TSchema;
-  renderEvent(
-    event: z.output<TSchema>,
-  ): z.input<typeof conversationEventPresentationSchema> | undefined;
-}): DefinedConversationEvent<z.input<TSchema>> {
-  const identity = z
-    .object({
-      name: conversationEventNameSchema,
-      version: z.number().int().positive(),
-    })
-    .strict()
-    .parse({ name: definition.name, version: definition.version });
-  let eventDefinition: DefinedConversationEvent<z.input<TSchema>>;
-  const createEvent = (
-    data: z.input<TSchema>,
-  ): PluginConversationEventValue => ({
-    data: definition.schema.parse(data),
-    definition: eventDefinition,
-  });
-  eventDefinition = Object.assign(createEvent, {
-    eventName: identity.name,
-    version: identity.version,
-    parse(data: unknown) {
-      return definition.schema.parse(data);
-    },
-    renderEvent(data: Record<string, unknown>) {
-      const parsed = definition.schema.parse(data);
-      const presentation = definition.renderEvent(parsed);
-      return presentation === undefined
-        ? undefined
-        : conversationEventPresentationSchema.parse(presentation);
-    },
-  });
-  return eventDefinition;
-}
-
-/** Conversation-bound event writer supplied by Junior core. */
-export interface PluginConversationEvents {
-  emit(event: PluginConversationEventValue): Promise<void>;
-}
-
-export interface PluginConversationEventCostDay {
-  costUsd: number;
-  date: string;
-  events: number;
-}
-
-/** Read aggregate costs for events owned by the current plugin namespace. */
-export interface PluginConversationEventStats {
-  costsByDay(input: {
-    days: 7 | 30 | 90;
-    eventName: string;
-  }): Promise<PluginConversationEventCostDay[]>;
-  costsByHour(input: {
-    eventName: string;
-    hours?: number;
-  }): Promise<PluginConversationEventCostDay[]>;
-}

package/src/credentials.ts

@@ -1,221 +0,0 @@
-import { z } from "zod";
-import type { PluginContext } from "./context";
-import { nonBlankStringSchema, pluginCredentialSubjectSchema } from "./schemas";
-
-const pluginProviderNameSchema = z.string().regex(/^[a-z][a-z0-9-]*$/);
-const pluginGrantNameSchema = z.string().regex(/^[a-z][a-z0-9.-]*$/);
-const pluginGrantAccessSchema = z.union([
-  z.literal("read"),
-  z.literal("write"),
-]);
-
-/** Runtime schema for provider authorization a plugin may request. */
-export const pluginAuthorizationSchema = z
-  .object({
-    provider: pluginProviderNameSchema,
-    scope: nonBlankStringSchema.optional(),
-    type: z.literal("oauth"),
-  })
-  .strict();
-
-/** Runtime schema for a provider account attached to stored OAuth tokens. */
-export const pluginProviderAccountSchema = z
-  .object({
-    displayName: nonBlankStringSchema.optional(),
-    handle: nonBlankStringSchema.optional(),
-    id: nonBlankStringSchema,
-    label: nonBlankStringSchema.optional(),
-    url: nonBlankStringSchema.optional(),
-  })
-  .strict();
-
-/** Runtime schema for OAuth tokens stored by the host for plugin credentials. */
-export const pluginStoredTokensSchema = z
-  .object({
-    account: pluginProviderAccountSchema.optional(),
-    accessToken: nonBlankStringSchema,
-    expiresAt: z.number().finite().optional(),
-    refreshToken: nonBlankStringSchema,
-    refreshTokenExpiresAt: z.number().finite().optional(),
-    scope: nonBlankStringSchema.optional(),
-  })
-  .strict();
-
-/** Runtime schema for a plugin-defined outbound credential grant. */
-export const pluginGrantSchema = z
-  .object({
-    access: pluginGrantAccessSchema,
-    leaseScope: nonBlankStringSchema.optional(),
-    name: pluginGrantNameSchema,
-    reason: nonBlankStringSchema.optional(),
-    requirements: z.array(nonBlankStringSchema).min(1).optional(),
-  })
-  .strict();
-
-/** Runtime schema for plugin-issued header mutations. */
-export const pluginCredentialHeaderTransformSchema = z
-  .object({
-    domain: z.string().min(1),
-    headers: z
-      .record(z.string(), z.string())
-      .refine((headers) => Object.keys(headers).length > 0),
-  })
-  .strict();
-
-/** Runtime schema for a short-lived plugin-issued credential lease. */
-export const pluginCredentialLeaseSchema = z
-  .object({
-    account: pluginProviderAccountSchema.optional(),
-    authorization: pluginAuthorizationSchema.optional(),
-    expiresAt: z.string().refine((value) => Number.isFinite(Date.parse(value))),
-    headerTransforms: z.array(pluginCredentialHeaderTransformSchema).min(1),
-  })
-  .strict();
-
-/** Runtime schema for the result returned by a plugin credential hook. */
-export const pluginCredentialResultSchema = z.discriminatedUnion("type", [
-  z
-    .object({
-      lease: pluginCredentialLeaseSchema,
-      type: z.literal("lease"),
-    })
-    .strict(),
-  z
-    .object({
-      authorization: pluginAuthorizationSchema.optional(),
-      message: nonBlankStringSchema,
-      type: z.literal("needed"),
-    })
-    .strict(),
-  z
-    .object({
-      message: nonBlankStringSchema,
-      type: z.literal("unavailable"),
-    })
-    .strict(),
-]);
-
-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 class EgressAuthRequired extends Error {
-  authorization?: PluginAuthorization;
-
-  constructor(
-    message: string,
-    options?: {
-      authorization?: PluginAuthorization;
-      cause?: unknown;
-    },
-  ) {
-    super(message, { cause: options?.cause });
-    this.name = "EgressAuthRequired";
-    this.authorization = options?.authorization;
-  }
-}
-
-/** Deny provider egress before Junior issues credentials for a disallowed operation. */
-export class EgressPolicyDenied extends Error {
-  constructor(message: string, options?: { cause?: unknown }) {
-    super(message, { cause: options?.cause });
-    this.name = "EgressPolicyDenied";
-  }
-}
-
-/** 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;
-  /** Plugin-declared operation this request performs, used for grant classification and diagnostics. */
-  operation?: 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 =
-  | {
-      platform: "system";
-      name: 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;
-}

package/src/dispatch.ts

@@ -1,31 +0,0 @@
-import { z } from "zod";
-import {
-  destinationVisibilitySchema,
-  dispatchOptionsSchema,
-  replyAttributionSchema,
-} from "./schemas";
-
-export type DestinationVisibility = z.output<
-  typeof destinationVisibilitySchema
->;
-export type DispatchOptions = z.output<typeof dispatchOptionsSchema>;
-/** Compact destination-visible context explaining what produced a reply. */
-export type ReplyAttribution = z.output<typeof replyAttributionSchema>;
-
-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/src/egress-policy.ts

@@ -1,15 +0,0 @@
-import { EgressPolicyDenied } from "./credentials";
-
-/**
- * Deny provider egress when a plugin policy does not allow the request.
- *
- * Call from a plugin `grantForEgress` hook before returning a write grant.
- */
-export function enforceEgressPolicy(input: {
-  allowed: boolean;
-  denialMessage: string;
-}): void {
-  if (!input.allowed) {
-    throw new EgressPolicyDenied(input.denialMessage);
-  }
-}