crewly 1.20.168 → 1.20.170

package/dist/cli/backend/src/services/messaging/owner-message-watchdog.service.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Unanswered-owner-message watchdog.
+ *
+ * Every owner message delivered to an agent on this machine ends in either an
+ * answer the owner can see, or ONE plain-words note in the same thread saying
+ * who it is waiting on and why. Four different bugs on 2026-09-30 each lost an
+ * owner message silently; each was fixed on its own, but nothing guaranteed
+ * the end-to-end property. This does.
+ *
+ * Timeline per message (constants in OWNER_MESSAGE_WATCHDOG_CONSTANTS):
+ *  - an answer (or a settled placeholder, or `reply --none`) clears it;
+ *  - a placeholder showing while the agent is mid-turn extends the wait, up
+ *    to BUSY_EXTEND_CAP_MS, then a note;
+ *  - T1 → one re-delivery ("nudge") to the responsible agent, waking it;
+ *    an agent that cannot be reached skips straight to the note;
+ *  - T2 → one note, and the message is no longer tracked.
+ *
+ * The service is transport-agnostic: what counts as "delivered", "answered",
+ * "busy" and how to nudge / post a note are injected (see the wiring module).
+ *
+ * @module services/messaging/owner-message-watchdog.service
+ * @see specs/2026-09-30-owner-message-guarantee.md
+ */
+/** Where the owner wrote: a Slack conversation, or a Crewly chat (portal / Talk / dashboard). */
+export type OwnerMessageSurface = 'slack' | 'chat';
+/** What a watched message needs to be tracked. */
+export interface OwnerMessageTrackInput {
+    surface: OwnerMessageSurface;
+    /** Slack channel / DM id (slack surface) */
+    slackChannelId?: string;
+    /** Slack thread root the answer belongs in (slack surface) */
+    threadTs?: string;
+    /** The owner's Slack message ts (dedupe key for slack) */
+    sourceTs?: string;
+    /** chat-v2 channel / conversation the message was recorded in (both surfaces when known) */
+    chatChannelId?: string;
+    /** chat-v2 thread the answer belongs in (huddles) */
+    chatThreadId?: string;
+    /** chat-v2 message id (dedupe key for chat) */
+    messageId?: string;
+    /** The agent that must answer (nudged at T1, named in the note) */
+    responsible: string;
+    /** Every agent that holds the message */
+    recipients: readonly string[];
+    /** True when at least one recipient was required to answer (DM, @mention, woken lead) */
+    required: boolean;
+    /** The owner's words */
+    text: string;
+    /** When it arrived (epoch ms); defaults to now */
+    receivedAt?: number;
+}
+/** One tracked message. */
+export interface OwnerMessageEntry {
+    key: string;
+    surface: OwnerMessageSurface;
+    slackChannelId?: string;
+    threadTs?: string;
+    sourceTs?: string;
+    chatChannelId?: string;
+    chatThreadId?: string;
+    messageId?: string;
+    responsible: string;
+    recipients: string[];
+    required: boolean;
+    /** Clipped owner text */
+    preview: string;
+    receivedAt: number;
+    stage: 'waiting' | 'nudged';
+    nudgedAt?: number;
+    /** A nudge that could not reach the agent */
+    nudgeBlocked?: {
+        reason: NudgeBlockReason;
+        detail?: string;
+    };
+    /** An interim note was posted in chat (a visible "working on it") */
+    interimAt?: number;
+    /** The nudged agent started a turn after the nudge */
+    busyAfterNudge?: boolean;
+    /** …and finished it */
+    turnDoneAfterNudge?: boolean;
+    /** Extension already logged */
+    extendedLogged?: boolean;
+}
+/** Why a nudge could not reach the agent. */
+export type NudgeBlockReason = 'asleep' | 'login' | 'error';
+/** Outcome of one nudge. */
+export type NudgeOutcome = {
+    outcome: 'sent';
+} | {
+    outcome: 'blocked';
+    reason: NudgeBlockReason;
+    detail?: string;
+};
+/** Pending sign-in, for the one-tap fix in the note. */
+export interface LoginHint {
+    /** Human name of the runtime ("Claude", "Codex") */
+    runtime: string;
+    /** Word the owner types after 重新登录 ("claude", "codex") */
+    runtimeCmd: string;
+}
+/** Injected behaviour. */
+export interface OwnerMessageWatchdogDeps {
+    /** Is the agent mid-turn right now? */
+    isBusy: (agentSession: string) => boolean;
+    /** Is a "working on it" placeholder showing where the answer will land (slack surface)? */
+    hasVisiblePlaceholder?: (entry: OwnerMessageEntry) => boolean;
+    /** Re-deliver the message to its responsible agent, waking it when stopped. */
+    nudge: (entry: OwnerMessageEntry, waitedMinutes: number) => Promise<NudgeOutcome>;
+    /** Post the note where the owner wrote. Returns false when it could not be posted. */
+    postNote: (entry: OwnerMessageEntry, text: string) => Promise<boolean>;
+    /** A sign-in the agent's runtime is waiting for, if any. */
+    loginRequired?: (agentSession: string) => LoginHint | null;
+    /** Display name for notes ("Ella"); defaults to the session name. */
+    displayNameOf?: (agentSession: string) => string;
+    /** Persisted state; omitted in tests that do not exercise restarts. */
+    storePath?: string;
+    /** Clock (tests). */
+    now?: () => number;
+}
+/** Row of the debug listing. */
+export interface OwnerMessageListing {
+    key: string;
+    surface: OwnerMessageSurface;
+    where: string;
+    responsible: string;
+    recipients: string[];
+    required: boolean;
+    ageMinutes: number;
+    stage: OwnerMessageEntry['stage'];
+    nudgedMinutesAgo?: number;
+    nudgeBlocked?: OwnerMessageEntry['nudgeBlocked'];
+    preview: string;
+}
+/**
+ * Whether a whole message is a bare acknowledgement ("好", "ok", "👍", "谢谢")
+ * that needs no answer.
+ *
+ * @param text - The owner's message
+ * @returns True for an acknowledgement from ACK_WORDS
+ */
+export declare function isAcknowledgement(text: string): boolean;
+/**
+ * The dedupe key of a message.
+ *
+ * @param input - Track input (or entry)
+ * @returns `slack:<channel>:<ts>` / `chat:<channel>:<messageId>`, or null when underspecified
+ */
+export declare function ownerMessageKey(input: Pick<OwnerMessageTrackInput, 'surface' | 'slackChannelId' | 'sourceTs' | 'threadTs' | 'chatChannelId' | 'messageId'>): string | null;
+/**
+ * Tracks owner messages until they are answered, nudging and then noting.
+ */
+export declare class OwnerMessageWatchdogService {
+    private readonly deps;
+    private readonly logger;
+    private readonly entries;
+    /** Recently finished keys, oldest first (Map keeps insertion order). */
+    private readonly resolved;
+    /** Thread → when an answer was last seen there (answers can beat the tracking call). */
+    private readonly recentAnswers;
+    private timer;
+    private ticking;
+    /**
+     * @param deps - Injected behaviour (see {@link OwnerMessageWatchdogDeps})
+     */
+    constructor(deps: OwnerMessageWatchdogDeps);
+    private now;
+    /** Start the periodic evaluation. */
+    start(): void;
+    /** Stop the periodic evaluation. */
+    stop(): void;
+    /**
+     * Start watching an owner message that was delivered to at least one agent.
+     * A second delivery of the same message (a hand-off, a re-dispatch) updates
+     * the entry rather than adding one; a message already answered is ignored.
+     *
+     * @param input - The message and who holds it
+     * @returns The entry, or null when it is not tracked (ack, answered, underspecified)
+     */
+    track(input: OwnerMessageTrackInput): OwnerMessageEntry | null;
+    /**
+     * Something the owner can see was posted in a Slack thread (an answer, a
+     * file, a settled placeholder, a colleague on another machine).
+     *
+     * @param slackChannelId - Slack channel / DM
+     * @param threadTs - Thread root (undefined = top level: clears nothing)
+     * @param why - For the log
+     * @returns How many entries were cleared
+     */
+    noteSlackAnswer(slackChannelId: string, threadTs: string | undefined, why: string): number;
+    /**
+     * An agent (or the orchestrator) spoke in a Crewly chat channel.
+     *
+     * @param chatChannelId - chat-v2 channel
+     * @param threadId - Thread of the turn (null/undefined = top level)
+     * @param interim - An interim note: shown, but the answer is still owed
+     * @returns How many entries were cleared
+     */
+    noteChatAnswer(chatChannelId: string, threadId: string | null | undefined, interim: boolean): number;
+    /**
+     * The responsible agent said no answer is needed (`reply --none`) for what
+     * it was asked in this conversation.
+     *
+     * @param agentSession - The agent
+     * @param where - Conversation (and thread) of its turn origin
+     * @returns How many entries were closed
+     */
+    closeByAgent(agentSession: string, where: {
+        chatChannelId?: string;
+        slackChannelId?: string;
+        threadTs?: string;
+    }): number;
+    /**
+     * An agent's working status changed. After a nudge, an optional-only
+     * message whose agent then finished a whole turn without answering is
+     * that agent's judgement ("not for me") — closed quietly at the next tick.
+     *
+     * @param agentSession - The agent
+     * @param busy - True when a turn started, false when it ended
+     */
+    noteAgentTurn(agentSession: string, busy: boolean): void;
+    /**
+     * Open messages an agent holds (responsible or recipient), oldest first.
+     *
+     * @param agentSession - The agent
+     * @returns Entries
+     */
+    owedBy(agentSession: string): OwnerMessageEntry[];
+    /**
+     * Debug listing of what is still waiting.
+     *
+     * @returns One row per tracked message, oldest first
+     */
+    list(): OwnerMessageListing[];
+    /** Number of tracked messages. */
+    get size(): number;
+    /**
+     * Evaluate every tracked message once. Safe to call concurrently (a second
+     * call while one runs is a no-op).
+     *
+     * @returns When the evaluation is done
+     */
+    tick(): Promise<void>;
+    private evaluate;
+    private isVisiblyWorking;
+    private runNudge;
+    /**
+     * Post the one note and stop tracking.
+     *
+     * @param entry - The message
+     * @param kind - Why now
+     */
+    private note;
+    /**
+     * The note in plain words.
+     *
+     * @param entry - The message
+     * @param kind - Why now
+     * @returns The note text
+     */
+    noteText(entry: OwnerMessageEntry, kind: 'cap' | 'silent' | 'blocked'): string;
+    private noteRecentAnswer;
+    private remember;
+    private finish;
+    private persist;
+    private load;
+}
+/** @returns The wired watchdog, or null before it started (and in tests). */
+export declare function getOwnerMessageWatchdog(): OwnerMessageWatchdogService | null;
+/** @param service - The watchdog to expose (null to clear) */
+export declare function setOwnerMessageWatchdog(service: OwnerMessageWatchdogService | null): void;
+//# sourceMappingURL=owner-message-watchdog.service.d.ts.map

package/dist/cli/backend/src/services/messaging/owner-message-watchdog.service.d.ts.map

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