crewly 1.20.108 → 1.20.110

package/dist/backend/backend/src/services/v3/ticket-review.service.d.ts

@@ -0,0 +1,242 @@
+/**
+ * TicketReviewService — the back half of the ticket loop
+ * (specs/ticket-loop.md, Phase 2).
+ *
+ * Phase 1 files a ticket for every "please do X". This service decides when
+ * a ticket is answered and what the owner does about it:
+ *
+ * - **Answered.** An agent message in the ticket's own conversation (matched
+ *   through the chat-v2 turn that opened it, {@link TicketReviewService.noteChatTurn})
+ *   is recorded as the ticket's `reply`. Once that agent is idle again (or the
+ *   reply has settled for {@link TICKET_CONSTANTS.REVIEW.SUBMIT_SETTLE_MS}) and
+ *   no WorkItem of the ticket is still open, the ticket is submitted: it goes
+ *   to 待验收 (`waiting_confirmation`), or straight to done for origins that
+ *   need no review. This replaces the old blind "close any open Request 3–10
+ *   minutes old" sweep, which closed tickets that nobody had answered.
+ * - **验过了** → done. **打回 + reason** → back to work; the reason becomes an
+ *   acceptance criterion (#763: criteria grow from real review) and, when the
+ *   owner sent it back from the board rather than the thread, a rework
+ *   WorkItem is queued for whoever answered.
+ * - **Silence accepts.** 待验收 for {@link TICKET_CONSTANTS.REVIEW.AUTO_ACCEPT_MS}
+ *   with no word → done, tagged `auto_accepted`. The owner is never pinged.
+ *
+ * The `done` gate itself lives in {@link RequestService.update}: without
+ * `accepted`, a ticket that needs review cannot become done by any path.
+ *
+ * @module services/v3/ticket-review.service
+ */
+import { type Request, type RequestPriority } from '../../types/v2/request.types.js';
+import { type TicketAcceptanceCheck, type TicketKind } from '../../types/v2/ticket.types.js';
+/** Request store surface the review needs (narrow for tests). */
+export interface ReviewRequestStore {
+    getById(id: string): Promise<Request | null>;
+    listAll(): Promise<Request[]>;
+    update(id: string, updates: Parameters<import('./request.service.js').RequestService['update']>[1]): Promise<Request>;
+}
+/** The slice of a chat-v2 message the review reads. */
+export interface ReviewChatMessage {
+    id: string;
+    channelId: string;
+    senderType: string;
+    senderId: string;
+    content: string;
+    threadId?: string;
+}
+/** A rework request for {@link TicketReviewServiceDeps.createRework}. */
+export interface ReworkInput {
+    ticket: Request;
+    reason: string;
+    /** Agent session to hand it to */
+    target: string;
+}
+/** Constructor dependencies. */
+export interface TicketReviewServiceDeps {
+    requests: ReviewRequestStore;
+    /** Number of the ticket's WorkItems that are not terminal */
+    openWorkItemCount?: (requestId: string) => Promise<number>;
+    /** Queue a rework WorkItem; returns its id */
+    createRework?: (input: ReworkInput) => Promise<string | null>;
+    /** Swap the receipt to "done" (🎫 → ✅) */
+    markReceiptDone?: (ticket: Request) => Promise<void>;
+    /** Session the rework goes to when nobody answered (the orchestrator) */
+    fallbackAgent: string;
+    now?: () => Date;
+}
+/** Result of an owner action. */
+export type ReviewActionResult = {
+    ok: true;
+    ticket: Request;
+} | {
+    ok: false;
+    reason: 'not_found' | 'not_in_review' | 'already_done' | 'cancelled' | 'open_work' | 'invalid';
+    ticket?: Request;
+};
+/** Where a 打回 came from. */
+export type RejectVia = 'thread' | 'board';
+/** Fields the owner may change from the board. */
+export interface TicketPatch {
+    title?: string;
+    priority?: RequestPriority;
+    kind?: TicketKind;
+    assignee?: string | null;
+}
+/**
+ * Review lifecycle of tickets. See module docs.
+ */
+export declare class TicketReviewService {
+    private readonly deps;
+    private readonly logger;
+    private chain;
+    /**
+     * @param deps - Store and optional pool / receipt hooks
+     */
+    constructor(deps: TicketReviewServiceDeps);
+    /**
+     * Run one state change at a time, so an idle event and the sweep cannot
+     * submit the same ticket twice.
+     *
+     * @param fn - The change
+     * @returns Its result
+     */
+    private serial;
+    /**
+     * Remember the chat-v2 turn that opened a ticket, so agent answers in the
+     * same thread can be matched to it. Only the first turn counts.
+     *
+     * @param ticketId - The ticket
+     * @param message - The owner's persisted message
+     */
+    noteChatTurn(ticketId: string, message: Pick<ReviewChatMessage, 'id' | 'channelId' | 'threadId'>): Promise<void>;
+    /**
+     * An agent posted in chat-v2: record it as the answer of the ticket whose
+     * thread it is in. Top-level agent messages (no thread) count for the newest
+     * open ticket in that channel that the agent could be answering.
+     *
+     * @param message - The chat-v2 message
+     * @returns The ticket it was recorded on, or null
+     */
+    onChatMessage(message: ReviewChatMessage): Promise<Request | null>;
+    /**
+     * An agent finished its turn: submit the tickets it answered.
+     *
+     * @param sessionName - The agent
+     * @returns Tickets submitted
+     */
+    onAgentIdle(sessionName: string): Promise<Request[]>;
+    /**
+     * Periodic pass: submit answers that have settled (in case no idle event
+     * came), and auto-accept 待验收 tickets nobody objected to.
+     *
+     * @returns What changed
+     */
+    sweep(): Promise<{
+        submitted: number;
+        autoAccepted: number;
+    }>;
+    /**
+     * Submit every answered ticket that matches and has no open work.
+     *
+     * @param match - Which answered tickets to look at
+     * @returns Tickets submitted
+     */
+    private submitAnswered;
+    /**
+     * 验过了 — the owner accepts. Works from any open status (the owner may
+     * accept before the agent says it is finished), but not while WorkItems
+     * are still running.
+     *
+     * @param ref - `TKT-123`, `123` or id
+     * @returns The accepted ticket, or why not
+     */
+    verify(ref: string): Promise<ReviewActionResult>;
+    /**
+     * Move a ticket to done with the owner's (or the auto-accept's) blessing.
+     *
+     * @param ticket - The ticket
+     * @param tags - Tags to store
+     * @returns Result
+     */
+    private accept;
+    /**
+     * 打回 — the owner sends it back. The reason becomes an acceptance
+     * criterion; from the board (not the thread, where the agent already sees
+     * the owner's words) a rework WorkItem is queued for whoever answered.
+     *
+     * @param ref - `TKT-123`, `123` or id
+     * @param reason - Why (required; the thread path fills a placeholder)
+     * @param via - `thread` or `board`
+     * @returns The reopened ticket, or why not
+     */
+    reject(ref: string, reason: string, via: RejectVia): Promise<ReviewActionResult>;
+    /**
+     * A follow-up from the owner in a 待验收 ticket's thread that is neither
+     * 验过了 nor 打回: the agent is working again, so the ticket leaves 待验收
+     * (no reject counted).
+     *
+     * @param ticketId - The ticket
+     * @returns The ticket after the change
+     */
+    reopenOnFollowUp(ticketId: string): Promise<Request | null>;
+    /**
+     * Replace the live acceptance list. Criteria not in `items` are marked
+     * removed (kept for history); new texts are added as the owner's.
+     *
+     * @param ref - Ticket reference
+     * @param items - The list the owner wants, in order
+     * @returns The ticket
+     */
+    setAcceptance(ref: string, items: ReadonlyArray<{
+        text: string;
+        check?: TicketAcceptanceCheck;
+    }>): Promise<ReviewActionResult>;
+    /**
+     * An agent's self-check against one live criterion.
+     *
+     * @param ref - Ticket reference
+     * @param index - Position in the live list (0-based)
+     * @param result - pass / fail
+     * @param evidence - What it looked at
+     * @returns The ticket
+     */
+    selfCheck(ref: string, index: number, result: 'pass' | 'fail', evidence?: string): Promise<ReviewActionResult>;
+    /**
+     * Board edits: title, priority, kind, assignee.
+     *
+     * @param ref - Ticket reference
+     * @param patch - Changes
+     * @returns The ticket
+     */
+    patch(ref: string, patch: TicketPatch): Promise<ReviewActionResult>;
+    /**
+     * Find a ticket by `TKT-123`, `123` or id.
+     *
+     * @param ref - Reference
+     * @returns The ticket, or null
+     */
+    private resolve;
+    /**
+     * Best-effort receipt swap.
+     *
+     * @param ticket - The done ticket
+     */
+    private receiptDone;
+    /**
+     * Current time (injectable for tests).
+     *
+     * @returns Now
+     */
+    private now;
+}
+/**
+ * Install the process-wide review service (composition root).
+ *
+ * @param service - The service, or null to clear (tests)
+ */
+export declare function setTicketReviewService(service: TicketReviewService | null): void;
+/**
+ * The process-wide review service, or null before boot wired it.
+ *
+ * @returns The service or null
+ */
+export declare function getTicketReviewService(): TicketReviewService | null;
+//# sourceMappingURL=ticket-review.service.d.ts.map

package/dist/backend/backend/src/services/v3/ticket-review.service.d.ts.map

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