@sentry/junior-plugin-api 0.197.0 → 0.199.0

package/dist/index.d.ts

@@ -1,19 +1,2021 @@
-export * from "./annotations";
-export * from "./code";
-export * from "./conversation-events";
-export * from "./schemas";
-export * from "./context";
-export * from "./state";
-export { definePromptContext, promptContextSchema, promptMessageSchema, type PromptContext, type PromptContextContribution, type PromptMessage, type SystemPromptContext, type UserPromptContribution, type UserPromptContext, } from "./prompt";
-export * from "./dispatch";
-export * from "./resource-events";
-export * from "./tasks";
-export * from "./tools";
-export * from "./operations";
-export * from "./credentials";
-export * from "./egress-policy";
-export * from "./hooks";
-export * from "./cli";
-export * from "./manifest";
-export * from "./registration";
-export * from "./user-pages";
+import { z, ZodTypeAny } from 'zod';
+import { Command } from 'commander';
+
+/** Exact non-blank actor user id that rejects the sentinel "unknown". */
+declare const actorUserIdSchema: z.ZodString;
+declare const nonBlankStringSchema: z.ZodString;
+/** Complete Slack Location associated with a Conversation. */
+declare const slackLocationSchema: z.ZodObject<{
+    id: z.ZodString;
+    provider: z.ZodLiteral<"slack">;
+    teamId: z.ZodString;
+    channelId: z.ZodString;
+    threadTs: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Complete Location types supported by Junior. */
+declare const locationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    provider: z.ZodLiteral<"slack">;
+    teamId: z.ZodString;
+    channelId: z.ZodString;
+    threadTs: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "provider">;
+/** Runtime platform names supported by plugin public contracts. */
+declare const platformSchema: z.ZodEnum<{
+    slack: "slack";
+    local: "local";
+}>;
+/** Runtime source visibility visible to plugins. */
+declare const sourceVisibilitySchema: z.ZodEnum<{
+    public: "public";
+    private: "private";
+}>;
+/** Provider-neutral visibility of a routed destination. */
+declare const destinationVisibilitySchema: z.ZodEnum<{
+    public: "public";
+    private: "private";
+}>;
+/** Runtime-owned Slack address for routing future work or side effects. */
+declare const slackDestinationSchema: z.ZodObject<{
+    platform: z.ZodLiteral<"slack">;
+    teamId: z.ZodString;
+    channelId: z.ZodString;
+}, z.core.$strict>;
+/** Runtime-owned local CLI conversation address. */
+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. */
+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 input Source. */
+declare const slackSourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"slack">;
+    teamId: z.ZodString;
+    channelId: z.ZodString;
+    visibility: z.ZodEnum<{
+        public: "public";
+        private: "private";
+    }>;
+    messageTs: z.ZodOptional<z.ZodString>;
+    threadTs: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Runtime-owned local CLI input Source. */
+declare const localSourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"local">;
+    visibility: z.ZodLiteral<"private">;
+    conversationId: z.ZodString;
+}, z.core.$strict>;
+/** Runtime-owned dashboard input Source. */
+declare const webSourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"web">;
+    visibility: z.ZodEnum<{
+        public: "public";
+        private: "private";
+    }>;
+    conversationId: z.ZodString;
+}, z.core.$strict>;
+/** Runtime-owned Resource event input Source. */
+declare const resourceEventSourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"resource_event">;
+    eventKey: z.ZodString;
+    eventType: z.ZodString;
+    identifier: z.ZodString;
+    namespace: z.ZodString;
+}, z.core.$strict>;
+/** Runtime-owned Scheduled task input Source. */
+declare const scheduledTaskSourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"scheduled_task">;
+}, z.core.$strict>;
+/** Runtime-owned Event task input Source. */
+declare const eventTaskSourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"event_task">;
+}, z.core.$strict>;
+/** Runtime-owned Plugin dispatch input Source. */
+declare const pluginDispatchSourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"plugin_dispatch">;
+}, z.core.$strict>;
+/** Runtime-owned Agent invocation input Source. */
+declare const agentInvocationSourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"agent_invocation">;
+}, z.core.$strict>;
+/** Runtime-owned input Source. Stored `platform` and Location fields normalize on read. */
+declare const sourceSchema: z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"slack">;
+    teamId: z.ZodString;
+    channelId: z.ZodString;
+    visibility: z.ZodEnum<{
+        public: "public";
+        private: "private";
+    }>;
+    messageTs: z.ZodOptional<z.ZodString>;
+    threadTs: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"local">;
+    visibility: z.ZodLiteral<"private">;
+    conversationId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"web">;
+    visibility: z.ZodEnum<{
+        public: "public";
+        private: "private";
+    }>;
+    conversationId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"resource_event">;
+    eventKey: z.ZodString;
+    eventType: z.ZodString;
+    identifier: z.ZodString;
+    namespace: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"scheduled_task">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"event_task">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"plugin_dispatch">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"agent_invocation">;
+}, z.core.$strict>], "kind">, unknown>;
+/** Stable user credential subject shape accepted from plugins. */
+declare const pluginCredentialSubjectSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"user">;
+    userId: z.ZodString;
+    allowedWhen: z.ZodLiteral<"private-direct-conversation">;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"user">;
+    userId: z.ZodString;
+    allowedWhen: z.ZodLiteral<"scheduled-task">;
+    taskId: z.ZodString;
+}, z.core.$strict>], "allowedWhen">;
+declare const slackActorSchema: 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>;
+declare const localActorSchema: 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>;
+declare const webActorSchema: z.ZodObject<{
+    platform: z.ZodLiteral<"web">;
+    email: z.ZodOptional<z.ZodString>;
+    fullName: z.ZodOptional<z.ZodString>;
+    userId: z.ZodString;
+    userName: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const systemActorSchema: z.ZodObject<{
+    platform: z.ZodLiteral<"system">;
+    name: z.ZodString;
+}, z.core.$strict>;
+/** Runtime-provided actor identity visible to plugin hooks. */
+declare const actorSchema: 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>, z.ZodObject<{
+    platform: z.ZodLiteral<"web">;
+    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<"system">;
+    name: z.ZodString;
+}, z.core.$strict>], "platform">;
+/** Core-owned provider account linked to a user when verified. */
+declare const identitySchema: z.ZodObject<{
+    displayName: z.ZodOptional<z.ZodString>;
+    handle: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    provider: z.ZodString;
+    providerSubjectId: z.ZodString;
+    providerTenantId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Core-owned person with every linked provider identity. */
+declare const userSchema: z.ZodObject<{
+    displayName: z.ZodOptional<z.ZodString>;
+    email: z.ZodString;
+    id: z.ZodString;
+    identities: z.ZodArray<z.ZodObject<{
+        displayName: z.ZodOptional<z.ZodString>;
+        handle: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        provider: z.ZodString;
+        providerSubjectId: z.ZodString;
+        providerTenantId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Compact destination-visible context explaining what produced a reply. */
+declare const replyAttributionSchema: z.ZodObject<{
+    label: z.ZodPipe<z.ZodString, z.ZodString>;
+    detail: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+/** Plugin dispatch request accepted by Junior core. */
+declare const dispatchOptionsSchema: z.ZodObject<{
+    idempotencyKey: z.ZodPipe<z.ZodString, z.ZodString>;
+    credentialSubject: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"user">;
+        userId: z.ZodString;
+        allowedWhen: z.ZodLiteral<"private-direct-conversation">;
+    }, 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;
+        channelId: z.ZodString;
+    }, z.core.$strict>;
+    destinationVisibility: z.ZodEnum<{
+        public: "public";
+        private: "private";
+    }>;
+    input: z.ZodPipe<z.ZodString, z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    replyAttribution: z.ZodOptional<z.ZodObject<{
+        label: z.ZodPipe<z.ZodString, z.ZodString>;
+        detail: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+
+/** Runtime platform name without source or destination coordinates. */
+type Platform = z.output<typeof platformSchema>;
+type Actor = z.output<typeof actorSchema>;
+type SlackActor = z.output<typeof slackActorSchema>;
+type LocalActor = z.output<typeof localActorSchema>;
+type WebActor = z.output<typeof webActorSchema>;
+type SystemActor = z.output<typeof systemActorSchema>;
+type Identity = z.output<typeof identitySchema>;
+type User = z.output<typeof userSchema>;
+type Source = z.output<typeof sourceSchema>;
+/** Validated Location associated with a Conversation. */
+type Location = z.output<typeof locationSchema>;
+/** Complete Slack Location associated with a Conversation. */
+type SlackLocation = z.output<typeof slackLocationSchema>;
+type SlackSource = Extract<Source, {
+    kind: "slack";
+}>;
+type LocalSource = Extract<Source, {
+    kind: "local";
+}>;
+type WebSource = Extract<Source, {
+    kind: "web";
+}>;
+type ResourceEventSource = Extract<Source, {
+    kind: "resource_event";
+}>;
+type ScheduledTaskSource = Extract<Source, {
+    kind: "scheduled_task";
+}>;
+type EventTaskSource = Extract<Source, {
+    kind: "event_task";
+}>;
+type PluginDispatchSource = Extract<Source, {
+    kind: "plugin_dispatch";
+}>;
+type AgentInvocationSource = Extract<Source, {
+    kind: "agent_invocation";
+}>;
+type SourceVisibility = z.output<typeof sourceVisibilitySchema>;
+type Destination = z.output<typeof destinationSchema>;
+type SlackDestination = Extract<Destination, {
+    platform: "slack";
+}>;
+type LocalDestination = Extract<Destination, {
+    platform: "local";
+}>;
+interface PluginMetadata {
+    name: string;
+}
+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;
+}
+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>;
+    }>;
+}
+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[][];
+    }>;
+}
+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;
+}
+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;
+}
+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;
+}
+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;
+}
+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;
+}
+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. */
+declare function createSlackSource(input: {
+    channelId: string;
+    messageTs?: string;
+    teamId: string;
+    threadTs?: string;
+    /** Runtime-normalized source visibility. */
+    visibility: SourceVisibility;
+}): SlackSource;
+/** Build a normalized local source from a local conversation id. */
+declare function createLocalSource(conversationId: string): LocalSource;
+/** Build a normalized web/dashboard source from a conversation id. */
+declare function createWebSource(conversationId: string, visibility?: SourceVisibility): WebSource;
+/** Build a normalized Resource event Source from one matched event. */
+declare function createResourceEventSource(input: {
+    eventKey: string;
+    eventType: string;
+    identifier: string;
+    namespace: string;
+}): ResourceEventSource;
+/** Return whether a source is private to a person or restricted group. */
+declare function isPrivateSource(source: Source): boolean;
+/** Return the stable source identity used for idempotency and attribution. */
+declare function getSourceKey(source: Source): string | undefined;
+/** Narrow a runtime destination to the Slack-specific address shape. */
+declare function isSlackDestination(destination: Destination | undefined): destination is SlackDestination;
+
+declare const resourceLinkAnnotationSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"resource_link">;
+    key: z.ZodString;
+    label: z.ZodString;
+    url: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        open: "open";
+        draft: "draft";
+        closed: "closed";
+        merged: "merged";
+        warning: "warning";
+    }>>;
+}, z.core.$strict>;
+/** Core-known annotation shapes that plugins may attach to a conversation. */
+declare const conversationAnnotationInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"resource_link">;
+    key: z.ZodString;
+    label: z.ZodString;
+    url: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        open: "open";
+        draft: "draft";
+        closed: "closed";
+        merged: "merged";
+        warning: "warning";
+    }>>;
+}, z.core.$strict>], "kind">;
+type ConversationAnnotationInput = z.output<typeof conversationAnnotationInputSchema>;
+type ConversationAnnotation = ConversationAnnotationInput & {
+    plugin: string;
+    createdAt: string;
+    updatedAt: string;
+};
+interface PluginAnnotations {
+    upsert(annotation: ConversationAnnotationInput): Promise<void>;
+    remove(kind: ConversationAnnotationInput["kind"], key: string): Promise<void>;
+    list(): Promise<ConversationAnnotation[]>;
+}
+interface PluginConversationAnnotations {
+    forConversation(conversationId: string): PluginAnnotations;
+}
+declare const conversationSidebarIconSchema: z.ZodEnum<{
+    "circle-dot": "circle-dot";
+    "circle-dashed": "circle-dashed";
+    "circle-x": "circle-x";
+    "git-merge": "git-merge";
+    "git-pull-request": "git-pull-request";
+    "triangle-alert": "triangle-alert";
+}>;
+declare const conversationSidebarAnnotationSchema: z.ZodObject<{
+    icon: z.ZodOptional<z.ZodEnum<{
+        "circle-dot": "circle-dot";
+        "circle-dashed": "circle-dashed";
+        "circle-x": "circle-x";
+        "git-merge": "git-merge";
+        "git-pull-request": "git-pull-request";
+        "triangle-alert": "triangle-alert";
+    }>>;
+    key: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strict>;
+type ConversationSidebarAnnotation = z.output<typeof conversationSidebarAnnotationSchema>;
+interface ConversationSidebarHookContext extends PluginContext {
+    /** Stored annotations owned by this plugin, keyed by candidate conversation. */
+    annotationsByConversationId: Record<string, ConversationAnnotation[]>;
+    conversationIds: string[];
+}
+interface ConversationSidebarResult {
+    /** Sidebar annotations in display order. Put the newest annotation first. */
+    annotationsByConversationId: Record<string, ConversationSidebarAnnotation[]>;
+}
+
+declare const codeChangeStateSchema: z.ZodEnum<{
+    open: "open";
+    closed: "closed";
+    merged: "merged";
+}>;
+type CodeChangeState = z.output<typeof codeChangeStateSchema>;
+declare const codeChangeInputSchema: z.ZodObject<{
+    closedAt: z.ZodOptional<z.ZodDate>;
+    conversationIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    mergedAt: z.ZodOptional<z.ZodDate>;
+    number: z.ZodNumber;
+    openedAt: z.ZodDate;
+    providerId: z.ZodString;
+    repository: z.ZodObject<{
+        name: z.ZodString;
+        providerId: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    state: z.ZodEnum<{
+        open: "open";
+        closed: "closed";
+        merged: "merged";
+    }>;
+    title: z.ZodOptional<z.ZodString>;
+    updatedAt: z.ZodDate;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type CodeChangeInput = z.input<typeof codeChangeInputSchema>;
+/** Write code changes from a plugin to Junior's code records. */
+interface CodeChangePublisher {
+    associateConversations(input: {
+        conversationIds: string[];
+        providerId: string;
+    }): Promise<void>;
+    record(input: CodeChangeInput): Promise<void>;
+}
+
+declare const conversationEventIconSchema: z.ZodEnum<{
+    check: "check";
+    key: "key";
+    link: "link";
+    warning: "warning";
+    activity: "activity";
+    brain: "brain";
+    calendar: "calendar";
+    database: "database";
+    info: "info";
+    sparkles: "sparkles";
+}>;
+/** Safe, core-rendered presentation for one plugin conversation event. */
+declare const conversationEventPresentationSchema: z.ZodObject<{
+    details: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        content: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        metadata: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        title: z.ZodString;
+    }, z.core.$strict>>>;
+    icon: z.ZodOptional<z.ZodEnum<{
+        check: "check";
+        key: "key";
+        link: "link";
+        warning: "warning";
+        activity: "activity";
+        brain: "brain";
+        calendar: "calendar";
+        database: "database";
+        info: "info";
+        sparkles: "sparkles";
+    }>>;
+    preview: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
+}, z.core.$strict>;
+type ConversationEventPresentation = z.output<typeof conversationEventPresentationSchema>;
+/** One validated plugin event value waiting for conversation-bound emission. */
+interface PluginConversationEventValue {
+    readonly data: Record<string, unknown>;
+    readonly definition: PluginConversationEventDefinition;
+}
+/** Registered schema and optional transcript presentation for one event version. */
+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. */
+interface DefinedConversationEvent<TInput> extends PluginConversationEventDefinition {
+    (data: TInput): PluginConversationEventValue;
+}
+/** Define one typed, versioned plugin-owned conversation event. */
+declare 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>>;
+/** Conversation-bound event writer supplied by Junior core. */
+interface PluginConversationEvents {
+    emit(event: PluginConversationEventValue): Promise<void>;
+}
+interface PluginConversationEventCostDay {
+    costUsd: number;
+    date: string;
+    events: number;
+}
+/** Read aggregate costs for events owned by the current plugin namespace. */
+interface PluginConversationEventStats {
+    costsByDay(input: {
+        days: 7 | 30 | 90;
+        eventName: string;
+    }): Promise<PluginConversationEventCostDay[]>;
+    costsByHour(input: {
+        eventName: string;
+        hours?: number;
+    }): Promise<PluginConversationEventCostDay[]>;
+}
+
+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>;
+}
+interface PluginReadState {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+}
+
+declare const promptMessageSchema: z.ZodObject<{
+    text: z.ZodString;
+}, z.core.$strict>;
+/** Small plugin-owned prompt text block rendered by Junior core. */
+type PromptMessage = z.output<typeof promptMessageSchema>;
+declare const promptContextSchema: z.ZodObject<{
+    kind: z.ZodString;
+    version: z.ZodNumber;
+    content: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+/** Structured plugin context retained alongside its model-visible rendering. */
+type PromptContext = z.output<typeof promptContextSchema>;
+/** Runtime contribution produced from one validated plugin context value. */
+interface PromptContextContribution {
+    context: PromptContext;
+    renderPrompt(): string;
+}
+/** Define one typed, versioned plugin context contribution. */
+declare function definePromptContext<TSchema extends z.ZodType<Record<string, unknown>>>(definition: {
+    kind: string;
+    version: number;
+    schema: TSchema;
+    renderPrompt(content: z.output<TSchema>): string;
+}): (content: z.input<TSchema>) => PromptContextContribution;
+/** One request-scoped plugin contribution to the model-visible user prompt. */
+type UserPromptContribution = PromptMessage | PromptContextContribution;
+/** Stable platform context for plugin system prompt guidance. */
+type SystemPromptContext = Pick<PluginContext, "db" | "log" | "plugin"> & {
+    platform: Platform;
+};
+/** Runtime facts available while building plugin user prompt context. */
+type UserPromptContext = Pick<PluginContext, "db" | "log" | "plugin"> & {
+    conversationId?: string;
+    destination: Destination;
+    embedder: PluginEmbedder;
+    /** Conversation-bound event writer when the prompt belongs to a durable turn. */
+    events?: PluginConversationEvents;
+    model: PluginModel;
+    /** Location associated with this Conversation. */
+    locationId?: string;
+    actor?: Actor;
+    source: Source;
+    state: PluginState;
+    text: string;
+    users: {
+        /** Resolve the current Actor's Identity and User. */
+        resolveActor(): Promise<{
+            identity: Identity;
+            user?: User;
+        } | undefined>;
+    };
+};
+
+type DestinationVisibility = z.output<typeof destinationVisibilitySchema>;
+type DispatchOptions = z.output<typeof dispatchOptionsSchema>;
+/** Compact destination-visible context explaining what produced a reply. */
+type ReplyAttribution = z.output<typeof replyAttributionSchema>;
+interface DispatchResult {
+    id: string;
+    status: "created" | "already_exists";
+}
+interface Dispatch {
+    errorMessage?: string;
+    id: string;
+    resultMessageTs?: string;
+    status: "pending" | "running" | "awaiting_resume" | "completed" | "failed" | "blocked";
+}
+
+declare const RESOURCE_EVENT_SUMMARY_MAX_LENGTH = 4000;
+declare const RESOURCE_EVENT_TEXT_MAX_LENGTH = 8000;
+declare const RESOURCE_EVENT_DATA_MAX_KEYS = 32;
+declare const RESOURCE_EVENT_DATA_MAX_JSON_BYTES = 4000;
+declare const RESOURCE_EVENT_GUIDANCE_MAX_LENGTH = 1000;
+/** Small trusted data from the plugin. The agent should not look these up again. */
+declare const resourceEventDataSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/** Canonical dotted event type published and selected across plugins. */
+declare const resourceEventTypeSchema: z.ZodString;
+declare const resourceTypeSchema: z.ZodString;
+/** One exact value a watch or event task may require on trusted event data. */
+declare const resourceEventMatchFieldSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+    }>;
+    description: z.ZodString;
+    enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+declare const resourceEventMatchFieldsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    kind: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+    }>;
+    description: z.ZodString;
+    enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>>;
+/** Exact trusted values required before a watch or event task runs. */
+declare const resourceEventMatchSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>]>>;
+type ResourceEventMatch = z.output<typeof resourceEventMatchSchema>;
+type ResourceEventMatchFields = z.output<typeof resourceEventMatchFieldsSchema>;
+/** Stable JSON for one match object. List order does not matter. */
+declare function stableResourceEventMatchKey(match: ResourceEventMatch | undefined): string;
+/** Return whether trusted event data matches one exact match object. */
+declare function resourceEventMatches(match: ResourceEventMatch | undefined, data: ResourceEventData | undefined): boolean;
+declare const pluginResourceEventTypeSchema: z.ZodObject<{
+    type: z.ZodString;
+    supportedEvents: z.ZodArray<z.ZodString>;
+    suggestedEvents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    matchFields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        kind: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+        }>;
+        description: z.ZodString;
+        enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    guidance: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+declare const pluginResourceEventsSchema: z.ZodObject<{
+    resourceTypes: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        supportedEvents: z.ZodArray<z.ZodString>;
+        suggestedEvents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        matchFields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            kind: z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+            }>;
+            description: z.ZodString;
+            enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>>;
+        guidance: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>;
+    isEnabled: z.ZodOptional<z.ZodFunction<z.ZodTuple<readonly [], null>, z.ZodBoolean>>;
+    normalizeIdentifier: z.ZodOptional<z.ZodFunction<z.ZodTuple<readonly [z.ZodString], null>, z.ZodString>>;
+}, z.core.$strict>;
+type PluginResourceEventType = z.output<typeof pluginResourceEventTypeSchema>;
+type PluginResourceEvents = z.output<typeof pluginResourceEventsSchema>;
+/** Apply a plugin's identifier convention at resource-event boundaries. */
+declare function normalizeResourceEventIdentifier(registration: Pick<PluginResourceEvents, "normalizeIdentifier"> | undefined, identifier: string): string;
+declare const subscribableResourceSchema: z.ZodObject<{
+    identifier: z.ZodString;
+    label: z.ZodString;
+    namespace: z.ZodString;
+    suggestedEvents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    supportedEvents: z.ZodArray<z.ZodString>;
+    type: z.ZodString;
+}, z.core.$strict>;
+type SubscribableResource = z.output<typeof subscribableResourceSchema>;
+/** Result returned after a temporary resource subscription is created. */
+declare const resourceEventSubscriptionResultSchema: z.ZodObject<{
+    events: z.ZodArray<z.ZodString>;
+    id: z.ZodString;
+}, z.core.$strict>;
+type ResourceEventSubscriptionResult = z.output<typeof resourceEventSubscriptionResultSchema>;
+declare const resourceEventInputSchema: z.ZodObject<{
+    eventKey: z.ZodString;
+    eventType: z.ZodString;
+    identifier: z.ZodString;
+    occurredAtMs: z.ZodNumber;
+    terminal: z.ZodOptional<z.ZodBoolean>;
+    trustedSummary: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    untrustedText: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+}, z.core.$strict>;
+type ResourceEventData = z.output<typeof resourceEventDataSchema>;
+type ResourceEventInput = z.output<typeof resourceEventInputSchema>;
+declare const resourceEventSchema: z.ZodObject<{
+    eventKey: z.ZodString;
+    eventType: z.ZodString;
+    identifier: z.ZodString;
+    occurredAtMs: z.ZodNumber;
+    terminal: z.ZodOptional<z.ZodBoolean>;
+    trustedSummary: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    untrustedText: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    namespace: z.ZodString;
+}, z.core.$strict>;
+type ResourceEvent = z.output<typeof resourceEventSchema>;
+interface ResourceEventPublisher {
+    /** Publish one normalized event under the owning plugin's namespace. */
+    publish(event: ResourceEventInput): Promise<void>;
+    /**
+     * Return match keys used by active watches or event tasks for these
+     * identifiers and event types. Plugins use this to load optional trusted
+     * data only when a filter needs it.
+     */
+    neededMatchKeys?(input: {
+        eventTypes: string[];
+        identifiers: string[];
+    }): Promise<string[]>;
+}
+
+/**
+ * Public plugin background-task contracts.
+ *
+ * Plugins register small task handlers. Junior core owns scheduling, delivery,
+ * retries, and the bounded run projection.
+ */
+
+/**
+ * Runtime-owned provenance for a transcript message: whether it is a durable
+ * instruction or ambient context, plus the actor identity when known. Missing
+ * provenance on an entry means unattributed context.
+ */
+declare const pluginRunTranscriptProvenanceSchema: z.ZodObject<{
+    authority: z.ZodEnum<{
+        instruction: "instruction";
+        context: "context";
+    }>;
+    actor: 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>, z.ZodObject<{
+        platform: z.ZodLiteral<"web">;
+        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<"system">;
+        name: z.ZodString;
+    }, z.core.$strict>], "platform">>;
+}, z.core.$strict>;
+/** One normalized transcript entry from the completed run exposed to plugin tasks. */
+declare const pluginRunTranscriptEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"message">;
+    role: z.ZodEnum<{
+        user: "user";
+        assistant: "assistant";
+    }>;
+    text: z.ZodString;
+    provenance: z.ZodOptional<z.ZodObject<{
+        authority: z.ZodEnum<{
+            instruction: "instruction";
+            context: "context";
+        }>;
+        actor: 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>, z.ZodObject<{
+            platform: z.ZodLiteral<"web">;
+            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<"system">;
+            name: z.ZodString;
+        }, z.core.$strict>], "platform">>;
+    }, z.core.$strict>>;
+    isRunActor: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"toolResult">;
+    toolName: z.ZodString;
+    isError: z.ZodBoolean;
+    text: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "type">;
+type PluginRunTranscriptProvenance = z.output<typeof pluginRunTranscriptProvenanceSchema>;
+/** Runtime-owned completed-run projection exposed to plugin tasks. */
+declare const pluginRunContextSchema: z.ZodObject<{
+    actorUserId: z.ZodOptional<z.ZodString>;
+    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">;
+    locationId: z.ZodOptional<z.ZodString>;
+    actors: z.ZodArray<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>, z.ZodObject<{
+        platform: z.ZodLiteral<"web">;
+        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<"system">;
+        name: z.ZodString;
+    }, z.core.$strict>], "platform">>;
+    actor: 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>, z.ZodObject<{
+        platform: z.ZodLiteral<"web">;
+        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<"system">;
+        name: z.ZodString;
+    }, z.core.$strict>], "platform">>;
+    runId: z.ZodString;
+    source: z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"slack">;
+        teamId: z.ZodString;
+        channelId: z.ZodString;
+        visibility: z.ZodEnum<{
+            public: "public";
+            private: "private";
+        }>;
+        messageTs: z.ZodOptional<z.ZodString>;
+        threadTs: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"local">;
+        visibility: z.ZodLiteral<"private">;
+        conversationId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"web">;
+        visibility: z.ZodEnum<{
+            public: "public";
+            private: "private";
+        }>;
+        conversationId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"resource_event">;
+        eventKey: z.ZodString;
+        eventType: z.ZodString;
+        identifier: z.ZodString;
+        namespace: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"scheduled_task">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"event_task">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"plugin_dispatch">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"agent_invocation">;
+    }, z.core.$strict>], "kind">, unknown>;
+    transcript: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"message">;
+        role: z.ZodEnum<{
+            user: "user";
+            assistant: "assistant";
+        }>;
+        text: z.ZodString;
+        provenance: z.ZodOptional<z.ZodObject<{
+            authority: z.ZodEnum<{
+                instruction: "instruction";
+                context: "context";
+            }>;
+            actor: 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>, z.ZodObject<{
+                platform: z.ZodLiteral<"web">;
+                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<"system">;
+                name: z.ZodString;
+            }, z.core.$strict>], "platform">>;
+        }, z.core.$strict>>;
+        isRunActor: z.ZodOptional<z.ZodBoolean>;
+    }, 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>;
+type PluginRunTranscriptEntry = z.output<typeof pluginRunTranscriptEntrySchema>;
+type PluginRunContext = z.output<typeof pluginRunContextSchema>;
+/** Runtime context passed to a plugin-owned background task. */
+interface PluginTaskContext extends PluginContext {
+    embedder: PluginEmbedder;
+    events: PluginConversationEvents;
+    id: string;
+    model: PluginModel;
+    name: string;
+    run: {
+        load(): Promise<PluginRunContext>;
+    };
+    state: PluginState;
+}
+/** Plugin task handler registered by name in a plugin manifest module. */
+interface PluginTaskDefinition {
+    run(ctx: PluginTaskContext): Promise<void> | void;
+}
+/** Task handlers keyed by the plugin-owned task name. */
+type PluginTasks = Record<string, PluginTaskDefinition>;
+
+declare const pluginGrantAccessSchema: z.ZodUnion<readonly [z.ZodLiteral<"read">, z.ZodLiteral<"write">]>;
+/** Runtime schema for provider authorization a plugin may request. */
+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. */
+declare const pluginProviderAccountSchema: z.ZodObject<{
+    displayName: z.ZodOptional<z.ZodString>;
+    handle: z.ZodOptional<z.ZodString>;
+    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. */
+declare const pluginStoredTokensSchema: z.ZodObject<{
+    account: z.ZodOptional<z.ZodObject<{
+        displayName: z.ZodOptional<z.ZodString>;
+        handle: z.ZodOptional<z.ZodString>;
+        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. */
+declare const pluginGrantSchema: z.ZodObject<{
+    access: z.ZodUnion<readonly [z.ZodLiteral<"read">, z.ZodLiteral<"write">]>;
+    leaseScope: z.ZodOptional<z.ZodString>;
+    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. */
+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. */
+declare const pluginCredentialLeaseSchema: z.ZodObject<{
+    account: z.ZodOptional<z.ZodObject<{
+        displayName: z.ZodOptional<z.ZodString>;
+        handle: z.ZodOptional<z.ZodString>;
+        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. */
+declare const pluginCredentialResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    lease: z.ZodObject<{
+        account: z.ZodOptional<z.ZodObject<{
+            displayName: z.ZodOptional<z.ZodString>;
+            handle: z.ZodOptional<z.ZodString>;
+            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">;
+type PluginCredentialSubject = z.output<typeof pluginCredentialSubjectSchema>;
+type PluginGrantAccess = z.output<typeof pluginGrantAccessSchema>;
+/** Provider authorization Junior can start when a plugin-owned grant is missing. */
+type PluginAuthorization = z.output<typeof pluginAuthorizationSchema>;
+/** Interrupt sandbox egress so Junior can start provider authorization. */
+declare class EgressAuthRequired extends Error {
+    authorization?: PluginAuthorization;
+    constructor(message: string, options?: {
+        authorization?: PluginAuthorization;
+        cause?: unknown;
+    });
+}
+/** Deny provider egress before Junior issues credentials for a disallowed operation. */
+declare class EgressPolicyDenied extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Provider account identity resolved by a plugin OAuth hook. */
+type PluginProviderAccount = z.output<typeof pluginProviderAccountSchema>;
+/** Plugin-defined grant required before Junior can forward one outbound request. */
+type PluginGrant = z.output<typeof pluginGrantSchema>;
+/** Request details available while selecting the grant for sandbox egress. */
+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;
+}
+interface EgressHookContext extends PluginContext {
+    request: PluginEgressRequest;
+}
+interface PluginEgressResponse {
+    /** Snapshot of upstream response headers; mutations do not affect pass-through. */
+    headers: Headers;
+    readText(maxBytes: number): Promise<string | undefined>;
+    status: number;
+}
+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. */
+type PluginCredentialHeaderTransform = z.output<typeof pluginCredentialHeaderTransformSchema>;
+/** Short-lived credential headers issued by a plugin for a selected grant. */
+type PluginCredentialLease = z.output<typeof pluginCredentialLeaseSchema>;
+type PluginCredentialResult = z.output<typeof pluginCredentialResultSchema>;
+type PluginCredentialActor = {
+    platform: "system";
+    name: string;
+} | {
+    type: "user";
+    userId: string;
+};
+interface PluginResolvedCredentialUser {
+    type: "user";
+    userId: string;
+}
+type PluginStoredTokens = z.output<typeof pluginStoredTokensSchema>;
+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;
+}
+interface PluginTokenStore {
+    credentialSubject?: PluginUserTokenSlot;
+    currentUser?: PluginUserTokenSlot;
+}
+interface ResolveOAuthAccountHookContext extends PluginContext {
+    tokens: PluginStoredTokens;
+}
+interface IssueCredentialHookContext extends PluginContext {
+    actor: PluginCredentialActor;
+    credentialSubject?: PluginResolvedCredentialUser;
+    grant: PluginGrant;
+    tokens: PluginTokenStore;
+}
+
+interface HeartbeatHookContext extends PluginContext {
+    agent: {
+        dispatch(options: DispatchOptions): Promise<DispatchResult>;
+        get(id: string): Promise<Dispatch | undefined>;
+    };
+    nowMs: number;
+    state: PluginState;
+}
+interface HeartbeatResult {
+    dispatchCount?: number;
+}
+interface UnfinishedWorkHookContext extends PluginContext {
+    /** Bounded conversation candidates selected by the host. */
+    conversationIds: string[];
+}
+interface UnfinishedWorkResult {
+    /** Candidate conversations that have plugin-owned work to finish. */
+    conversationIds: string[];
+    /**
+     * Candidate conversations that have any associated plugin-owned work,
+     * finished or unfinished. Omit when the plugin cannot distinguish assignment.
+     *
+     * The host uses this with unfinished work and finish times to set feed
+     * `isPriority`. Finished assigned work stays out of Priority unless the
+     * conversation has activity after the finish time.
+     */
+    assignedConversationIds?: string[];
+    /**
+     * Latest time when all known work finished, keyed by conversation id.
+     * ISO-8601 timestamps. Used with conversation activity to decide whether
+     * finished work still belongs in Priority.
+     */
+    finishedWorkAtByConversationId?: Record<string, string>;
+}
+type PluginOperationalTone = "danger" | "good" | "neutral" | "warning";
+interface PluginOperationalMetric {
+    label: string;
+    tone?: PluginOperationalTone;
+    value: string;
+}
+interface PluginOperationalField {
+    key: string;
+    label: string;
+}
+interface PluginOperationalRecord {
+    id: string;
+    tone?: PluginOperationalTone;
+    values: Record<string, string>;
+}
+interface PluginOperationalRecordSet {
+    fields?: PluginOperationalField[];
+    emptyText?: string;
+    records?: PluginOperationalRecord[];
+    title: string;
+}
+interface PluginOperationalChartSeries {
+    format?: "usd";
+    key: string;
+    label: string;
+    tone?: PluginOperationalTone;
+}
+interface PluginOperationalChartCategory {
+    id: string;
+    label: string;
+    values: Record<string, number>;
+}
+interface PluginOperationalBarChartWidget {
+    categories: PluginOperationalChartCategory[];
+    description?: string;
+    emptyText?: string;
+    id: string;
+    series: PluginOperationalChartSeries[];
+    timeRangeDays?: Array<1 | 7 | 30 | 90>;
+    title: string;
+    type: "bar_chart";
+}
+interface PluginOperationalReportContent {
+    generatedAt?: string;
+    metrics?: PluginOperationalMetric[];
+    recordSets?: PluginOperationalRecordSet[];
+    title?: string;
+    widgets?: PluginOperationalBarChartWidget[];
+}
+interface PluginOperationalReport extends PluginOperationalReportContent {
+    pluginName: string;
+}
+interface OperationalReportHookContext extends PluginContext {
+    eventStats: PluginConversationEventStats;
+    nowMs: number;
+    state: PluginReadState;
+}
+/** Read-only context for one person-scoped plugin report on a profile page. */
+interface ProfileReportHookContext extends PluginContext {
+    nowMs: number;
+    state: PluginReadState;
+    /** Canonical user for the profile being viewed. */
+    subject: User;
+    /** Canonical user for the authenticated viewer. */
+    viewer: User;
+}
+type PluginRouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "ALL";
+type PluginRouteHandler = {
+    bivarianceHack(request: Request): Promise<Response> | Response;
+}["bivarianceHack"];
+interface PluginRoute {
+    handler: PluginRouteHandler;
+    method?: PluginRouteMethod | PluginRouteMethod[];
+    path: string;
+}
+/** Fetch-compatible plugin HTTP app mounted by Junior. */
+type PluginRouteApp = {
+    fetch(request: Request, context?: PluginApiRouteRequestContext): Promise<Response> | Response;
+};
+interface RouteRegistrationHookContext extends PluginContext {
+    annotations: PluginConversationAnnotations;
+    /** Provider-neutral write boundary for Junior's native code index. */
+    codeChanges: CodeChangePublisher;
+    /** Core-owned delivery boundary for provider webhook events. */
+    resourceEvents: ResourceEventPublisher;
+}
+interface ApiRouteRegistrationHookContext extends PluginContext {
+    eventStats: PluginConversationEventStats;
+    users: {
+        /** Resolve or create the canonical user for one verified email. */
+        resolve(email: string): Promise<User | undefined>;
+    };
+}
+/** Per-request context Junior passes to authenticated plugin product API routes. */
+declare const pluginApiRouteRequestContextSchema: z.ZodObject<{
+    auth: z.ZodObject<{
+        user: z.ZodObject<{
+            email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            emailVerified: z.ZodOptional<z.ZodBoolean>;
+            name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    pluginName: z.ZodString;
+}, z.core.$strict>;
+type PluginApiRouteRequestContext = z.output<typeof pluginApiRouteRequestContextSchema>;
+interface SlackConversationLink {
+    url: string;
+}
+interface SlackConversationLinkHookContext extends PluginContext {
+    conversationId: string;
+}
+
+interface PluginEnv {
+    get(key: string): string | undefined;
+    set(key: string, value: string): void;
+}
+interface PluginDecision {
+    deny(message: string): void;
+    replaceInput(input: Record<string, unknown>): void;
+}
+/** Thrown when a plugin tool rejects invalid model or user input. */
+declare class PluginToolInputError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+interface PluginSandbox {
+    juniorRoot: string;
+    root: string;
+    readFile(path: string): Promise<Uint8Array | null>;
+    run(input: {
+        args?: string[];
+        cmd: string;
+        cwd?: string;
+        env?: Record<string, string>;
+        signal?: AbortSignal;
+        sudo?: boolean;
+    }): Promise<{
+        exitCode: number;
+        stderr: string;
+        stdout: string;
+    }>;
+    writeFile(input: {
+        content: string | Uint8Array;
+        mode?: number;
+        path: string;
+    }): Promise<void>;
+}
+interface PluginEgress {
+    /**
+     * Fetch a provider URL with host-owned credentials.
+     *
+     * The runtime selects and injects credentials for `provider`; plugin code
+     * owns the request shape and response handling. `operation` names the
+     * provider action for grant selection and diagnostics.
+     */
+    fetch(input: {
+        operation: string;
+        provider: string;
+        request: Request;
+    }): Promise<Response>;
+}
+declare const pluginToolContentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"image">;
+    data: z.ZodString;
+    mimeType: z.ZodString;
+}, z.core.$strict>], "type">;
+/** Model-visible content returned by a plugin tool. */
+type PluginToolContent = z.output<typeof pluginToolContentSchema>;
+/** Pi-native projection with model-facing content and canonical runtime details. */
+interface PluginToolOutputEnvelope<TDetails = unknown> {
+    content: PluginToolContent[];
+    details: TDetails;
+}
+type PluginMcpContent = PluginToolContent;
+/** Successful raw provider result returned to a plugin-owned wrapper tool. */
+type PluginMcpToolSuccess = {
+    content: PluginMcpContent[];
+    status: "success";
+    structuredContent?: unknown;
+};
+/** Handled provider authorization pause with no provider result to consume. */
+type PluginMcpAuthorizationPending = {
+    status: "authorization_pending";
+};
+/** Definitive provider rejection; transport and session failures still throw. */
+type PluginMcpToolError = {
+    message: string;
+    status: "error";
+};
+type PluginMcpToolResult = PluginMcpAuthorizationPending | PluginMcpToolError | PluginMcpToolSuccess;
+/** Access to this plugin's hosted MCP provider without exposing credentials. */
+interface PluginMcp {
+    /**
+     * Call a provider tool declared in `wrappedTools`.
+     *
+     * The host activates the provider when needed. Successful calls return the
+     * provider's original content, provider rejections return an error result,
+     * and authorization pauses return no tool content. Transport failures throw.
+     */
+    callTool(input: {
+        arguments?: Record<string, unknown>;
+        name: string;
+        toolCallId?: string;
+    }): Promise<PluginMcpToolResult>;
+    /**
+     * Activate the provider before wrapper-owned state changes.
+     *
+     * Ordinary wrappers can call `callTool` directly. Durable mutation wrappers
+     * may prepare first so an initial authorization pause happens before they
+     * record pending work.
+     */
+    prepare(): Promise<"authorization_pending" | "ready">;
+}
+/**
+ * Provider-owned, repeatable repository preparation for a Workspace Sandbox.
+ * Implementations should refresh complete checkouts and replace missing or
+ * partial ones.
+ */
+interface WorkspacePrepareHookContext extends PluginContext {
+    repos: Array<{
+        path: string;
+        repo: string;
+    }>;
+    sandbox: PluginSandbox;
+}
+interface SandboxPrepareHookContext extends PluginContext {
+    actor?: Actor;
+    sandbox: PluginSandbox;
+}
+interface BeforeToolExecuteHookContext extends PluginContext {
+    decision: PluginDecision;
+    env: PluginEnv;
+    actor?: Actor;
+    /** All actors who contributed instructions to the run so far; see `multi-actor-runs.md`. */
+    actors?: Actor[];
+    tool: {
+        input: Record<string, unknown>;
+        name: string;
+    };
+    /**
+     * Resolve the current actor's stored identity and linked user.
+     * Same contract as tool registration; used for commit attribution.
+     */
+    users: {
+        resolveActor(): Promise<{
+            identity: Identity;
+            user?: User;
+        } | undefined>;
+    };
+}
+/**
+ * Context for post-success MCP tool processing.
+ *
+ * Runs after a hosted MCP tool succeeds on the model-facing path. Use for
+ * junior-owned side effects such as conversation annotations without replacing
+ * the provider tool contract.
+ */
+interface AfterMcpToolHookContext extends PluginContext {
+    /**
+     * Opaque Junior conversation/session identity for this turn.
+     * Interactive Slack turns use `slack:{channelId}:{threadTs}`.
+     */
+    conversationId?: string;
+    annotations?: PluginAnnotations;
+    result: {
+        structuredContent?: unknown;
+    };
+    tool: {
+        arguments: Record<string, unknown>;
+        /** Provider-local MCP tool name, for example `save_issue`. */
+        name: string;
+    };
+}
+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;
+    /** Abort when the owning agent tool call is cancelled or times out. */
+    signal?: AbortSignal;
+    /** Stable runtime tool-call id; durable create tools should derive idempotency keys from it. */
+    toolCallId?: string;
+}
+declare const pluginToolContinuationSchema: z.ZodObject<{
+    arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Shared optional fields for canonical plugin tool outputs. */
+declare const pluginToolOutputSchema: z.ZodObject<{
+    target: z.ZodOptional<z.ZodString>;
+    truncated: z.ZodOptional<z.ZodBoolean>;
+    continuation: z.ZodOptional<z.ZodObject<{
+        arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$loose>;
+type PluginToolOutput = z.output<typeof pluginToolOutputSchema>;
+type PluginToolExecute<TInput = unknown, TOutput = unknown> = {
+    bivarianceHack(input: TInput, options: PluginToolExecuteOptions): Promise<TOutput> | TOutput;
+}["bivarianceHack"];
+/**
+ * Tool-declared approval mode.
+ *
+ * `auto` delegates to core policy, `review` enters Guardian review, and
+ * `approve` permits execution without review. Plugin tool helpers normalize
+ * omission to `auto`.
+ *
+ * Core resolves the effective mode immediately before execution.
+ */
+declare const toolApprovalModeSchema: z.ZodEnum<{
+    auto: "auto";
+    review: "review";
+    approve: "approve";
+}>;
+type ToolApprovalMode = z.output<typeof toolApprovalModeSchema>;
+/**
+ * Reviewer signals describing a tool's side-effect behavior.
+ *
+ * These hints follow the MCP tool annotation contract. Guardian may use
+ * them as signals, but they never grant authority or override deterministic
+ * authorization.
+ */
+interface ToolAnnotations {
+    [key: string]: unknown;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+    readOnlyHint?: boolean;
+    title?: string;
+}
+declare const REQUIRED_TOOL_ANNOTATION_KEYS: readonly ["destructiveHint", "idempotentHint", "openWorldHint", "readOnlyHint"];
+type RequiredToolAnnotationKey = (typeof REQUIRED_TOOL_ANNOTATION_KEYS)[number];
+/** Return behavioral annotation keys that a tool did not declare. */
+declare function missingToolAnnotationKeys(annotations: ToolAnnotations | undefined): RequiredToolAnnotationKey[];
+/**
+ * Canonical approval metadata declared by core and plugin tools.
+ */
+interface ToolApprovalMetadata<TInput = unknown> {
+    /** Optional declared approval mode; the owning tool boundary selects defaults. */
+    approvalMode?: ToolApprovalMode;
+    annotations?: ToolAnnotations;
+    /**
+     * Describe the reviewed semantic action for the review request.
+     *
+     * Core owns authoritative tool, actor, source, destination, conversation,
+     * credential, and input data. This description adds domain-specific context
+     * only and is never an authorization grant.
+     */
+    describeProposal?(input: TInput): string;
+}
+interface PluginToolDefinition<TInput = unknown, TOutput = unknown, TExecuteOutput = TOutput> extends ToolApprovalMetadata<TInput> {
+    description: string;
+    executionMode?: unknown;
+    inputSchema: unknown;
+    outputSchema?: unknown;
+    /**
+     * Select result fields that are safe to retain in private traces.
+     * Returning `undefined` suppresses private result capture.
+     */
+    privateTraceResult?(result: TOutput): unknown;
+    prepareArguments?: (args: unknown) => TInput;
+    /**
+     * @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, TExecuteOutput>;
+}
+type ZodPluginToolDefinition<TInputSchema extends ZodTypeAny, TOutputSchema extends ZodTypeAny, TExecuteResult extends z.input<TOutputSchema> | PluginToolOutputEnvelope<z.input<TOutputSchema>>> = Omit<PluginToolDefinition<z.output<TInputSchema>, z.output<TOutputSchema>>, "inputSchema" | "outputSchema" | "prepareArguments" | "execute"> & {
+    inputSchema: TInputSchema;
+    outputSchema: TOutputSchema;
+    prepareArguments?: (args: unknown) => z.input<TInputSchema>;
+    execute?: (input: z.output<TInputSchema>, options: PluginToolExecuteOptions) => Promise<TExecuteResult> | TExecuteResult;
+};
+type ParsedPluginToolExecuteResult<TOutputSchema extends ZodTypeAny, TResult> = TResult extends PluginToolOutputEnvelope<unknown> ? PluginToolOutputEnvelope<z.output<TOutputSchema>> : z.output<TOutputSchema>;
+/** Define a plugin tool with Zod input parsing and validated structured results. */
+declare function zodTool<TInputSchema extends ZodTypeAny, TOutputSchema extends ZodTypeAny, TExecuteResult extends z.input<TOutputSchema> | PluginToolOutputEnvelope<z.input<TOutputSchema>>>(definition: ZodPluginToolDefinition<TInputSchema, TOutputSchema, TExecuteResult>): PluginToolDefinition<z.output<TInputSchema>, z.output<TOutputSchema>, ParsedPluginToolExecuteResult<TOutputSchema, TExecuteResult>>;
+/** Define a plugin tool with Zod input parsing and the structured result contract. */
+declare function definePluginTool<TInputSchema extends ZodTypeAny, TOutputSchema extends ZodTypeAny, TExecuteResult extends z.input<TOutputSchema> | PluginToolOutputEnvelope<z.input<TOutputSchema>>>(definition: ZodPluginToolDefinition<TInputSchema, TOutputSchema, TExecuteResult>): PluginToolDefinition<z.output<TInputSchema>, z.output<TOutputSchema>, ParsedPluginToolExecuteResult<TOutputSchema, TExecuteResult>>;
+interface SlackToolRegistrationHookContext {
+    /**
+     * What Slack tools can do in the Conversation Location.
+     * Computed from Location, not from Source or Destination.
+     */
+    channelCapabilities: {
+        canAddReactions: boolean;
+        canCreateCanvas: boolean;
+        canPostToChannel: boolean;
+    };
+    /** Host-owned link to this conversation, preferring the dashboard when enabled. */
+    conversationLink?: SlackConversationLink;
+    credentialSubject?: Extract<PluginCredentialSubject, {
+        allowedWhen: "private-direct-conversation";
+    }>;
+}
+interface PluginResourceEventToolContext {
+    /** Whether this invocation can create a working resource subscription. */
+    canSubscribe: boolean;
+    /** Create a temporary resource subscription for the current conversation. */
+    subscribe(input: {
+        events: string[];
+        intent: string;
+        resource: SubscribableResource;
+    }): Promise<ResourceEventSubscriptionResult>;
+}
+interface PluginWorkspaceToolContext {
+    /** Find named Workspaces that include one provider repository. */
+    findByRepository(input: {
+        provider: string;
+        repo: string;
+    }): Promise<string[]>;
+}
+interface BaseToolRegistrationHookContext extends PluginContext {
+    /**
+     * Opaque Junior conversation/session identity for this turn.
+     * Interactive Slack turns use `slack:{channelId}:{threadTs}`.
+     * Scheduled/web turns use an internal id such as `agent-dispatch:{id}`.
+     * Do not parse as Slack unless the value starts with `slack:`.
+     */
+    conversationId?: string;
+    annotations?: PluginAnnotations;
+    embedder: PluginEmbedder;
+    egress: PluginEgress;
+    mcp?: PluginMcp;
+    model: PluginModel;
+    resourceEvents: PluginResourceEventToolContext;
+    /** Sandbox filesystem and command capability for plugin-owned workspace tools. */
+    sandbox: PluginSandbox;
+    state: PluginState;
+    users: {
+        /** Resolve the current actor's stored identity and linked user. */
+        resolveActor(): Promise<{
+            identity: Identity;
+            user?: User;
+        } | undefined>;
+    };
+    userText?: string;
+    workspaces: PluginWorkspaceToolContext;
+}
+type ToolRegistrationHookContext = BaseToolRegistrationHookContext & InvocationContext & {
+    /** Slack tool details when the Conversation has a Slack Location. */
+    slack?: SlackToolRegistrationHookContext;
+};
+
+/**
+ * Deny provider egress when a plugin policy does not allow the request.
+ *
+ * Call from a plugin `grantForEgress` hook before returning a write grant.
+ */
+declare function enforceEgressPolicy(input: {
+    allowed: boolean;
+    denialMessage: string;
+}): void;
+
+/** Input for a pure Markdown rewrite before destination delivery formatting. */
+interface FormatMarkdownHookContext {
+    text: string;
+}
+interface PluginHooks {
+    conversationSidebar?(ctx: ConversationSidebarHookContext): Promise<ConversationSidebarResult> | ConversationSidebarResult;
+    systemPrompt?(ctx: SystemPromptContext): Promise<PromptMessage[]> | PromptMessage[];
+    userPrompt?(ctx: UserPromptContext): Promise<UserPromptContribution[] | undefined> | UserPromptContribution[] | undefined;
+    beforeToolExecute?(ctx: BeforeToolExecuteHookContext): Promise<void> | void;
+    /**
+     * Run after a successful hosted MCP tool call.
+     *
+     * Prefer this for junior-owned side effects such as conversation annotations.
+     * Do not use it to invent a parallel tool contract for the provider tool.
+     */
+    afterMcpTool?(ctx: AfterMcpToolHookContext): Promise<void> | void;
+    grantForEgress?(ctx: EgressHookContext): Promise<PluginGrant | undefined> | PluginGrant | undefined;
+    heartbeat?(ctx: HeartbeatHookContext): Promise<HeartbeatResult | void> | HeartbeatResult | void;
+    unfinishedWork?(ctx: UnfinishedWorkHookContext): Promise<UnfinishedWorkResult> | UnfinishedWorkResult;
+    issueCredential?(ctx: IssueCredentialHookContext): Promise<PluginCredentialResult> | PluginCredentialResult;
+    onEgressResponse?(ctx: EgressResponseHookContext): Promise<void> | void;
+    operationalReport?(ctx: OperationalReportHookContext): Promise<PluginOperationalReportContent | undefined> | PluginOperationalReportContent | undefined;
+    /**
+     * Return one person-scoped operational report for a profile page.
+     * Omit or return undefined when the plugin has nothing to show for the subject.
+     */
+    profileReport?(ctx: ProfileReportHookContext): Promise<PluginOperationalReportContent | undefined> | PluginOperationalReportContent | undefined;
+    /** Return plugin-owned product API routes mounted under Junior's authenticated plugin namespace. */
+    apiRoutes?(ctx: ApiRouteRegistrationHookContext): PluginRouteApp | undefined;
+    resolveOAuthAccount?(ctx: ResolveOAuthAccountHookContext): Promise<PluginProviderAccount | undefined> | PluginProviderAccount | undefined;
+    routes?(ctx: RouteRegistrationHookContext): PluginRoute[];
+    sandboxPrepare?(ctx: SandboxPrepareHookContext): Promise<void> | void;
+    workspacePrepare?(ctx: WorkspacePrepareHookContext): Promise<void> | void;
+    slackConversationLink?(ctx: SlackConversationLinkHookContext): SlackConversationLink | undefined;
+    /** Pure Markdown rewrite. Emit ordinary Markdown only. */
+    formatMarkdown?(ctx: FormatMarkdownHookContext): string;
+    tools?(ctx: ToolRegistrationHookContext): Record<string, PluginToolDefinition>;
+}
+
+/**
+ * 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.
+ */
+
+interface PluginCliIo {
+    writeError(text: string): Promise<void> | void;
+    writeOutput(text: string): Promise<void> | void;
+}
+interface PluginCliActionCommand {
+    name: string;
+    summary: string;
+}
+/** Host/admin context exposed to plugin-owned CLI command actions. */
+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. */
+type PluginCliActionHandler<Args extends unknown[] = unknown[]> = (ctx: PluginCliActionContext, ...args: Args) => Promise<number | void> | number | void;
+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. */
+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. */
+interface PluginCliDefinition {
+    commands: PluginCliCommandDefinition[];
+}
+
+interface PluginOAuthConfig {
+    authorizeEndpoint: string;
+    authorizeParams?: Record<string, string>;
+    clientIdEnv: string;
+    clientSecretEnv: string;
+    scope?: string;
+    /**
+     * Treat a provider token response with `scope: ""` like an omitted scope and
+     * fall back to the requested scope string when storing the token.
+     */
+    treatEmptyScopeAsUnreported?: boolean;
+    tokenAuthMethod?: "body" | "basic";
+    tokenEndpoint: string;
+    tokenExtraHeaders?: Record<string, string>;
+}
+interface PluginOAuthBearerCredentials {
+    apiHeaders?: Record<string, string>;
+    authTokenEnv: string;
+    authTokenPlaceholder?: string;
+    domains: string[];
+    type: "oauth-bearer";
+}
+type PluginCredentials = PluginOAuthBearerCredentials;
+interface PluginNpmRuntimeDependency {
+    package: string;
+    type: "npm";
+    version: string;
+}
+interface PluginSystemRuntimeDependency {
+    package: string;
+    type: "system";
+}
+interface PluginSystemRuntimeDependencyFromUrl {
+    sha256: string;
+    type: "system";
+    url: string;
+}
+type PluginRuntimeDependency = PluginNpmRuntimeDependency | PluginSystemRuntimeDependency | PluginSystemRuntimeDependencyFromUrl;
+interface PluginRuntimePostinstallCommand {
+    args?: string[];
+    cmd: string;
+    sudo?: boolean;
+}
+interface PluginMcpConfig {
+    /** Provider tools exposed directly to the model. */
+    allowedTools?: string[];
+    headers?: Record<string, string>;
+    transport: "http";
+    url: string;
+    /** Provider tools hidden from the model and callable only by plugin-owned wrapper tools. */
+    wrappedTools?: string[];
+}
+interface PluginEnvVarDeclaration {
+    default?: string;
+    exposeToCommandEnv?: boolean;
+}
+interface PluginManifest {
+    apiHeaders?: Record<string, string>;
+    commandEnv?: Record<string, string>;
+    configKeys?: string[];
+    credentials?: PluginCredentials;
+    description: string;
+    displayName: string;
+    domains?: string[];
+    envVars?: Record<string, PluginEnvVarDeclaration>;
+    mcp?: PluginMcpConfig;
+    name: string;
+    oauth?: PluginOAuthConfig;
+    runtimeDependencies?: PluginRuntimeDependency[];
+    runtimePostinstall?: PluginRuntimePostinstallCommand[];
+    target?: {
+        commandFlags?: string[];
+        configKey: string;
+        type: string;
+    };
+}
+
+/**
+ * Core-rendered plugin user pages.
+ *
+ * Plugins own bounded data projection; Junior owns viewer authorization,
+ * routing, response validation, and browser rendering.
+ */
+
+/** Bounded list content returned by a plugin-owned user page. */
+declare const pluginUserPageContentSchema: z.ZodObject<{
+    emptyText: z.ZodOptional<z.ZodString>;
+    metrics: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        detail: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        tone: z.ZodOptional<z.ZodEnum<{
+            warning: "warning";
+            good: "good";
+            neutral: "neutral";
+        }>>;
+        value: z.ZodString;
+    }, z.core.$strict>>>;
+    nextCursor: z.ZodOptional<z.ZodString>;
+    records: z.ZodArray<z.ZodObject<{
+        actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            confirmation: z.ZodOptional<z.ZodString>;
+            href: z.ZodString;
+            label: z.ZodString;
+            method: z.ZodLiteral<"DELETE">;
+            tone: z.ZodOptional<z.ZodEnum<{
+                danger: "danger";
+                neutral: "neutral";
+            }>>;
+        }, z.core.$strict>>>;
+        description: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        metadata: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strict>>>;
+        title: z.ZodString;
+    }, z.core.$strict>>;
+    searchPlaceholder: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"list">;
+}, z.core.$strict>;
+/** Validated content for the current core-rendered list page type. */
+type PluginUserPageContent = z.output<typeof pluginUserPageContentSchema>;
+declare const pluginUserPageLinkSchema: z.ZodObject<{
+    description: z.ZodString;
+    id: z.ZodString;
+    label: z.ZodString;
+    navigation: z.ZodEnum<{
+        primary: "primary";
+        profile: "profile";
+    }>;
+    pluginDisplayName: z.ZodString;
+    pluginName: z.ZodString;
+}, z.core.$strict>;
+declare const pluginUserPageLinksSchema: z.ZodArray<z.ZodObject<{
+    description: z.ZodString;
+    id: z.ZodString;
+    label: z.ZodString;
+    navigation: z.ZodEnum<{
+        primary: "primary";
+        profile: "profile";
+    }>;
+    pluginDisplayName: z.ZodString;
+    pluginName: z.ZodString;
+}, z.core.$strict>>;
+/** Safe navigation metadata for one registered plugin user page. */
+type PluginUserPageLink = z.output<typeof pluginUserPageLinkSchema>;
+/** Optional cursor token for one plugin user page reader. */
+declare const pluginUserPageCursorSchema: z.ZodOptional<z.ZodString>;
+/** Optional filter token for one plugin user page reader. */
+declare const pluginUserPageFilterSchema: z.ZodOptional<z.ZodString>;
+/** Optional free-text query for one plugin user page reader. */
+declare const pluginUserPageQuerySchema: z.ZodOptional<z.ZodString>;
+/** Validated query state passed to one plugin user page reader. */
+declare const pluginUserPageInputSchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    filter: z.ZodOptional<z.ZodString>;
+    limit: z.ZodNumber;
+    query: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type PluginUserPageInput = z.output<typeof pluginUserPageInputSchema>;
+/** Trusted host context supplied while reading one plugin user page. */
+interface PluginUserPageContext extends PluginContext {
+    viewer: User;
+}
+/** Navigation metadata and reader for one core-rendered plugin user page. */
+interface PluginUserPageDefinition {
+    description: string;
+    id: string;
+    label: string;
+    /** Dashboard navigation surface where this page is linked. */
+    navigation?: "primary" | "profile";
+    read(ctx: PluginUserPageContext, input: PluginUserPageInput): Promise<PluginUserPageContent> | PluginUserPageContent;
+}
+
+interface PluginModelConfig {
+    /** Host model family used when no explicit structured model id is configured. */
+    structuredModel?: "default" | "fast";
+    /** Host model id used for this plugin's structured model calls. */
+    structuredModelId?: string;
+}
+type PluginRegistrationInput = {
+    cli?: PluginCliDefinition;
+    conversationEvents?: PluginConversationEventDefinition[];
+    hooks?: PluginHooks;
+    manifest: PluginManifest;
+    model?: PluginModelConfig;
+    packageName?: string;
+    resourceEvents?: PluginResourceEvents;
+    tasks?: PluginTasks;
+    userPages?: PluginUserPageDefinition[];
+};
+interface PluginRegistration extends PluginRegistrationInput {
+}
+/** Define one Junior plugin registration for app and build-time wiring. */
+declare function defineJuniorPlugin(plugin: PluginRegistrationInput): PluginRegistration;
+
+export { type Actor, type AfterMcpToolHookContext, type AgentInvocationSource, type ApiRouteRegistrationHookContext, type BeforeToolExecuteHookContext, type CodeChangeInput, type CodeChangePublisher, type CodeChangeState, type ConversationAnnotation, type ConversationAnnotationInput, type ConversationEventPresentation, type ConversationSidebarAnnotation, type ConversationSidebarHookContext, type ConversationSidebarResult, type DefinedConversationEvent, type Destination, type DestinationVisibility, type Dispatch, type DispatchOptions, type DispatchResult, EgressAuthRequired, type EgressHookContext, EgressPolicyDenied, type EgressResponseHookContext, type EventTaskSource, type FormatMarkdownHookContext, type HeartbeatHookContext, type HeartbeatResult, type Identity, type InvocationContext, type IssueCredentialHookContext, type LocalActor, type LocalDestination, type LocalInvocationContext, type LocalSource, type Location, type OperationalReportHookContext, type Platform, type PluginAnnotations, type PluginApiRouteRequestContext, type PluginAuthorization, type PluginCliActionCommand, type PluginCliActionContext, type PluginCliActionHandler, type PluginCliCommandDefinition, type PluginCliDefinition, type PluginCliHost, type PluginCliIo, type PluginContext, type PluginConversationAnnotations, type PluginConversationEventCostDay, type PluginConversationEventDefinition, type PluginConversationEventStats, type PluginConversationEventValue, type PluginConversationEvents, type PluginCredentialActor, type PluginCredentialHeaderTransform, type PluginCredentialLease, type PluginCredentialResult, type PluginCredentialSubject, type PluginCredentials, type PluginDecision, type PluginDispatchSource, type PluginEgress, type PluginEgressRequest, type PluginEgressResponse, type PluginEmbedder, type PluginEnv, type PluginEnvVarDeclaration, type PluginGrant, type PluginGrantAccess, type PluginHooks, type PluginLogger, type PluginManifest, type PluginMcp, type PluginMcpAuthorizationPending, type PluginMcpConfig, type PluginMcpContent, type PluginMcpToolError, type PluginMcpToolResult, type PluginMcpToolSuccess, type PluginMetadata, type PluginModel, type PluginModelConfig, type PluginNpmRuntimeDependency, type PluginOAuthBearerCredentials, type PluginOAuthConfig, type PluginOperationalBarChartWidget, type PluginOperationalChartCategory, type PluginOperationalChartSeries, type PluginOperationalField, type PluginOperationalMetric, type PluginOperationalRecord, type PluginOperationalRecordSet, type PluginOperationalReport, type PluginOperationalReportContent, type PluginOperationalTone, type PluginProviderAccount, type PluginReadState, type PluginRegistration, type PluginRegistrationInput, type PluginResolvedCredentialUser, type PluginResourceEventToolContext, type PluginResourceEventType, type PluginResourceEvents, type PluginRoute, type PluginRouteApp, type PluginRouteHandler, type PluginRouteMethod, type PluginRunContext, type PluginRunTranscriptEntry, type PluginRunTranscriptProvenance, type PluginRuntimeDependency, type PluginRuntimePostinstallCommand, type PluginSandbox, type PluginState, type PluginStoredTokens, type PluginSystemRuntimeDependency, type PluginSystemRuntimeDependencyFromUrl, type PluginTaskContext, type PluginTaskDefinition, type PluginTasks, type PluginTokenStore, type PluginToolContent, type PluginToolDefinition, type PluginToolExecute, type PluginToolExecuteOptions, PluginToolInputError, type PluginToolOutput, type PluginToolOutputEnvelope, type PluginUserPageContent, type PluginUserPageContext, type PluginUserPageDefinition, type PluginUserPageInput, type PluginUserPageLink, type PluginUserTokenSlot, type PluginWorkspaceToolContext, type ProfileReportHookContext, type PromptContext, type PromptContextContribution, type PromptMessage, REQUIRED_TOOL_ANNOTATION_KEYS, RESOURCE_EVENT_DATA_MAX_JSON_BYTES, RESOURCE_EVENT_DATA_MAX_KEYS, RESOURCE_EVENT_GUIDANCE_MAX_LENGTH, RESOURCE_EVENT_SUMMARY_MAX_LENGTH, RESOURCE_EVENT_TEXT_MAX_LENGTH, type ReplyAttribution, type RequiredToolAnnotationKey, type ResolveOAuthAccountHookContext, type ResourceEvent, type ResourceEventData, type ResourceEventInput, type ResourceEventInvocationContext, type ResourceEventMatch, type ResourceEventMatchFields, type ResourceEventPublisher, type ResourceEventSource, type ResourceEventSubscriptionResult, type RouteRegistrationHookContext, type SandboxPrepareHookContext, type ScheduledTaskSource, type SlackActor, type SlackConversationLink, type SlackConversationLinkHookContext, type SlackDestination, type SlackInvocationContext, type SlackLocation, type SlackSource, type SlackToolRegistrationHookContext, type Source, type SourceVisibility, type SubscribableResource, type SystemActor, type SystemPromptContext, type ToolAnnotations, type ToolApprovalMetadata, type ToolApprovalMode, type ToolRegistrationHookContext, type UnfinishedWorkHookContext, type UnfinishedWorkResult, type User, type UserPromptContext, type UserPromptContribution, type WebActor, type WebInvocationContext, type WebSource, type WorkspacePrepareHookContext, actorSchema, actorUserIdSchema, agentInvocationSourceSchema, codeChangeInputSchema, codeChangeStateSchema, conversationAnnotationInputSchema, conversationEventIconSchema, conversationEventPresentationSchema, conversationSidebarAnnotationSchema, conversationSidebarIconSchema, createLocalSource, createResourceEventSource, createSlackSource, createWebSource, defineConversationEvent, defineJuniorPlugin, definePluginTool, definePromptContext, destinationSchema, destinationVisibilitySchema, dispatchOptionsSchema, enforceEgressPolicy, eventTaskSourceSchema, getSourceKey, identitySchema, isPrivateSource, isSlackDestination, localActorSchema, localDestinationSchema, localSourceSchema, locationSchema, missingToolAnnotationKeys, nonBlankStringSchema, normalizeResourceEventIdentifier, platformSchema, pluginApiRouteRequestContextSchema, pluginAuthorizationSchema, pluginCredentialHeaderTransformSchema, pluginCredentialLeaseSchema, pluginCredentialResultSchema, pluginCredentialSubjectSchema, pluginDispatchSourceSchema, pluginGrantSchema, pluginProviderAccountSchema, pluginResourceEventTypeSchema, pluginResourceEventsSchema, pluginRunContextSchema, pluginRunTranscriptEntrySchema, pluginRunTranscriptProvenanceSchema, pluginStoredTokensSchema, pluginToolContentSchema, pluginToolContinuationSchema, pluginToolOutputSchema, pluginUserPageContentSchema, pluginUserPageCursorSchema, pluginUserPageFilterSchema, pluginUserPageInputSchema, pluginUserPageLinkSchema, pluginUserPageLinksSchema, pluginUserPageQuerySchema, promptContextSchema, promptMessageSchema, replyAttributionSchema, resourceEventDataSchema, resourceEventInputSchema, resourceEventMatchFieldSchema, resourceEventMatchFieldsSchema, resourceEventMatchSchema, resourceEventMatches, resourceEventSchema, resourceEventSourceSchema, resourceEventSubscriptionResultSchema, resourceEventTypeSchema, resourceLinkAnnotationSchema, resourceTypeSchema, scheduledTaskSourceSchema, slackActorSchema, slackDestinationSchema, slackLocationSchema, slackSourceSchema, sourceSchema, sourceVisibilitySchema, stableResourceEventMatchKey, subscribableResourceSchema, systemActorSchema, toolApprovalModeSchema, userSchema, webActorSchema, webSourceSchema, zodTool };