crewly 1.20.105 → 1.20.107

package/dist/cli/backend/src/services/v3/ticket-channel-hooks.d.ts

@@ -0,0 +1,279 @@
+/**
+ * Ticket loop — per-channel glue (specs/ticket-loop.md, Phase 1 §2).
+ *
+ * The intake service is channel-agnostic; this module holds what the channel
+ * call sites share:
+ *
+ * - conversation / thread refs (`slack:<channel>:<root>`, `chatv2:<channel>:<root>`)
+ *   so a follow-up finds its thread's ticket and a top-level "不用记" finds
+ *   the latest ticket of its conversation;
+ * - the owner test for chat-v2 rows (PR #786's authorship markers);
+ * - the line added to a delivered message (`[TICKET:TKT-123 <id>] …`);
+ * - a bounded wait on intake, so a slow disk never holds a message back;
+ * - the two receipt sinks (Slack thread reply, chat-v2 system row).
+ *
+ * @module services/v3/ticket-channel-hooks
+ */
+import type { Request } from '../../types/v2/request.types.js';
+import type { SlackBlock, SlackOutgoingMessage } from '../../types/slack.types.js';
+import type { ChatChannelDTO, ChatMessageDTO } from '../chat-v2/types.js';
+import type { TicketOriginChannel } from '../../types/v2/ticket.types.js';
+import type { IntakeMessage, IntakeOutcome, TicketIntakeService, TicketReceiptSink } from './ticket-intake.service.js';
+/**
+ * Conversation ref of a Slack channel or DM.
+ *
+ * @param slackChannelId - Slack conversation id
+ * @returns `slack:<channel>`
+ */
+export declare function slackConversationRef(slackChannelId: string): string;
+/**
+ * Thread ref of a Slack thread (a top-level message is its own thread root).
+ *
+ * @param slackChannelId - Slack conversation id
+ * @param threadRootTs - Thread root ts
+ * @returns `slack:<channel>:<root ts>`
+ */
+export declare function slackThreadRef(slackChannelId: string, threadRootTs: string): string;
+/**
+ * Conversation ref of a chat-v2 channel.
+ *
+ * @param chatChannelId - chat-v2 channel id
+ * @returns `chatv2:<channel>`
+ */
+export declare function chatV2ConversationRef(chatChannelId: string): string;
+/**
+ * Thread ref of a chat-v2 thread (a root message is its own thread).
+ *
+ * @param chatChannelId - chat-v2 channel id
+ * @param rootMessageId - Thread root message id
+ * @returns `chatv2:<channel>:<root id>`
+ */
+export declare function chatV2ThreadRef(chatChannelId: string, rootMessageId: string): string;
+/**
+ * Whether a chat-v2 row carries the owner's own words.
+ *
+ * Mirrors the commitment gate's read (PR #786): a `user` row counts only when
+ * no agent authorship marker is set and its source is not an agent-reply
+ * source. A colleague agent's Slack post and an agent calling a user-turn API
+ * are stored as `user` rows but carry the marker.
+ *
+ * @param message - Persisted chat-v2 message
+ * @returns True for the owner's message
+ */
+export declare function isOwnerChatMessage(message: Pick<ChatMessageDTO, 'senderType' | 'metadata'>): boolean;
+/**
+ * The ticket a delivered message belongs to, from an intake outcome.
+ *
+ * @param outcome - Intake outcome (or null when intake did not run)
+ * @returns The ticket, or null
+ */
+export declare function ticketOfOutcome(outcome: IntakeOutcome | null): Request | null;
+/**
+ * The line added to a message delivered to an agent: the machine-readable
+ * marker plus how to link work to it.
+ *
+ * @param ticket - The ticket (null → '')
+ * @returns The line, or '' when there is no numbered ticket
+ */
+export declare function ticketDeliveryLine(ticket: Pick<Request, 'id' | 'ticketNumber'> | null): string;
+/**
+ * Append the ticket line to a text delivered through the message queue.
+ *
+ * @param text - Text to deliver
+ * @param ticket - Its ticket, if any
+ * @returns The text, with the ticket line appended when there is one
+ */
+export declare function appendTicketLine(text: string, ticket: Pick<Request, 'id' | 'ticketNumber'> | null): string;
+/**
+ * A copy of a chat-v2 message carrying the ticket line in its metadata, for
+ * the dispatcher to render into the agent's prompt. The persisted row is not
+ * changed.
+ *
+ * @param message - Persisted message
+ * @param ticket - Its ticket, if any
+ * @returns The same message when there is no ticket, else a copy
+ */
+export declare function withTicketMarker(message: ChatMessageDTO, ticket: Pick<Request, 'id' | 'ticketNumber'> | null): ChatMessageDTO;
+/**
+ * The ticket line a dispatcher should render for a message (see {@link withTicketMarker}).
+ *
+ * @param message - Message about to be dispatched
+ * @returns The line, or undefined
+ */
+export declare function ticketLineOf(message: Pick<ChatMessageDTO, 'metadata'>): string | undefined;
+/**
+ * Run intake, but give up waiting after {@link TICKET_CONSTANTS.INTAKE_TIMEOUT_MS}.
+ * Intake keeps running in the background (the ticket and its receipt still
+ * appear); only the delivered copy goes out without the marker.
+ *
+ * @param intake - The intake service, or null when not wired
+ * @param message - The message
+ * @param timeoutMs - Override for tests
+ * @returns The outcome, or null when intake is not wired or timed out
+ */
+export declare function intakeWithin(intake: Pick<TicketIntakeService, 'intakeWithOutcome'> | null, message: IntakeMessage, timeoutMs?: number): Promise<IntakeOutcome | null>;
+/**
+ * Receipt text for a new ticket.
+ *
+ * @param ticket - The ticket
+ * @param withButton - Whether a dismiss button is shown next to it
+ * @returns `已记成 TKT-123 · 不用记？回复「不用记」`
+ */
+export declare function receiptText(ticket: Pick<Request, 'ticketNumber'>, withButton?: boolean): string;
+/**
+ * Receipt text after "不用记".
+ *
+ * @param ticket - The ticket
+ * @returns `TKT-123 已取消记录`
+ */
+export declare function dismissedReceiptText(ticket: Pick<Request, 'ticketNumber'>): string;
+/** The slice of SlackService the Slack receipt sink uses. */
+export interface ReceiptSlackApi {
+    sendMessage(message: SlackOutgoingMessage): Promise<string>;
+    updateMessage(channelId: string, messageTs: string, text: string, blocks?: SlackBlock[], botToken?: string): Promise<void>;
+    /** True when button clicks reach this process (socket mode with a Bolt app) */
+    supportsInteractivity?(): boolean;
+}
+/** Slack receipt sink dependencies. */
+export interface SlackReceiptSinkDeps {
+    slack: ReceiptSlackApi;
+    /** Bot token of an agent's own Slack app, when it has one */
+    botTokenFor?: (agentSession: string) => string | undefined;
+}
+/**
+ * Block Kit body of a receipt with the dismiss button.
+ *
+ * @param ticket - The ticket
+ * @returns Blocks
+ */
+export declare function slackReceiptBlocks(ticket: Pick<Request, 'id' | 'ticketNumber'>): SlackBlock[];
+/**
+ * Receipts as a reply in the Slack thread the owner wrote in, through the same
+ * SlackService the channel already posts with. The dismiss button is added
+ * only when button clicks reach this process (socket mode); on the Cloud
+ * transport they do not, and the receipt tells the owner to reply 「不用记」.
+ *
+ * @param deps - Slack API and bot-token lookup
+ * @returns The sink
+ */
+export declare function createSlackReceiptSink(deps: SlackReceiptSinkDeps): TicketReceiptSink;
+/** The slice of ChatV2Service the chat-v2 receipt sink uses. */
+export interface ReceiptChatApi {
+    recordTurn(input: {
+        channelId: string;
+        senderType: 'system';
+        senderId: string;
+        content: string;
+        contentType?: 'system_note';
+        threadId?: string;
+        metadata: {
+            source: 'system';
+            [key: string]: unknown;
+        };
+    }): {
+        message: ChatMessageDTO;
+    };
+    updateSystemMessage(messageId: string, content: string, metadataPatch?: Record<string, unknown>): ChatMessageDTO | null;
+}
+/** chat-v2 receipt sink dependencies. */
+export interface ChatV2ReceiptSinkDeps {
+    chat: ReceiptChatApi;
+    /** Push a row to live views (the chat-v2 WebSocket gateway), when wired */
+    broadcast?: (message: ChatMessageDTO) => void;
+}
+/**
+ * Receipts as a system row under the owner's chat-v2 message. The row's
+ * metadata names the ticket and the dismiss endpoint, so a client can render
+ * a button; replying 「不用记」 works everywhere.
+ *
+ * @param deps - chat-v2 API and optional broadcaster
+ * @returns The sink
+ */
+export declare function createChatV2ReceiptSink(deps: ChatV2ReceiptSinkDeps): TicketReceiptSink;
+/**
+ * Canonical chat-v2 sourceConversationItemId the SLA subscriber parses
+ * (`chatv2-<channel>__<message>`). `__` because channel and message ids are
+ * UUIDs with dashes in them.
+ *
+ * @param channelId - chat-v2 channel id
+ * @param messageId - chat-v2 message id
+ * @returns The source id
+ */
+export declare function buildChatV2SourceId(channelId: string, messageId: string): string;
+/**
+ * Source id for a chat-v2 ticket NOT routed to the orchestrator. A different
+ * prefix on purpose: the SLA subscriber closes any open Request whose source
+ * starts with `chatv2-` as soon as an agent replies in that channel, which is
+ * right for the orc's respond-to-user tracking and wrong for a ticket.
+ *
+ * @param channelId - chat-v2 channel id
+ * @param messageId - chat-v2 message id
+ * @returns `chatv2t-<channel>__<message>`
+ */
+export declare function buildChatV2TicketSourceId(channelId: string, messageId: string): string;
+/**
+ * Whether a chat-v2 channel is the owner's DM with the orchestrator — the
+ * only chat-v2 channel whose tickets keep the SLA (`chat-v2` tag).
+ *
+ * @param channel - The channel
+ * @returns True for the orc DM
+ */
+export declare function isOrchestratorRoutedChatV2Channel(channel: Pick<ChatChannelDTO, 'type' | 'agentSession'>): boolean;
+/**
+ * Build the intake message for an owner's chat-v2 message.
+ *
+ * @param channel - Its channel
+ * @param message - The persisted message
+ * @param originChannel - `chat` (dashboard), `portal` (relay) or `mobile`
+ * @returns The intake message, or null when it is not the owner's
+ */
+export declare function chatV2IntakeMessage(channel: ChatChannelDTO, message: ChatMessageDTO, originChannel: Extract<TicketOriginChannel, 'chat' | 'portal' | 'mobile'>): IntakeMessage | null;
+/**
+ * Ticket intake for an owner's chat-v2 message (specs/ticket-loop.md §2),
+ * shared by the REST controller and the portal relay adapter. Waits at most
+ * `TICKET_CONSTANTS.INTAKE_TIMEOUT_MS`; never throws.
+ *
+ * @param intake - The intake service (null → no-op)
+ * @param channel - The message's channel
+ * @param message - The persisted message
+ * @param origin - `chat`, `portal` or `mobile`
+ * @returns The message to dispatch — a copy carrying the ticket line when it
+ *   belongs to a ticket, otherwise the message itself
+ */
+export declare function intakeChatV2OwnerMessage(intake: Pick<TicketIntakeService, 'intakeWithOutcome'> | null, channel: ChatChannelDTO, message: ChatMessageDTO, origin: Extract<TicketOriginChannel, 'chat' | 'portal' | 'mobile'>): Promise<ChatMessageDTO>;
+/** What the Slack call sites know about an inbound message. */
+export interface SlackIntakeInput {
+    text: string;
+    slackChannelId: string;
+    ts: string;
+    threadTs?: string;
+    userId: string;
+    userName?: string;
+    /** Set when a bot (one of the account's agents) wrote it */
+    authorAgentSession?: string;
+    hasFiles?: boolean;
+    /**
+     * Slack user id of the owner (the Cloud app's installer), when known. Then
+     * only that user's messages file tickets; other people in the workspace do
+     * not (Phase 1). Unknown (self-hosted socket mode) = any human.
+     */
+    ownerUserId?: string | null;
+}
+/**
+ * Build the intake message for a Slack message.
+ *
+ * The source id prefix is per surface: the legacy bridge keeps `slack-…`
+ * (the SLA subscriber and status updater key on it), team channels use
+ * `slackch-…` and agent DMs `slackdm-…` so an orc reply in the same thread
+ * cannot close a ticket that belongs to a team.
+ *
+ * @param input - The Slack message
+ * @param surface - Which Slack path received it
+ * @param options - Assignee and where the receipt goes
+ * @returns The intake message
+ */
+export declare function slackIntakeMessage(input: SlackIntakeInput, surface: 'legacy-bridge' | 'team-channel' | 'agent-dm', options?: {
+    targetAgent?: string;
+    receiptPostAs?: string;
+}): IntakeMessage;
+//# sourceMappingURL=ticket-channel-hooks.d.ts.map

package/dist/cli/backend/src/services/v3/ticket-channel-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ticket-channel-hooks.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/v3/ticket-channel-hooks.ts"],"names":[],"mappings":"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"}