@sentry/junior 0.197.0 → 0.199.0

package/dist/app.d.ts

@@ -1,16 +1,455 @@
-import { Hono } from "hono";
-import type { ModelProfileInput } from "@/chat/model-profile";
-import { type ExperimentalFeaturesConfig } from "@/chat/experimental";
-import { type SandboxResourceConfig } from "@/chat/sandbox/resources";
-import { type JuniorPluginSet } from "./plugins";
-import type { ConversationWorkCallbackOptions } from "@/chat/app/conversation-work";
-import type { WaitUntilFn } from "@/handlers/types";
-import { JUNIOR_VERSION } from "./version";
-export { defineJuniorPlugins } from "./plugins";
-export { JUNIOR_VERSION };
-export type { JuniorPluginInput, JuniorPluginSet, JuniorPluginSetOptions, } from "./plugins";
-export type { ModelProfileInput } from "@/chat/model-profile";
-export interface JuniorAppOptions {
+import { Hono } from 'hono';
+import { PluginRuntimePostinstallCommand, PluginRegistration, locationSchema, Source, Destination } from '@sentry/junior-plugin-api';
+import { StateAdapter } from 'chat';
+import { z } from 'zod';
+export { JUNIOR_VERSION } from './version.js';
+
+declare const TURN_REASONING_LEVELS: readonly ["none", "low", "medium", "high", "xhigh"];
+type TurnReasoningLevel = (typeof TURN_REASONING_LEVELS)[number];
+
+/** Runtime configuration for one named model profile. */
+interface ModelProfileConfig {
+    /**
+     * Tells models which tasks fit this profile.
+     * Name concrete tasks. Add use and avoid cases when helpful.
+     * Do not use model product names as the selection rule.
+     */
+    description?: string;
+    modelId: string;
+    reasoningLevel?: TurnReasoningLevel;
+}
+/** App-level profile input: a model id string or a full profile config. */
+type ModelProfileInput = string | ModelProfileConfig;
+
+interface BotModelConfig {
+    /** Model used for embeddings. */
+    embeddingModelId?: string;
+    /** Model used for low-cost structured and utility calls. */
+    fastModelId?: string;
+    /** Model used to review sensitive tool calls. */
+    guardianModelId?: string;
+    /** Model used to generate images. */
+    imageGenerationModelId?: string;
+    /** Model used to analyze images. */
+    visionModelId?: string;
+    /** Model used for web search. */
+    webSearchModelId?: string;
+}
+
+/**
+ * Known unstable product features that must be opted into explicitly.
+ * Add new keys here as features graduate from private experiments; remove them
+ * once they become stable defaults.
+ */
+declare const EXPERIMENTAL_FEATURES: readonly ["passive-routing", "subagents"];
+/** One known experimental feature name. */
+type ExperimentalFeature = (typeof EXPERIMENTAL_FEATURES)[number];
+/** App-level opt-ins for unstable product features. */
+type ExperimentalFeaturesConfig = Readonly<Partial<Record<ExperimentalFeature, boolean>>>;
+
+interface SandboxResourceConfig {
+    vcpus?: number;
+}
+
+interface PluginOAuthConfig {
+    clientIdEnv: string;
+    clientSecretEnv: string;
+    authorizeEndpoint: string;
+    tokenEndpoint: string;
+    scope?: string;
+    /**
+     * Set true when the provider returns an empty scope string even for authorized
+     * grants (e.g. GitHub App user-to-server tokens always return `scope: ""`
+     * regardless of what was requested). When enabled, an empty response scope
+     * uses the configured `scope` value instead of being treated as
+     * "no scopes granted".
+     */
+    treatEmptyScopeAsUnreported?: boolean;
+    authorizeParams?: Record<string, string>;
+    tokenAuthMethod?: "body" | "basic";
+    tokenExtraHeaders?: Record<string, string>;
+}
+interface PluginEnvVarDeclaration {
+    default?: string;
+    exposeToCommandEnv?: boolean;
+}
+type PluginRuntimeDependencyConfig = {
+    type: "npm";
+    package: string;
+    version?: string;
+} | {
+    type: "system";
+    package: string;
+} | {
+    type: "system";
+    url: string;
+    sha256: string;
+};
+interface PluginOAuthConfigPatch extends Omit<Partial<PluginOAuthConfig>, "authorizeParams" | "tokenExtraHeaders"> {
+    authorizeParams?: Record<string, string | null> | null;
+    tokenExtraHeaders?: Record<string, string | null> | null;
+}
+type PluginCredentialConfigBase = {
+    domains?: string[];
+    authTokenEnv?: string;
+    authTokenPlaceholder?: string | null;
+};
+type PluginCredentialConfig = PluginCredentialConfigBase & {
+    apiHeaders?: Record<string, string | null> | null;
+    type?: "oauth-bearer";
+};
+/** Install-level changes applied to one plugin manifest before validation. */
+interface PluginManifestConfig {
+    displayName?: string;
+    description?: string;
+    configKeys?: string[];
+    domains?: string[] | null;
+    apiHeaders?: Record<string, string | null> | null;
+    commandEnv?: Record<string, string | null> | null;
+    envVars?: Record<string, PluginEnvVarDeclaration | null> | null;
+    credentials?: PluginCredentialConfig | null;
+    runtimeDependencies?: PluginRuntimeDependencyConfig[] | null;
+    runtimePostinstall?: PluginRuntimePostinstallCommand[] | null;
+    mcp?: {
+        transport?: "http";
+        url?: string;
+        headers?: Record<string, string | null> | null;
+        allowedTools?: string[] | null;
+        wrappedTools?: string[] | null;
+    } | null;
+    oauth?: PluginOAuthConfigPatch | null;
+    target?: {
+        type?: string;
+        configKey?: string;
+        commandFlags?: string[] | null;
+    } | null;
+}
+
+type JuniorPluginInput = PluginRegistration | string;
+interface JuniorPluginSetOptions {
+    /** Install-level manifest overrides applied before validation. */
+    manifests?: Record<string, PluginManifestConfig>;
+}
+/** Reusable plugin registrations and manifest overrides. */
+interface JuniorPluginSet {
+    /** Install-level manifest overrides applied before validation. */
+    manifests?: Record<string, PluginManifestConfig>;
+    /** Manifest-only plugin packages included by package name. */
+    packageNames: string[];
+    /** JavaScript plugin definitions included by package factories. */
+    registrations: PluginRegistration[];
+}
+/** Define package-name plugins and JS plugin definitions for one app. */
+declare function defineJuniorPlugins(inputs: JuniorPluginInput[], options?: JuniorPluginSetOptions): JuniorPluginSet;
+
+/** Validated Location associated with a Conversation. */
+type Location = z.output<typeof locationSchema>;
+
+/**
+ * Canonical actor identity.
+ *
+ * Runtime actors are platform-scoped actors. Stored Slack actor parsing
+ * remains explicit so durable conversation metadata is not repaired on read.
+ */
+
+declare const storedSlackActorSchema: z.ZodObject<{
+    email: z.ZodOptional<z.ZodString>;
+    fullName: z.ZodOptional<z.ZodString>;
+    platform: z.ZodOptional<z.ZodLiteral<"slack">>;
+    slackUserId: z.ZodOptional<z.ZodString>;
+    slackUserName: z.ZodOptional<z.ZodString>;
+    teamId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type StoredSlackActor = z.output<typeof storedSlackActorSchema>;
+
+type ConversationPrivacy = "public" | "private";
+
+declare const usageSchema: z.ZodObject<{
+    inputTokens: z.ZodOptional<z.ZodNumber>;
+    outputTokens: z.ZodOptional<z.ZodNumber>;
+    cachedInputTokens: z.ZodOptional<z.ZodNumber>;
+    cacheCreationTokens: z.ZodOptional<z.ZodNumber>;
+    reasoningTokens: z.ZodOptional<z.ZodNumber>;
+    totalTokens: z.ZodOptional<z.ZodNumber>;
+    cost: z.ZodOptional<z.ZodObject<{
+        input: z.ZodOptional<z.ZodNumber>;
+        output: z.ZodOptional<z.ZodNumber>;
+        cacheRead: z.ZodOptional<z.ZodNumber>;
+        cacheWrite: z.ZodOptional<z.ZodNumber>;
+        total: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type Usage = z.output<typeof usageSchema>;
+
+/**
+ * Structured token and cost usage captured for a single agent turn.
+ *
+ * Mirrors the fields pi-ai emits on `AssistantMessage.usage` (see
+ * `@earendil-works/pi-ai` `Usage`) so diagnostics carry every counter the
+ * provider normalizes into the pi-ai shape as its own item. Renderers decide
+ * whether to display a breakdown or a single aggregate.
+ */
+type AgentTurnUsage = Usage;
+
+/** Legacy provider Source fields stored on a Conversation. */
+type SessionSource = Extract<Source, {
+    kind: "web";
+}> | Extract<Source, {
+    kind: "local";
+}> | Omit<Extract<Source, {
+    kind: "slack";
+}>, "messageTs">;
+
+type ConversationSource = "api" | "internal" | "local" | "plugin" | "resource_event" | "scheduler" | "slack" | "web";
+type ConversationStatus = "paused" | "failed" | "idle" | "pending" | "running";
+interface ConversationExecution {
+    lastCheckpointAtMs?: number;
+    lastEnqueuedAtMs?: number;
+    runId?: string;
+    status: ConversationStatus;
+    updatedAtMs?: number;
+}
+/**
+ * Durable Conversation owned by Junior.
+ *
+ * The final interface stores zero or one complete Location here. No Location
+ * means the Conversation stays in Junior's API and UI. A Location names the
+ * outside place where a provider can deliver the Conversation. A Run carries
+ * this Location when the agent or tools need it. Source stays about the input.
+ * Delivery is created for the Location and allows output to be sent there.
+ *
+ * `destination` and `sessionSource` temporarily duplicate parts of that model.
+ * Their field TODOs state when each legacy copy can be removed.
+ */
+interface Conversation {
+    channelName?: string;
+    conversationId: string;
+    createdAtMs: number;
+    destination?: Destination;
+    execution: ConversationExecution;
+    executionMetrics?: {
+        durationMs: number;
+        runId?: string;
+        usage?: AgentTurnUsage;
+    };
+    lastActivityAtMs: number;
+    /** Immutable parent Conversation. */
+    parentConversationId?: string;
+    /** Optional provider coordinates associated with this Conversation. */
+    location?: Location;
+    actor?: StoredSlackActor;
+    schemaVersion: 1;
+    source?: ConversationSource;
+    /**
+     * Structured inbound Source locator for this conversation session.
+     * Session-stable (threaded Slack keeps threadTs; channel-level turns omit
+     * it; never stores per-message ts). Set-once.
+     */
+    sessionSource?: SessionSource;
+    title?: string;
+    updatedAtMs: number;
+    /**
+     * When retention purged this conversation's content. Set means messages and
+     * events were deleted wholesale; reporting presents the transcript as expired
+     * rather than privacy-redacted (`../../../../../policies/data-redaction.md`).
+     */
+    transcriptPurgedAtMs?: number;
+    /** Confirmed Conversation visibility. Undefined means no confirmation exists. */
+    visibility?: ConversationPrivacy;
+}
+/** Persist and read durable conversation metadata for reporting surfaces. */
+interface ConversationStore {
+    /** Create one Conversation with an immutable parent. */
+    createChild(args: {
+        childConversationId: string;
+        parentConversationId: string;
+        nowMs?: number;
+        source?: ConversationSource;
+    }): Promise<void>;
+    get(args: {
+        conversationId: string;
+    }): Promise<Conversation | undefined>;
+    /** Resolve the durable conversation bound to one provider conversation. */
+    getConversationIdByProviderConversation(args: {
+        provider: string;
+        providerDestinationId: string;
+        providerTenantId: string;
+        providerConversationId: string;
+    }): Promise<string | undefined>;
+    /** Bind one provider conversation to its pre-existing durable conversation. */
+    bindProviderConversation(args: {
+        conversationId: string;
+        provider: string;
+        providerDestinationId: string;
+        providerTenantId: string;
+        providerConversationId: string;
+    }): Promise<void>;
+    /** Read confirmed public/private visibility for one destination. */
+    getDestinationVisibility(args: {
+        provider: string;
+        providerDestinationId: string;
+        providerTenantId?: string;
+    }): Promise<ConversationPrivacy | undefined>;
+    /**
+     * Resolve one Slack channel id from a known destination display name.
+     *
+     * Matches only destinations Junior already stored for this workspace. Exact
+     * name match after stripping a leading `#`. Returns undefined when missing
+     * or ambiguous. Does not scan Slack.
+     */
+    findSlackDestinationByName(args: {
+        channelName: string;
+        teamId: string;
+    }): Promise<{
+        channelId: string;
+        channelName?: string;
+    } | undefined>;
+    recordActivity(args: {
+        activityAtMs?: number;
+        channelName?: string;
+        conversationId: string;
+        destination?: Destination;
+        nowMs?: number;
+        actor?: StoredSlackActor;
+        source?: ConversationSource;
+        /** Source normalized to a stable session locator; set-once when absent. */
+        sessionSource?: Source;
+        title?: string;
+        /** Confirmed destination visibility; omit when unavailable. */
+        visibility?: ConversationPrivacy;
+    }): Promise<void>;
+    /**
+     * Materialize execution and usage aggregates beside canonical metadata.
+     * These fields serve reporting and runtime control, never history hydration.
+     */
+    recordExecution(args: {
+        channelName?: string;
+        conversationId: string;
+        createdAtMs: number;
+        destination?: Destination;
+        execution: ConversationExecution;
+        lastActivityAtMs: number;
+        metrics: {
+            durationMs: number;
+            usage?: AgentTurnUsage;
+        } | null;
+        actor?: StoredSlackActor;
+        source?: ConversationSource;
+        title?: string;
+        updatedAtMs: number;
+        /** Confirmed destination visibility; omit when unavailable. */
+        visibility?: ConversationPrivacy;
+    }): Promise<void>;
+    listByActivity(args?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Conversation[]>;
+}
+
+/** Validate the v2 conversation work hint sent through Vercel Queue. */
+declare const conversationQueueMessageSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<2>;
+    conversationId: z.ZodString;
+}, z.core.$strict>;
+/** Conversation work hint accepted by the queue callback and worker. */
+type ConversationQueueMessage = z.output<typeof conversationQueueMessageSchema>;
+interface ConversationQueueSendOptions {
+    delayMs?: number;
+    idempotencyKey?: string;
+}
+interface ConversationQueueSendResult {
+    messageId?: string;
+}
+/**
+ * External transport for wake-up hints. Durable work stays in the mailbox;
+ * transports only need to accept one hint and may return a provider message id.
+ */
+interface ConversationWorkQueue {
+    send(message: ConversationQueueMessage, options?: ConversationQueueSendOptions): Promise<ConversationQueueSendResult | void>;
+}
+
+/** Canonical durable mailbox entry owned by task execution. */
+declare const inboundMessageSchema: z.ZodObject<{
+    attemptCount: z.ZodOptional<z.ZodNumber>;
+    conversationId: z.ZodString;
+    createdAtMs: z.ZodNumber;
+    delivery: z.ZodEnum<{
+        defer: "defer";
+        interrupt: "interrupt";
+    }>;
+    destination: z.ZodOptional<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">>;
+    inboundMessageId: z.ZodString;
+    injectedAtMs: z.ZodOptional<z.ZodNumber>;
+    input: z.ZodObject<{
+        attachments: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        authorId: z.ZodOptional<z.ZodString>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        text: z.ZodString;
+    }, z.core.$strict>;
+    receivedAtMs: z.ZodNumber;
+    source: z.ZodEnum<{
+        slack: "slack";
+        api: "api";
+        plugin: "plugin";
+        local: "local";
+        web: "web";
+        resource_event: "resource_event";
+        internal: "internal";
+        scheduler: "scheduler";
+    }>;
+}, z.core.$strict>;
+type InboundMessage = z.output<typeof inboundMessageSchema>;
+
+interface ConversationWorkerContext {
+    attempt: InboxAttempt;
+    checkIn(): Promise<boolean>;
+    conversationId: string;
+    destination?: Destination;
+    /** True when the current execution slice must stop at its next safe boundary. */
+    shouldYield(): boolean;
+    /** Return an AbortSignal backed by the durable Conversation stop request. */
+    stopSignal?(): AbortSignal;
+}
+interface InboxAttempt {
+    ack(): Promise<void>;
+    conversationId: string;
+    destination?: Destination;
+    drain(handle: (messages: InboundMessage[]) => Promise<readonly string[] | void>): Promise<InboundMessage[]>;
+    isFinalAttempt: boolean;
+    messages: InboundMessage[];
+}
+interface ConversationWorkerResult {
+    /** `paused` waits for an external wake but must resume if a stop raced it. */
+    status: "completed" | "deferred" | "lost_lease" | "paused" | "yielded";
+}
+
+interface ProcessConversationQueueMessageOptions {
+    checkInIntervalMs?: number;
+    conversationStore?: ConversationStore;
+    nowMs?: () => number;
+    queue?: ConversationWorkQueue;
+    run(context: ConversationWorkerContext): Promise<ConversationWorkerResult>;
+    softYieldAfterMs?: number;
+    state?: StateAdapter;
+}
+interface VercelConversationWorkCallbackOptions extends ProcessConversationQueueMessageOptions {
+    topic?: string;
+    visibilityTimeoutSeconds?: number;
+}
+
+type ConversationWorkCallbackOptions = VercelConversationWorkCallbackOptions;
+
+/** Callback to schedule background work that must finish before the function exits. */
+type WaitUntilFn = (task: Promise<unknown> | (() => Promise<unknown>)) => void;
+
+interface JuniorAppOptions extends BotModelConfig {
     /** Authenticated dashboard mounted by core when configured. */
     dashboard?: JuniorDashboardOptions;
     /**
@@ -51,7 +490,7 @@ export interface JuniorAppOptions {
     };
     waitUntil?: WaitUntilFn;
 }
-export interface JuniorDashboardOptions {
+interface JuniorDashboardOptions {
     /** Browser auth route prefix used by Better Auth. */
     authPath?: string;
     /** Require a dashboard browser session before serving dashboard pages and APIs. */
@@ -76,4 +515,6 @@ export interface JuniorDashboardOptions {
     trustedOrigins?: string[];
 }
 /** Create a Hono app with all Junior routes. */
-export declare function createApp(options?: JuniorAppOptions): Promise<Hono>;
+declare function createApp(options?: JuniorAppOptions): Promise<Hono>;
+
+export { type JuniorAppOptions, type JuniorDashboardOptions, type JuniorPluginInput, type JuniorPluginSet, type JuniorPluginSetOptions, type ModelProfileInput, createApp, defineJuniorPlugins };