@sentry/junior 0.85.0 → 0.87.0

package/dist/chat/conversation-privacy.d.ts

@@ -1,14 +1,24 @@
 export type ConversationPrivacy = "public" | "private";
 type TraceAttributeValue = string | number | boolean | string[];
-/** Resolve whether a conversation may expose raw payloads based on known Slack identity. */
+/**
+ * Resolve whether a conversation may expose raw payloads.
+ *
+ * Only a live source signal or persisted destination visibility can classify
+ * a conversation public. Identifier prefixes may only narrow classification
+ * toward private. Unknown stays undefined so callers fail closed to private.
+ */
 export declare function resolveConversationPrivacy(input: {
     channelId?: string;
     conversationId?: string;
+    /** Live source or persisted visibility, when the caller has one. */
+    visibility?: ConversationPrivacy;
 }): ConversationPrivacy | undefined;
-/** Gate raw transcript/tool payload exposure to conversations known to be public. */
+/** Gate raw transcript/tool payload exposure to public conversations. */
 export declare function canExposeConversationPayload(input: {
     channelId?: string;
     conversationId?: string;
+    /** Live source or persisted visibility, when the caller has one. */
+    visibility?: ConversationPrivacy;
 }): boolean;
 /** Return the privacy mode bound to the current agent turn. */
 export declare function getCurrentConversationPrivacy(): ConversationPrivacy | undefined;

package/dist/chat/conversations/sql/migrations.d.ts

@@ -5,7 +5,7 @@ export interface Migration {
     id: string;
     statements: readonly string[];
 }
-export declare const migrations: readonly [Migration];
+export declare const migrations: readonly [Migration, Migration];
 export { schema };
 /** Apply pending SQL schema migrations for queryable conversation records. */
 export declare function migrateSchema(executor: JuniorSqlMigrationExecutor, migrationList?: readonly Migration[]): Promise<void>;

package/dist/chat/conversations/sql/store.d.ts

@@ -1,4 +1,5 @@
 import type { Destination } from "@sentry/junior-plugin-api";
+import type { ConversationPrivacy } from "@/chat/conversation-privacy";
 import { type StoredSlackRequester } from "@/chat/requester";
 import type { JuniorSqlDatabase, JuniorSqlMigrationExecutor } from "@/chat/sql/db";
 import type { Conversation, ConversationExecution, ConversationSource, ConversationStore } from "../store";
@@ -21,6 +22,7 @@ export declare class SqlStore implements ConversationStore {
         requester?: StoredSlackRequester;
         source?: ConversationSource;
         title?: string;
+        visibility?: ConversationPrivacy;
     }): Promise<void>;
     recordExecution(args: {
         channelName?: string;
@@ -33,13 +35,19 @@ export declare class SqlStore implements ConversationStore {
         source?: ConversationSource;
         title?: string;
         updatedAtMs: number;
+        visibility?: ConversationPrivacy;
     }): Promise<void>;
     /** Copy one conversation record into SQL during backfill. */
-    backfillConversation(conversation: Conversation): Promise<void>;
+    backfillConversation(sourceConversation: Conversation): Promise<void>;
     listByActivity(args?: {
         limit?: number;
         offset?: number;
     }): Promise<Conversation[]>;
+    getDestinationVisibility(args: {
+        provider: string;
+        providerDestinationId: string;
+        providerTenantId?: string;
+    }): Promise<ConversationPrivacy | undefined>;
     /** Serialize all durable mutations for one conversation inside a SQL transaction. */
     private withConversationMutation;
     private readConversationRow;

package/dist/chat/conversations/store.d.ts

@@ -1,4 +1,5 @@
 import type { Destination } from "@sentry/junior-plugin-api";
+import type { ConversationPrivacy } from "@/chat/conversation-privacy";
 import type { StoredSlackRequester } from "@/chat/requester";
 export type ConversationSource = "api" | "internal" | "local" | "plugin" | "resource_event" | "scheduler" | "slack";
 export type ConversationStatus = "awaiting_resume" | "failed" | "idle" | "pending" | "running";
@@ -21,12 +22,20 @@ export interface Conversation {
     source?: ConversationSource;
     title?: string;
     updatedAtMs: number;
+    /** Persisted destination visibility. Undefined means no destination row exists. */
+    visibility?: ConversationPrivacy;
 }
 /** Persist and read durable conversation metadata for reporting surfaces. */
 export interface ConversationStore {
     get(args: {
         conversationId: string;
     }): Promise<Conversation | undefined>;
+    /** Read persisted visibility for one destination. Missing rows fail closed. */
+    getDestinationVisibility(args: {
+        provider: string;
+        providerDestinationId: string;
+        providerTenantId?: string;
+    }): Promise<ConversationPrivacy | undefined>;
     recordActivity(args: {
         activityAtMs?: number;
         channelName?: string;
@@ -36,6 +45,8 @@ export interface ConversationStore {
         requester?: StoredSlackRequester;
         source?: ConversationSource;
         title?: string;
+        /** Source-confirmed visibility from the current event's signal only. */
+        visibility?: ConversationPrivacy;
     }): Promise<void>;
     /** Store task-execution metadata for long-term conversation history. */
     recordExecution(args: {
@@ -49,6 +60,8 @@ export interface ConversationStore {
         source?: ConversationSource;
         title?: string;
         updatedAtMs: number;
+        /** Source-confirmed visibility from the current event's signal only. */
+        visibility?: ConversationPrivacy;
     }): Promise<void>;
     listByActivity(args?: {
         limit?: number;

package/dist/chat/ingress/message-changed.d.ts

@@ -16,7 +16,9 @@ interface SlackMessageChangedEvent {
         type: "message";
         subtype: "message_changed";
         channel: string;
+        channel_type?: string;
         message: {
+            bot_id?: string;
             files?: SlackEditedMessageFile[];
             source_team?: string;
             text?: string;

package/dist/chat/no-reply.d.ts

@@ -0,0 +1,7 @@
+export declare const NO_REPLY_MARKER = "[[NO_REPLY]]";
+/** Detect the reserved marker so Slack side effects can intentionally complete without thread text. */
+export declare function isNoReplyMarker(text: string): boolean;
+/** Detect marker leaks before publication strips or rejects them. */
+export declare function containsNoReplyMarker(text: string): boolean;
+/** Remove the reserved marker from mixed assistant text so it is never shown to users. */
+export declare function stripNoReplyMarker(text: string): string;

package/dist/chat/respond.d.ts

@@ -72,7 +72,7 @@ export interface ReplyRequestContext {
         webSearch?: WebSearchToolDeps;
     };
     onStatus?: (status: AssistantStatusSpec) => void | Promise<void>;
-    drainSteeringMessages?: (inject: (messages: ReplySteeringMessage[]) => Promise<void>) => Promise<ReplySteeringMessage[]>;
+    drainSteeringMessages?: (accept: (messages: ReplySteeringMessage[]) => Promise<void>) => Promise<ReplySteeringMessage[]>;
     /** Return true when the durable worker should pause at the next Pi boundary. */
     shouldYield?: () => boolean;
     recordPendingAuth?: (pendingAuth: ConversationPendingAuthState) => void | Promise<void>;
@@ -97,5 +97,11 @@ export interface ReplySteeringMessage {
     timestampMs?: number;
     userAttachments?: ReplyRequestAttachment[];
 }
+/**
+ * Convert a mid-run user message into the Pi user message shape used for
+ * steering injection and parked-conversation session-log appends, so both
+ * paths store identical durable history.
+ */
+export declare function buildSteeringPiMessage(message: ReplySteeringMessage): PiMessage;
 /** Run a full agent turn: discover skills, execute tools, and return the assistant reply. */
 export declare function generateAssistantReply(messageText: string, context: AssistantReplyRequestContext): Promise<AssistantReply>;

package/dist/chat/runtime/reply-executor.d.ts

@@ -1,11 +1,3 @@
-/**
- * Slack reply execution boundary.
- *
- * This module bridges prepared Slack thread state into `generateAssistantReply`
- * and commits the resulting Slack-visible delivery/state updates. It is where
- * queued messages, compaction, status updates, and Slack posting meet; agent
- * internals stay behind the reply generator.
- */
 import type { Message, Thread } from "chat";
 import type { SlackAdapter } from "@chat-adapter/slack";
 import { type Destination } from "@sentry/junior-plugin-api";
@@ -54,13 +46,13 @@ export declare function createReplyToThread(deps: ReplyExecutorDeps): (thread: T
     beforeFirstResponsePost?: () => Promise<void>;
     destination: Destination;
     explicitMention?: boolean;
-    onInputCommitted?: () => Promise<void>;
+    ack?: () => Promise<void>;
     onToolInvocation?: (invocation: TurnToolInvocation) => void;
     onTurnCompleted?: () => Promise<void>;
     onTurnStatePersisted?: () => Promise<void>;
     preparedState?: PreparedTurnState;
     queuedMessages?: QueuedTurnMessage[];
-    drainSteeringMessages?: (inject: (messages: QueuedTurnMessage[]) => Promise<void>, context?: {
+    drainSteeringMessages?: (accept: (messages: QueuedTurnMessage[]) => Promise<void>, context?: {
         conversationContext?: string;
     }) => Promise<QueuedTurnMessage[]>;
     shouldYield?: () => boolean;

package/dist/chat/runtime/slack-runtime.d.ts

@@ -26,11 +26,12 @@ export interface SteeringCandidateMessage {
 }
 export interface ReplyHooks {
     beforeFirstResponsePost?: () => Promise<void>;
-    drainSteeringMessages?: (inject: (messages: SteeringCandidateMessage[]) => Promise<readonly string[] | void>) => Promise<void>;
+    drainSteeringMessages?: (accept: (messages: SteeringCandidateMessage[]) => Promise<readonly string[] | void>) => Promise<void>;
     messageContext?: MessageContext;
-    onInputCommitted?: () => Promise<void>;
+    ack?: () => Promise<void>;
     onToolInvocation?: (invocation: TurnToolInvocation) => void;
     onTurnStatePersisted?: () => Promise<void>;
+    isFinalAttempt?: boolean;
     shouldYield?: () => boolean;
 }
 interface SteeringDrainContext {
@@ -90,13 +91,13 @@ export interface SlackTurnRuntimeDependencies<TPreparedState> {
         beforeFirstResponsePost?: () => Promise<void>;
         destination: Destination;
         explicitMention?: boolean;
-        onInputCommitted?: () => Promise<void>;
+        ack?: () => Promise<void>;
         onToolInvocation?: (invocation: TurnToolInvocation) => void;
         onTurnCompleted?: () => Promise<void>;
         onTurnStatePersisted?: () => Promise<void>;
         preparedState?: TPreparedState;
         queuedMessages?: QueuedTurnMessage[];
-        drainSteeringMessages?: (inject: (messages: QueuedTurnMessage[]) => Promise<void>, context?: SteeringDrainContext) => Promise<QueuedTurnMessage[]>;
+        drainSteeringMessages?: (accept: (messages: QueuedTurnMessage[]) => Promise<void>, context?: SteeringDrainContext) => Promise<QueuedTurnMessage[]>;
         shouldYield?: () => boolean;
     }) => Promise<void>;
     decideSubscribedReply: SubscribedReplyPolicy;

package/dist/chat/runtime/turn.d.ts

@@ -51,6 +51,13 @@ export declare class TurnInputCommitLostError extends Error {
 }
 /** Return whether an error means the durable worker lost input ownership. */
 export declare function isTurnInputCommitLostError(error: unknown): error is TurnInputCommitLostError;
+/** Error indicating durable turn input should stay pending for a later worker. */
+export declare class TurnInputDeferredError extends Error {
+    readonly code = "turn_input_deferred";
+    constructor(message?: string);
+}
+/** Return whether an error means the durable worker should redeliver input later. */
+export declare function isTurnInputDeferredError(error: unknown): error is TurnInputDeferredError;
 /** Mark a turn as the active turn in conversation state. */
 export declare function startActiveTurn(args: {
     conversation: ThreadConversationState;

package/dist/chat/services/persist-retry.d.ts

@@ -0,0 +1,2 @@
+/** Retry a delivered-state persist briefly before surfacing the failure. */
+export declare function persistWithRetry(persist: () => Promise<void>): Promise<void>;

package/dist/chat/services/reply-delivery-plan.d.ts

@@ -5,10 +5,6 @@ export interface ReplyDeliveryPlan {
     postThreadText: boolean;
     attachFiles: ReplyFileDelivery;
 }
-/** Check if text is a short acknowledgment (emoji, "ok", etc.) that a reaction already covers. */
-export declare function isRedundantReactionAckText(text: string): boolean;
-/** Check if the user asked for a reaction without also asking for text. */
-export declare function isReactionOnlyIntent(text: string): boolean;
 /** Determine how a reply should be delivered (thread vs channel, file handling). */
 export declare function buildReplyDeliveryPlan(args: {
     explicitChannelPostIntent: boolean;

package/dist/chat/services/turn-session-record.d.ts

@@ -1,4 +1,5 @@
 import { type AgentTurnSessionRecord, type AgentTurnSurface } from "@/chat/state/turn-session";
+import type { ConversationPrivacy } from "@/chat/conversation-privacy";
 import type { Destination, Requester, Source } from "@sentry/junior-plugin-api";
 import type { PiMessage } from "@/chat/pi/messages";
 import { type AgentTurnUsage } from "@/chat/usage";
@@ -38,16 +39,26 @@ export declare function persistRunningSessionRecord(args: {
     surface?: AgentTurnSurface;
     turnStartMessageIndex?: number;
 }): Promise<boolean>;
-/** Persist a completed turn session record. */
+/**
+ * Commit the delivered final reply as the terminal completed session record.
+ *
+ * Generation completing is not delivery: call this only after the destination
+ * accepted the visible final reply, so an undelivered assistant reply never
+ * becomes durable conversation history or a terminal completed state. Failures
+ * are logged and swallowed because the reply is already user-visible.
+ */
 export declare function persistCompletedSessionRecord(args: {
     channelName?: string;
     conversationId: string;
     currentDurationMs?: number;
     currentUsage?: AgentTurnUsage;
     destination?: Destination;
+    /** Source-confirmed destination visibility from the current event's signal. */
+    destinationVisibility?: ConversationPrivacy;
     source?: Source;
     sessionId: string;
-    sliceId: number;
+    /** Defaults to the latest stored slice when the deliverer does not know it. */
+    sliceId?: number;
     allMessages: PiMessage[];
     loadedSkillNames?: string[];
     logContext: SessionRecordLogContext;
@@ -55,6 +66,24 @@ export declare function persistCompletedSessionRecord(args: {
     surface?: AgentTurnSurface;
     turnStartMessageIndex?: number;
 }): Promise<void>;
+/** Complete a delivered single-slice run with an explicit session boundary. */
+export declare function completeDeliveredTurn(args: {
+    channelName?: string;
+    conversationId: string;
+    destination: Destination;
+    destinationVisibility?: ConversationPrivacy;
+    durationMs?: number;
+    loadedSkillNames?: string[];
+    logContext: SessionRecordLogContext;
+    messages: PiMessage[];
+    requester?: Requester;
+    sessionId: string;
+    sliceId: number;
+    source: Source;
+    surface: AgentTurnSurface;
+    turnStartMessageIndex?: number;
+    usage?: AgentTurnUsage;
+}): Promise<void>;
 /**
  * Persist an auth-pause session record. Returns the durable record only when
  * the caller can safely hand the user to an authorization resume flow.

package/dist/chat/slack/client.d.ts

@@ -28,18 +28,49 @@ export declare class SlackActionError extends Error {
 interface SlackRetryContext {
     action?: string;
     attributes?: Record<string, string | number | boolean>;
+    /**
+     * Whether repeating the operation cannot produce a duplicate user-visible
+     * effect (reads, deletes, reactions). Request timeouts are ambiguous — Slack
+     * may have accepted the write — so they are only retried when the caller
+     * marks the operation idempotent. Defaults to false (never risk a duplicate
+     * post).
+     */
+    idempotent?: boolean;
     /** Extra attributes forwarded onto the per-attempt Sentry span. */
     spanAttributes?: Record<string, string | number | boolean>;
 }
 /** Extract a header value by case-insensitive name from a raw headers object. */
 export declare function getHeaderString(headers: unknown, name: string): string | undefined;
+/**
+ * Bind a workspace installation token for all Slack Web API calls inside
+ * `fn`, so multi-workspace outbound writes use the destination workspace's
+ * credentials rather than the env fallback token.
+ */
+export declare function runWithSlackInstallationToken<T>(token: string, fn: () => T): T;
 export declare function normalizeSlackConversationId(channelId: string | undefined): string | undefined;
+/**
+ * Run a Slack Web API call with bounded retries so transient platform
+ * failures do not surface as turn failures, while non-idempotent posts are
+ * never re-sent when Slack may already have accepted them.
+ *
+ * Retry classes: rate limits (bounded Retry-After), connection-phase network
+ * failures, and Slack 5xx responses always retry; request timeouts retry only
+ * when the caller marks the operation `idempotent`.
+ */
 export declare function withSlackRetries<T>(task: () => Promise<T>, maxAttempts?: number, context?: SlackRetryContext): Promise<T>;
+/**
+ * Slack Web API client for the current destination workspace: the ambient
+ * installation token when one is bound, otherwise the env bot token for
+ * single-workspace deployments. Fails instead of falling back when the call
+ * is workspace-scoped and no installation token can be resolved, so a write
+ * never goes out with another workspace's credentials.
+ */
 export declare function getSlackClient(): WebClient;
 /**
  * Slack channel ID prefixes:
- * - C: public channel
- * - G: private channel / group DM
+ * - C: channel — modern private channels also use C, so the prefix never
+ *   proves a channel is public
+ * - G: legacy private channel / group DM
  * - D: direct message (1:1)
  */
 export declare function isDmChannel(channelId: string): boolean;

package/dist/chat/slack/conversation-context.d.ts

@@ -2,11 +2,26 @@
 export type SlackEventChannelType = "channel" | "group" | "mpim" | "im";
 /** Slack conversation categories Junior can share with agents. */
 export type SlackConversationType = "public_channel" | "private_channel" | "group_dm" | "direct_message" | "private_channel_or_group_dm";
+/** Conversation visibility classification derived from source-provided signals. */
+export type SlackConversationVisibility = "public" | "private";
 /** Slack conversation facts available to the bot for runtime context. */
 export interface SlackConversationContext {
     type: SlackConversationType;
     name?: string;
+    /**
+     * Visibility proven by a source signal (`channel_type`) or narrowed toward
+     * private by a `D`/`G` id prefix. Undefined for `C`-prefixed conversations
+     * without a signal, which may be public or private.
+     */
+    visibility?: SlackConversationVisibility;
 }
+/**
+ * Map Slack's Events API channel_type to a source-confirmed visibility.
+ *
+ * This is the only mapping allowed to classify a Slack conversation public;
+ * channel-id prefixes may only narrow classification toward private.
+ */
+export declare function conversationVisibilityFromSlackChannelType(channelType: SlackEventChannelType | undefined): SlackConversationVisibility | undefined;
 /** Resolve Slack's raw event channel type from a Chat SDK message-like object. */
 export declare function resolveSlackChannelTypeFromMessage(message: unknown): SlackEventChannelType | undefined;
 /** Build Slack conversation facts available to runtime consumers. */

package/dist/chat/state/turn-session.d.ts

@@ -2,6 +2,7 @@ import { type Destination, type Source } from "@sentry/junior-plugin-api";
 import type { PiMessage } from "@/chat/pi/messages";
 import { type Requester } from "@/chat/requester";
 import type { AgentTurnUsage } from "@/chat/usage";
+import type { ConversationPrivacy } from "@/chat/conversation-privacy";
 import type { ConversationStore } from "@/chat/conversations/store";
 export type AgentTurnSessionStatus = "running" | "awaiting_resume" | "completed" | "failed" | "abandoned";
 export type AgentTurnSurface = "slack" | "api" | "scheduler" | "internal";
@@ -40,6 +41,8 @@ export declare function upsertAgentTurnSessionRecord(args: {
     cumulativeDurationMs?: number;
     cumulativeUsage?: AgentTurnUsage;
     destination?: Destination;
+    /** Source-confirmed destination visibility from the current event's signal. */
+    destinationVisibility?: ConversationPrivacy;
     source?: Source;
     lastProgressAtMs?: number;
     loadedSkillNames?: string[];
@@ -64,6 +67,12 @@ export declare function recordAgentTurnSessionSummary(args: {
     cumulativeDurationMs?: number;
     cumulativeUsage?: AgentTurnUsage;
     destination?: Destination;
+    /**
+     * Source-confirmed destination visibility from the current event's signal
+     * (Slack `channel_type`). Leave unset when no live signal exists so an
+     * existing destination visibility is not overwritten.
+     */
+    destinationVisibility?: ConversationPrivacy;
     source?: Source;
     lastProgressAtMs?: number;
     loadedSkillNames?: string[];

package/dist/chat/task-execution/queue.d.ts

@@ -3,7 +3,7 @@ export interface ConversationQueueMessage {
     conversationId: string;
     destination: Destination;
 }
-export type ConversationQueueMessageRejectReason = "destination_mismatch" | "expired" | "malformed" | "signature_mismatch";
+export type ConversationQueueMessageRejectReason = "destination_mismatch" | "expired" | "invalid_record" | "malformed" | "signature_mismatch";
 export declare class ConversationQueueMessageRejectedError extends Error {
     conversationId?: string;
     reason: ConversationQueueMessageRejectReason;

package/dist/chat/task-execution/slack-work.d.ts

@@ -1,6 +1,6 @@
 import type { SlackAdapter } from "@chat-adapter/slack";
 import { Message, ThreadImpl, type SerializedMessage, type SerializedThread, type StateAdapter } from "chat";
-import type { SlackTurnRuntime } from "@/chat/runtime/slack-runtime";
+import type { SlackTurnOptions } from "@/chat/runtime/slack-runtime";
 import type { ConversationStore } from "@/chat/conversations/store";
 import type { InboundMessage } from "@/chat/task-execution/store";
 import type { ConversationWorkerContext, ConversationWorkerResult } from "@/chat/task-execution/worker";
@@ -15,6 +15,14 @@ export interface SlackConversationMessageMetadata {
     route: SlackConversationRoute;
     thread: SerializedThread;
 }
+type SlackInboxTurnOptions = SlackTurnOptions & {
+    ack: () => Promise<void>;
+    isFinalAttempt: boolean;
+};
+interface SlackInboxTurnRuntime {
+    handleNewMention(thread: ThreadImpl, message: Message, hooks: SlackInboxTurnOptions): Promise<void>;
+    handleSubscribedMessage(thread: ThreadImpl, message: Message, hooks: SlackInboxTurnOptions): Promise<void>;
+}
 interface SlackResourceEventInboundInput {
     event: {
         eventKey: string;
@@ -39,7 +47,7 @@ export interface CreateSlackConversationWorkerOptions {
     lookupSlackUser?: (teamId: string, userId: string) => Promise<SlackRequesterProfile | null | undefined>;
     resumeAwaitingContinuation: (conversationId: string) => Promise<boolean>;
     conversationStore?: ConversationStore;
-    runtime: Pick<SlackTurnRuntime<unknown>, "handleNewMention" | "handleSubscribedMessage">;
+    runtime: SlackInboxTurnRuntime;
     state?: StateAdapter;
 }
 /** Create a Slack mailbox record for a subscribed resource-event notification. */

package/dist/chat/task-execution/state.d.ts

@@ -1,11 +1,17 @@
 import type { StateAdapter } from "chat";
 import type { Destination } from "@sentry/junior-plugin-api";
 import { type StoredSlackRequester } from "@/chat/requester";
+declare class InvalidConversationRecordError extends Error {
+    constructor(conversationId: string);
+}
+/** Return whether an error means a stored conversation record failed validation. */
+export declare function isInvalidConversationRecordError(error: unknown): error is InvalidConversationRecordError;
 export declare const CONVERSATION_BY_ACTIVITY_INDEX_KEY = "junior:conversation:by-activity";
 export declare const CONVERSATION_ACTIVE_INDEX_KEY = "junior:conversation:active";
 export declare const CONVERSATION_WORK_LEASE_TTL_MS = 90000;
 export declare const CONVERSATION_WORK_CHECK_IN_INTERVAL_MS = 15000;
 export declare const CONVERSATION_WORK_STALE_ENQUEUE_MS = 60000;
+export declare const CONVERSATION_WORK_MAX_DELIVERY_ATTEMPTS = 5;
 export type Source = "api" | "internal" | "local" | "plugin" | "resource_event" | "scheduler" | "slack";
 export type ExecutionStatus = "awaiting_resume" | "failed" | "idle" | "pending" | "running";
 export interface AgentInput {
@@ -15,6 +21,7 @@ export interface AgentInput {
     text: string;
 }
 export interface InboundMessage {
+    attemptCount?: number;
     conversationId: string;
     createdAtMs: number;
     destination: Destination;
@@ -88,6 +95,8 @@ export interface AppendAndEnqueueInboundMessageResult extends AppendInboundMessa
 export interface RequestConversationWorkResult {
     status: "created" | "updated";
 }
+/** Whether this is the final attempt before an unacked message is dead-lettered. */
+export declare function isFinalAttempt(message: Pick<InboundMessage, "attemptCount">): boolean;
 /** Return a persisted conversation record, if one exists. */
 export declare function getConversation(args: {
     conversationId: string;
@@ -176,17 +185,17 @@ export declare function checkInConversationWork(args: {
  * Drain pending mailbox entries after the caller acknowledges durable handling.
  *
  * Returning ids acknowledges only that subset; returning nothing acknowledges
- * every offered pending entry.
+ * every pending entry passed to the handler.
  */
 export declare function drainConversationMailbox(args: {
     conversationId: string;
-    inject: (messages: InboundMessage[]) => Promise<readonly string[] | void>;
+    handle: (messages: InboundMessage[]) => Promise<readonly string[] | void>;
     leaseToken: string;
     nowMs?: number;
     state?: StateAdapter;
 }): Promise<InboundMessage[]>;
-/** Mark selected leased mailbox entries after their session-log injection succeeds. */
-export declare function markConversationMessagesInjected(args: {
+/** Acknowledge leased mailbox entries after the handler accepts responsibility. */
+export declare function ackMessages(args: {
     conversationId: string;
     inboundMessageIds: string[];
     leaseToken: string;
@@ -215,6 +224,36 @@ export declare function completeConversationWork(args: {
     nowMs?: number;
     state?: StateAdapter;
 }): Promise<"completed" | "lost_lease" | "pending">;
+/** Failure outcome: `lost_lease` (another owner took over), `recorded` (attempt counted), or `skipped` (durable progress was made). */
+export interface AttemptFailure {
+    pendingCount: number;
+    deadLetteredMessages: InboundMessage[];
+    status: "lost_lease" | "recorded" | "skipped";
+}
+/**
+ * Record one failed delivery attempt for the pending messages a run attempted,
+ * dead-lettering messages that reach the retry limit so a deterministic
+ * failure cannot requeue forever.
+ *
+ * Attempts are counted only when the run made no durable progress: if any
+ * attempted message left the mailbox, the remaining pending entries may be
+ * deliberate deferrals and are left untouched. Consumed message ids stay in
+ * `inboundMessageIds` so source retries remain duplicates.
+ */
+export declare function recordAttemptFailure(args: {
+    conversationId: string;
+    inboundMessageIds: string[];
+    leaseToken: string;
+    nowMs?: number;
+    state?: StateAdapter;
+}): Promise<AttemptFailure>;
+/** Record a terminal failure completion for a leased conversation. */
+export declare function deadLetterAttempt(args: {
+    conversationId: string;
+    leaseToken: string;
+    nowMs?: number;
+    state?: StateAdapter;
+}): Promise<"failed" | "lost_lease" | "pending">;
 /** Clear an expired durable lease so a later worker can resume safely. */
 export declare function clearExpiredConversationLease(args: {
     conversationId: string;
@@ -238,3 +277,4 @@ export declare function listConversationsByActivity(args?: {
     offset?: number;
     state?: StateAdapter;
 }): Promise<Conversation[]>;
+export {};

package/dist/chat/task-execution/store.d.ts

@@ -2,7 +2,7 @@ import type { StateAdapter } from "chat";
 import type { ConversationStore } from "@/chat/conversations/store";
 import type { ConversationWorkQueue } from "./queue";
 import * as workState from "./state";
-export { CONVERSATION_ACTIVE_INDEX_KEY, CONVERSATION_BY_ACTIVITY_INDEX_KEY, CONVERSATION_WORK_CHECK_IN_INTERVAL_MS, CONVERSATION_WORK_LEASE_TTL_MS, CONVERSATION_WORK_STALE_ENQUEUE_MS, type AgentInput, type AppendAndEnqueueInboundMessageResult, type AppendInboundMessageResult, type Conversation, type ConversationExecution, type ConversationWorkLease, type ConversationWorkState, type ExecutionStatus, type InboundMessage, type Lease, type RequestConversationWorkResult, type Source, type StartConversationWorkAcquired, type StartConversationWorkActive, type StartConversationWorkNoWork, type StartConversationWorkResult, } from "@/chat/task-execution/state";
+export { CONVERSATION_ACTIVE_INDEX_KEY, CONVERSATION_BY_ACTIVITY_INDEX_KEY, CONVERSATION_WORK_CHECK_IN_INTERVAL_MS, CONVERSATION_WORK_LEASE_TTL_MS, CONVERSATION_WORK_MAX_DELIVERY_ATTEMPTS, CONVERSATION_WORK_STALE_ENQUEUE_MS, isFinalAttempt, isInvalidConversationRecordError, type AgentInput, type AttemptFailure, type AppendAndEnqueueInboundMessageResult, type AppendInboundMessageResult, type Conversation, type ConversationExecution, type ConversationWorkLease, type ConversationWorkState, type ExecutionStatus, type InboundMessage, type Lease, type RequestConversationWorkResult, type Source, type StartConversationWorkAcquired, type StartConversationWorkActive, type StartConversationWorkNoWork, type StartConversationWorkResult, } from "@/chat/task-execution/state";
 import type { AppendAndEnqueueInboundMessageResult, Conversation, InboundMessage } from "@/chat/task-execution/state";
 export type EnsureConversationWakeResult = {
     queueMessageId?: string;
@@ -90,13 +90,13 @@ export declare function checkInConversationWork(args: {
     nowMs?: number;
     state?: StateAdapter;
 }): Promise<boolean>;
-/** Drain pending mailbox entries after the caller has durably injected them. */
+/** Drain pending mailbox entries after the caller accepts responsibility. */
 export declare function drainConversationMailbox(args: Parameters<typeof workState.drainConversationMailbox>[0] & {
     conversationStore?: ConversationStore;
     state?: StateAdapter;
 }): Promise<workState.InboundMessage[]>;
-/** Mark selected leased mailbox entries after their session-log injection succeeds. */
-export declare function markConversationMessagesInjected(args: {
+/** Acknowledge leased mailbox entries after the handler accepts responsibility. */
+export declare function ackMessages(args: {
     conversationId: string;
     inboundMessageIds: string[];
     leaseToken: string;
@@ -129,6 +129,23 @@ export declare function completeConversationWork(args: {
     nowMs?: number;
     state?: StateAdapter;
 }): Promise<"pending" | "completed" | "lost_lease">;
+/** Record one failed delivery attempt and dead-letter messages at their limit. */
+export declare function recordAttemptFailure(args: {
+    conversationId: string;
+    inboundMessageIds: string[];
+    leaseToken: string;
+    conversationStore?: ConversationStore;
+    nowMs?: number;
+    state?: StateAdapter;
+}): Promise<workState.AttemptFailure>;
+/** Record a terminal failure completion for a leased conversation. */
+export declare function deadLetterAttempt(args: {
+    conversationId: string;
+    leaseToken: string;
+    conversationStore?: ConversationStore;
+    nowMs?: number;
+    state?: StateAdapter;
+}): Promise<"pending" | "failed" | "lost_lease">;
 /** Clear an expired durable lease so a later worker can resume safely. */
 export declare function clearExpiredConversationLease(args: {
     conversationId: string;

package/dist/chat/task-execution/worker.d.ts

@@ -6,18 +6,25 @@ import { type InboundMessage } from "./store";
 export declare const CONVERSATION_WORK_DEFER_DELAY_MS = 15000;
 export declare const CONVERSATION_WORK_SOFT_YIELD_AFTER_MS = 240000;
 export interface ConversationWorkerContext {
+    attempt: InboxAttempt;
     checkIn(): Promise<boolean>;
     conversationId: string;
     destination: Destination;
-    drainMailbox(inject: (messages: InboundMessage[]) => Promise<readonly string[] | void>): Promise<InboundMessage[]>;
-    leaseToken: string;
     shouldYield(): boolean;
 }
+export interface InboxAttempt {
+    ack(): Promise<void>;
+    conversationId: string;
+    destination: Destination;
+    drain(handle: (messages: InboundMessage[]) => Promise<readonly string[] | void>): Promise<InboundMessage[]>;
+    isFinalAttempt: boolean;
+    messages: InboundMessage[];
+}
 export interface ConversationWorkerResult {
-    status: "completed" | "lost_lease" | "yielded";
+    status: "completed" | "deferred" | "lost_lease" | "yielded";
 }
 export interface ConversationWorkProcessResult {
-    status: "active" | "completed" | "lost_lease" | "no_work" | "pending_requeued" | "yielded";
+    status: "active" | "completed" | "failed" | "lost_lease" | "no_work" | "pending_requeued" | "yielded";
 }
 export interface ProcessConversationWorkOptions {
     checkInIntervalMs?: number;