@sentry/junior-plugin-api 0.72.0 → 0.74.0

package/dist/index.d.ts

@@ -1,25 +1,84 @@
 import { z } from "zod";
+/** 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.ZodObject<{
+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;
+    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">;
+    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;
+    messageTs: z.ZodOptional<z.ZodString>;
+    threadTs: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    platform: z.ZodLiteral<"local">;
+    conversationId: z.ZodString;
+}, z.core.$strict>], "platform">;
 /** Stable user credential subject shape accepted from plugins. */
 export declare const agentPluginCredentialSubjectSchema: z.ZodObject<{
     type: z.ZodLiteral<"user">;
     userId: z.ZodString;
     allowedWhen: z.ZodLiteral<"private-direct-conversation">;
 }, z.core.$strict>;
-/** Runtime-provided requester identity visible to plugin hooks. */
-export declare const requesterSchema: z.ZodObject<{
+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>;
-    fullName: 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>;
@@ -37,6 +96,15 @@ export declare const dispatchOptionsSchema: z.ZodObject<{
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strict>;
 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 interface AgentPluginMetadata {
     name: string;
 }
@@ -63,6 +131,28 @@ export interface AgentPluginContext {
     log: AgentPluginLogger;
     plugin: AgentPluginMetadata;
 }
+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, if any. */
+    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, if any. */
+    destination?: LocalDestination;
+    requester?: LocalRequester;
+    /** Runtime-owned source where the invocation came from. */
+    source: LocalSource;
+}
+export type InvocationContext = LocalInvocationContext | SlackInvocationContext;
 export interface AgentPluginSandbox {
     juniorRoot: string;
     root: string;
@@ -122,23 +212,19 @@ export interface AgentPluginToolDefinition<TInput = unknown> {
     promptSnippet?: string;
     execute?: AgentPluginToolExecute<TInput>;
 }
-export interface ToolRegistrationHookContext extends AgentPluginContext {
+export interface SlackToolRegistrationHookContext {
     /**
-     * Capabilities of `channelId` — the raw conversation channel exposed to
-     * this plugin. Recomputed from `channelId`, not from `destination`.
+     * Capabilities of the source Slack conversation exposed to this plugin.
+     * Recomputed from `source.channelId`, not from `destination`.
      */
-    channelCapabilities?: {
+    channelCapabilities: {
         canAddReactions: boolean;
         canCreateCanvas: boolean;
         canPostToChannel: boolean;
     };
-    /**
-     * The raw Slack channel ID for this conversation — the DM or channel where
-     * this turn is happening, without any assistant-context-source override.
-     * Use this as the stable binding key for state scoped to a Slack conversation.
-     * `channelCapabilities` describes this channel.
-     */
-    channelId?: string;
+    credentialSubject?: AgentPluginCredentialSubject;
+}
+interface BaseToolRegistrationHookContext extends AgentPluginContext {
     /**
      * Opaque Junior conversation/session identity for this turn.
      * Interactive Slack turns use `slack:{channelId}:{threadTs}`.
@@ -146,22 +232,26 @@ export interface ToolRegistrationHookContext extends AgentPluginContext {
      * Do not parse as Slack unless the value starts with `slack:`.
      */
     conversationId?: string;
-    credentialSubject?: AgentPluginCredentialSubject;
-    /**
-     * Runtime-owned destination suitable for future autonomous dispatch. For
-     * Slack, this is the raw conversation channel, not a thread timestamp or
-     * assistant-context source channel.
-     */
-    destination?: Destination;
-    messageTs?: string;
-    requester?: Requester;
     state: AgentPluginState;
-    teamId?: string;
-    threadTs?: string;
     userText?: string;
 }
+interface SlackToolRegistrationContext extends BaseToolRegistrationHookContext, SlackInvocationContext {
+    slack: SlackToolRegistrationHookContext;
+}
+interface LocalToolRegistrationContext extends BaseToolRegistrationHookContext, LocalInvocationContext {
+    slack?: never;
+}
+export type ToolRegistrationHookContext = LocalToolRegistrationContext | SlackToolRegistrationContext;
 export type AgentPluginCredentialSubject = z.output<typeof agentPluginCredentialSubjectSchema>;
 export type Destination = z.output<typeof destinationSchema>;
+export type SlackDestination = Extract<Destination, {
+    platform: "slack";
+}>;
+export type LocalDestination = Extract<Destination, {
+    platform: "local";
+}>;
+/** Narrow a runtime destination to the Slack-specific address shape. */
+export declare function isSlackDestination(destination: Destination | undefined): destination is SlackDestination;
 export type DispatchOptions = z.output<typeof dispatchOptionsSchema>;
 export interface DispatchResult {
     id: string;
@@ -183,6 +273,21 @@ export interface AgentPluginState {
 export interface AgentPluginReadState {
     get<T = unknown>(key: string): Promise<T | undefined>;
 }
+export type AgentPluginConversationStatus = "active" | "completed" | "failed" | "hung" | "superseded";
+export interface AgentPluginConversationSummary {
+    channelName?: string;
+    conversationId: string;
+    displayTitle: string;
+    lastActivityAt: string;
+    lastUpdatedAt: string;
+    source?: "api" | "internal" | "local" | "plugin" | "scheduler" | "slack";
+    status: AgentPluginConversationStatus;
+}
+export interface AgentPluginConversations {
+    listRecent(options?: {
+        limit?: number;
+    }): Promise<AgentPluginConversationSummary[]>;
+}
 export interface HeartbeatHookContext extends AgentPluginContext {
     agent: {
         dispatch(options: DispatchOptions): Promise<DispatchResult>;
@@ -225,6 +330,7 @@ export interface PluginOperationalReport extends PluginOperationalReportContent
     pluginName: string;
 }
 export interface OperationalReportHookContext extends AgentPluginContext {
+    conversations: AgentPluginConversations;
     nowMs: number;
     state: AgentPluginReadState;
 }
@@ -481,6 +587,7 @@ export interface JuniorPluginManifest {
     configKeys?: string[];
     credentials?: JuniorPluginCredentials;
     description: string;
+    displayName: string;
     domains?: string[];
     envVars?: Record<string, JuniorPluginEnvVarDeclaration>;
     mcp?: JuniorPluginMcpConfig;

package/dist/index.js

@@ -2,28 +2,60 @@
 import { z } from "zod";
 var slackTeamIdSchema = z.string().regex(/^T[A-Z0-9]+$/);
 var slackConversationIdSchema = z.string().regex(/^(C|G|D)[A-Z0-9]+$/);
+var localConversationIdSchema = z.string().regex(/^local:[a-z0-9_-]+:[a-z0-9][a-z0-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 destinationSchema = z.object({
+var slackDestinationSchema = z.object({
   platform: z.literal("slack"),
   teamId: slackTeamIdSchema,
   channelId: slackConversationIdSchema
 }).strict();
+var localDestinationSchema = z.object({
+  platform: z.literal("local"),
+  conversationId: localConversationIdSchema
+}).strict();
+var destinationSchema = z.discriminatedUnion("platform", [
+  slackDestinationSchema,
+  localDestinationSchema
+]);
+var slackSourceSchema = z.object({
+  platform: z.literal("slack"),
+  teamId: slackTeamIdSchema,
+  channelId: slackConversationIdSchema,
+  messageTs: nonBlankStringSchema.optional(),
+  threadTs: nonBlankStringSchema.optional()
+}).strict();
+var localSourceSchema = localDestinationSchema;
+var sourceSchema = z.discriminatedUnion("platform", [
+  slackSourceSchema,
+  localSourceSchema
+]);
 var agentPluginCredentialSubjectSchema = z.object({
   type: z.literal("user"),
   userId: exactActorUserIdSchema,
   allowedWhen: z.literal("private-direct-conversation")
 }).strict();
-var requesterSchema = z.object({
-  platform: z.literal("slack"),
-  teamId: slackTeamIdSchema,
-  userId: exactActorUserIdSchema,
-  userName: nonBlankStringSchema.optional(),
+var requesterProfileSchema = {
+  email: nonBlankStringSchema.optional(),
   fullName: nonBlankStringSchema.optional(),
-  email: nonBlankStringSchema.optional()
+  userId: exactActorUserIdSchema,
+  userName: nonBlankStringSchema.optional()
+};
+var slackRequesterSchema = z.object({
+  ...requesterProfileSchema,
+  platform: z.literal("slack"),
+  teamId: slackTeamIdSchema
 }).strict();
+var localRequesterSchema = z.object({
+  ...requesterProfileSchema,
+  platform: z.literal("local")
+}).strict();
+var requesterSchema = z.discriminatedUnion("platform", [
+  slackRequesterSchema,
+  localRequesterSchema
+]);
 var dispatchMetadataSchema = z.record(z.string(), z.string()).superRefine((metadata, ctx) => {
   const entries = Object.entries(metadata);
   if (entries.length > 20) {
@@ -61,7 +93,7 @@ var dispatchMetadataSchema = z.record(z.string(), z.string()).superRefine((metad
 var dispatchOptionsSchema = z.object({
   idempotencyKey: nonBlankStringSchema.pipe(z.string().max(512)),
   credentialSubject: agentPluginCredentialSubjectSchema.optional(),
-  destination: destinationSchema,
+  destination: slackDestinationSchema,
   input: nonBlankStringSchema.pipe(z.string().max(32e3)),
   metadata: dispatchMetadataSchema.optional()
 }).strict();
@@ -71,6 +103,9 @@ var AgentPluginToolInputError = class extends Error {
     this.name = "AgentPluginToolInputError";
   }
 };
+function isSlackDestination(destination) {
+  return destination?.platform === "slack";
+}
 var agentPluginProviderNameSchema = z.string().regex(/^[a-z][a-z0-9-]*$/);
 var agentPluginGrantNameSchema = z.string().regex(/^[a-z][a-z0-9.-]*$/);
 var agentPluginGrantAccessSchema = z.union([
@@ -150,6 +185,11 @@ function defineJuniorPlugin(plugin) {
       `Junior plugin registration name "${name}" must be a lowercase plugin identifier.`
     );
   }
+  if (typeof manifest.displayName !== "string" || !manifest.displayName.trim()) {
+    throw new Error(
+      `Junior plugin "${name}" manifest.displayName is required.`
+    );
+  }
   if (typeof manifest.description !== "string" || !manifest.description.trim()) {
     throw new Error(
       `Junior plugin "${name}" manifest.description is required.`
@@ -178,5 +218,13 @@ export {
   defineJuniorPlugin,
   destinationSchema,
   dispatchOptionsSchema,
-  requesterSchema
+  isSlackDestination,
+  localDestinationSchema,
+  localRequesterSchema,
+  localSourceSchema,
+  requesterSchema,
+  slackDestinationSchema,
+  slackRequesterSchema,
+  slackSourceSchema,
+  sourceSchema
 };

package/package.json

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

package/src/index.ts

@@ -2,6 +2,9 @@ import { z } from "zod";
 
 const slackTeamIdSchema = z.string().regex(/^T[A-Z0-9]+$/);
 const slackConversationIdSchema = z.string().regex(/^(C|G|D)[A-Z0-9]+$/);
+const localConversationIdSchema = z
+  .string()
+  .regex(/^local:[a-z0-9_-]+:[a-z0-9][a-z0-9_-]*$/);
 const exactActorUserIdSchema = z
   .string()
   .min(1)
@@ -12,15 +15,49 @@ const nonBlankStringSchema = z
   .string()
   .refine((value) => value.trim().length > 0);
 
+/** Runtime-owned Slack address for routing future work or side effects. */
+export const slackDestinationSchema = z
+  .object({
+    platform: z.literal("slack"),
+    teamId: slackTeamIdSchema,
+    channelId: slackConversationIdSchema,
+  })
+  .strict();
+
+/** Runtime-owned local CLI conversation address. */
+export const localDestinationSchema = z
+  .object({
+    platform: z.literal("local"),
+    conversationId: localConversationIdSchema,
+  })
+  .strict();
+
 /** Runtime-owned provider-neutral address for routing future work or side effects. */
-export const destinationSchema = z
+export const destinationSchema = z.discriminatedUnion("platform", [
+  slackDestinationSchema,
+  localDestinationSchema,
+]);
+
+/** Runtime-owned Slack coordinates for the inbound invocation. */
+export const slackSourceSchema = z
   .object({
     platform: z.literal("slack"),
     teamId: slackTeamIdSchema,
     channelId: slackConversationIdSchema,
+    messageTs: nonBlankStringSchema.optional(),
+    threadTs: nonBlankStringSchema.optional(),
   })
   .strict();
 
+/** Runtime-owned local CLI coordinates for the inbound invocation. */
+export const localSourceSchema = localDestinationSchema;
+
+/** Runtime-owned provider-neutral coordinates for the inbound invocation. */
+export const sourceSchema = z.discriminatedUnion("platform", [
+  slackSourceSchema,
+  localSourceSchema,
+]);
+
 /** Stable user credential subject shape accepted from plugins. */
 export const agentPluginCredentialSubjectSchema = z
   .object({
@@ -30,18 +67,35 @@ export const agentPluginCredentialSubjectSchema = z
   })
   .strict();
 
-/** Runtime-provided requester identity visible to plugin hooks. */
-export const requesterSchema = z
+/** Shared exact actor profile fields for platform-scoped requesters. */
+const requesterProfileSchema = {
+  email: nonBlankStringSchema.optional(),
+  fullName: nonBlankStringSchema.optional(),
+  userId: exactActorUserIdSchema,
+  userName: nonBlankStringSchema.optional(),
+};
+
+export const slackRequesterSchema = z
   .object({
+    ...requesterProfileSchema,
     platform: z.literal("slack"),
     teamId: slackTeamIdSchema,
-    userId: exactActorUserIdSchema,
-    userName: nonBlankStringSchema.optional(),
-    fullName: nonBlankStringSchema.optional(),
-    email: nonBlankStringSchema.optional(),
   })
   .strict();
 
+export const localRequesterSchema = z
+  .object({
+    ...requesterProfileSchema,
+    platform: z.literal("local"),
+  })
+  .strict();
+
+/** Runtime-provided requester identity visible to plugin hooks. */
+export const requesterSchema = z.discriminatedUnion("platform", [
+  slackRequesterSchema,
+  localRequesterSchema,
+]);
+
 const dispatchMetadataSchema = z
   .record(z.string(), z.string())
   .superRefine((metadata, ctx) => {
@@ -84,13 +138,18 @@ export const dispatchOptionsSchema = z
   .object({
     idempotencyKey: nonBlankStringSchema.pipe(z.string().max(512)),
     credentialSubject: agentPluginCredentialSubjectSchema.optional(),
-    destination: destinationSchema,
+    destination: slackDestinationSchema,
     input: nonBlankStringSchema.pipe(z.string().max(32_000)),
     metadata: dispatchMetadataSchema.optional(),
   })
   .strict();
 
 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 interface AgentPluginMetadata {
   name: string;
@@ -125,6 +184,32 @@ export interface AgentPluginContext {
   plugin: AgentPluginMetadata;
 }
 
+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, if any. */
+  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, if any. */
+  destination?: LocalDestination;
+  requester?: LocalRequester;
+  /** Runtime-owned source where the invocation came from. */
+  source: LocalSource;
+}
+
+export type InvocationContext = LocalInvocationContext | SlackInvocationContext;
+
 export interface AgentPluginSandbox {
   juniorRoot: string;
   root: string;
@@ -190,23 +275,20 @@ export interface AgentPluginToolDefinition<TInput = unknown> {
   execute?: AgentPluginToolExecute<TInput>;
 }
 
-export interface ToolRegistrationHookContext extends AgentPluginContext {
+export interface SlackToolRegistrationHookContext {
   /**
-   * Capabilities of `channelId` — the raw conversation channel exposed to
-   * this plugin. Recomputed from `channelId`, not from `destination`.
+   * Capabilities of the source Slack conversation exposed to this plugin.
+   * Recomputed from `source.channelId`, not from `destination`.
    */
-  channelCapabilities?: {
+  channelCapabilities: {
     canAddReactions: boolean;
     canCreateCanvas: boolean;
     canPostToChannel: boolean;
   };
-  /**
-   * The raw Slack channel ID for this conversation — the DM or channel where
-   * this turn is happening, without any assistant-context-source override.
-   * Use this as the stable binding key for state scoped to a Slack conversation.
-   * `channelCapabilities` describes this channel.
-   */
-  channelId?: string;
+  credentialSubject?: AgentPluginCredentialSubject;
+}
+
+interface BaseToolRegistrationHookContext extends AgentPluginContext {
   /**
    * Opaque Junior conversation/session identity for this turn.
    * Interactive Slack turns use `slack:{channelId}:{threadTs}`.
@@ -214,27 +296,41 @@ export interface ToolRegistrationHookContext extends AgentPluginContext {
    * Do not parse as Slack unless the value starts with `slack:`.
    */
   conversationId?: string;
-  credentialSubject?: AgentPluginCredentialSubject;
-  /**
-   * Runtime-owned destination suitable for future autonomous dispatch. For
-   * Slack, this is the raw conversation channel, not a thread timestamp or
-   * assistant-context source channel.
-   */
-  destination?: Destination;
-  messageTs?: string;
-  requester?: Requester;
   state: AgentPluginState;
-  teamId?: string;
-  threadTs?: string;
   userText?: string;
 }
 
+interface SlackToolRegistrationContext
+  extends BaseToolRegistrationHookContext, SlackInvocationContext {
+  slack: SlackToolRegistrationHookContext;
+}
+
+interface LocalToolRegistrationContext
+  extends BaseToolRegistrationHookContext, LocalInvocationContext {
+  slack?: never;
+}
+
+export type ToolRegistrationHookContext =
+  | LocalToolRegistrationContext
+  | SlackToolRegistrationContext;
+
 export type AgentPluginCredentialSubject = z.output<
   typeof agentPluginCredentialSubjectSchema
 >;
 
 export type Destination = z.output<typeof destinationSchema>;
 
+export type SlackDestination = Extract<Destination, { platform: "slack" }>;
+
+export type LocalDestination = Extract<Destination, { platform: "local" }>;
+
+/** Narrow a runtime destination to the Slack-specific address shape. */
+export function isSlackDestination(
+  destination: Destination | undefined,
+): destination is SlackDestination {
+  return destination?.platform === "slack";
+}
+
 export type DispatchOptions = z.output<typeof dispatchOptionsSchema>;
 
 export interface DispatchResult {
@@ -271,6 +367,29 @@ export interface AgentPluginReadState {
   get<T = unknown>(key: string): Promise<T | undefined>;
 }
 
+export type AgentPluginConversationStatus =
+  | "active"
+  | "completed"
+  | "failed"
+  | "hung"
+  | "superseded";
+
+export interface AgentPluginConversationSummary {
+  channelName?: string;
+  conversationId: string;
+  displayTitle: string;
+  lastActivityAt: string;
+  lastUpdatedAt: string;
+  source?: "api" | "internal" | "local" | "plugin" | "scheduler" | "slack";
+  status: AgentPluginConversationStatus;
+}
+
+export interface AgentPluginConversations {
+  listRecent(options?: {
+    limit?: number;
+  }): Promise<AgentPluginConversationSummary[]>;
+}
+
 export interface HeartbeatHookContext extends AgentPluginContext {
   agent: {
     dispatch(options: DispatchOptions): Promise<DispatchResult>;
@@ -322,6 +441,7 @@ export interface PluginOperationalReport extends PluginOperationalReportContent
 }
 
 export interface OperationalReportHookContext extends AgentPluginContext {
+  conversations: AgentPluginConversations;
   nowMs: number;
   state: AgentPluginReadState;
 }
@@ -672,6 +792,7 @@ export interface JuniorPluginManifest {
   configKeys?: string[];
   credentials?: JuniorPluginCredentials;
   description: string;
+  displayName: string;
   domains?: string[];
   envVars?: Record<string, JuniorPluginEnvVarDeclaration>;
   mcp?: JuniorPluginMcpConfig;
@@ -726,6 +847,14 @@ export function defineJuniorPlugin(
       `Junior plugin registration name "${name}" must be a lowercase plugin identifier.`,
     );
   }
+  if (
+    typeof manifest.displayName !== "string" ||
+    !manifest.displayName.trim()
+  ) {
+    throw new Error(
+      `Junior plugin "${name}" manifest.displayName is required.`,
+    );
+  }
   if (
     typeof manifest.description !== "string" ||
     !manifest.description.trim()