crewly 1.20.194 → 1.20.196

package/dist/backend/backend/src/services/signal-digest/signal-digest.service.d.ts

@@ -0,0 +1,272 @@
+/**
+ * Daily signal digest (#987, specs/2026-10-03-signal-digest.md).
+ *
+ * A team lead proposes 3–5 actions for a site (the `signal-digest` skill
+ * collects the signals and drafts them). This service:
+ * 1. refuses actions the site's history blocks (tried with Do, or skipped
+ *    recently), and replaces the site's earlier unanswered actions;
+ * 2. posts ONE Slack card with Do / Skip per action, from the lead's bot, in
+ *    the lead's team channel (else the owner's DM);
+ * 3. on Do, opens an experiment ticket in the site's project and tells the
+ *    lead; on Skip, records it so the action stays off the list for a while;
+ * 4. keeps each site's signal-source status and tells the owner once when a
+ *    source starts or stops failing (nothing on the days it does not change).
+ *
+ * @module services/signal-digest/signal-digest.service
+ */
+import type { ComponentLogger } from '../core/logger.service.js';
+import type { DecisionPostIdentity, DecisionSlackApi, BlockActionsPayload } from '../decisions/decision.service.js';
+import type { CreateSignalDigestInput, SignalChoice, SignalDigest, SignalDigestItem, SignalHistoryEntry, SignalSourceReport } from '../../types/signal-digest.types.js';
+import type { SignalDigestStore } from './signal-digest-store.js';
+/** A ticket a Do asks for. */
+export interface SignalTicketInput {
+    /** Project reference (name, id or path) */
+    project: string;
+    /** The lead's team, when known (dropped when it is not on the project) */
+    team?: string;
+    title: string;
+    description: string;
+    acceptance: string[];
+    labels: string[];
+    source: string;
+}
+/** The experiment card a Do asks for (#986): the experiment service's create input. */
+export interface SignalExperimentInput {
+    title: string;
+    hypothesis: string;
+    metric: Record<string, string>;
+    ticket: {
+        kind: 'project';
+        project: string;
+        id: string;
+    };
+}
+/** Collaborators. */
+export interface SignalDigestServiceDeps {
+    store: SignalDigestStore;
+    slack: () => DecisionSlackApi | null;
+    instanceId: () => string;
+    /** Whether a Slack user may answer (the owner) */
+    isOwner: (userId: string) => boolean;
+    identityOf: (session: string) => Promise<DecisionPostIdentity>;
+    teamOf: (session: string) => Promise<string | undefined>;
+    teamChannelOf: (teamId: string) => Promise<string | null>;
+    /** The owner's DM, opened with that identity (fallback place) */
+    ownerDmOf?: (identity: DecisionPostIdentity) => Promise<string | null>;
+    displayName?: (session: string) => Promise<string | undefined>;
+    /** Open a ticket; returns its id */
+    createTicket: (input: SignalTicketInput) => Promise<{
+        id: string;
+    }>;
+    /** Create an experiment card as that session (#986); absent = experiment cards are off */
+    createExperiment?: (input: SignalExperimentInput, caller: string) => Promise<{
+        id: string;
+    }>;
+    /** Tell an agent something (wakes it when needed) */
+    deliverToAgent: (session: string, text: string) => Promise<boolean>;
+    /** Tell the owner (false = not delivered); absent = no source-change notices */
+    notifyOwner?: (notice: {
+        title: string;
+        message: string;
+        urgent: boolean;
+    }) => Promise<boolean>;
+    logger: ComponentLogger;
+    now?: () => Date;
+}
+/** What a Slack click did. */
+export interface SignalInteractionOutcome {
+    handled: boolean;
+    reason: string;
+    digest?: SignalDigest;
+}
+/**
+ * The description of the ticket a Do opens: the digest item plus the
+ * experiment card fields #986 measures (hypothesis, metric, baseline, window).
+ *
+ * @param digest - Digest
+ * @param item - The action
+ * @returns Markdown
+ */
+export declare function experimentTicketDescription(digest: SignalDigest, item: SignalDigestItem): string;
+/**
+ * How a source is named to the owner.
+ *
+ * @param name - Source name
+ * @returns Label
+ */
+export declare function sourceLabel(name: string): string;
+/**
+ * Signal digests: proposals, the Slack card, the owner's answers.
+ */
+export declare class SignalDigestService {
+    private readonly deps;
+    private static instance;
+    private readonly now;
+    /** Source reports are handled one at a time (one change notice per change) */
+    private sourceChain;
+    /**
+     * @param deps - Collaborators
+     */
+    constructor(deps: SignalDigestServiceDeps);
+    /** The running service, when started. */
+    static getInstance(): SignalDigestService | null;
+    /**
+     * Set (or clear) the running service.
+     *
+     * @param service - Service or null
+     */
+    static setInstance(service: SignalDigestService | null): void;
+    /**
+     * Propose a digest. The site's earlier unanswered actions are replaced
+     * (expired) first; then any action the history still blocks is refused.
+     *
+     * @param callerSession - Team lead session (X-Agent-Session)
+     * @param input - `{ site, project?, config?, items }`
+     * @returns The stored digest (with `card`, or `postError` when Slack refused)
+     * @throws SignalDigestError(400) for a contract violation, (409) for blocked actions
+     */
+    propose(callerSession: string | undefined, input: CreateSignalDigestInput): Promise<SignalDigest>;
+    /**
+     * A site's digest proposed within DUPLICATE_WINDOW_MS that still has open actions.
+     *
+     * @param site - Site
+     * @returns The newest such digest, or null
+     */
+    private recentOpenDigest;
+    /**
+     * The site's latest source report, when it is recent enough to describe today's run.
+     *
+     * @param site - Site
+     * @returns Statuses, or undefined
+     */
+    private latestSources;
+    /**
+     * A collect run's source statuses (`POST /api/signal-digests/sources`).
+     * Stored per site; the owner is told once when a source starts or stops
+     * failing — not every day it stays broken.
+     *
+     * @param callerSession - Team lead session (X-Agent-Session)
+     * @param input - `{ site, sources }`
+     * @returns What changed and whether the owner was told
+     * @throws SignalDigestError(400)
+     */
+    reportSources(callerSession: string | undefined, input: {
+        site?: unknown;
+        sources?: unknown;
+    }): Promise<SignalSourceReport>;
+    /**
+     * Store a source report and send the change notice (see {@link reportSources}).
+     *
+     * @param caller - Reporting session
+     * @param site - Site
+     * @param sources - Statuses
+     * @returns The report outcome
+     */
+    private recordSources;
+    /**
+     * The site's blocked keys (Do within 90 days, Skip within 30) and its open ones.
+     *
+     * @param site - Site
+     * @returns History entries
+     */
+    history(site: string): Promise<SignalHistoryEntry[]>;
+    /**
+     * Digests, newest first.
+     *
+     * @param site - Only this site, when given
+     * @returns Digests
+     */
+    list(site?: string): Promise<SignalDigest[]>;
+    /**
+     * One digest.
+     *
+     * @param id - Digest id
+     * @returns Digest or null
+     */
+    get(id: string): Promise<SignalDigest | null>;
+    /**
+     * Answer one action from the dashboard / API (owner only; the caller checks).
+     *
+     * @param id - Digest id
+     * @param n - Item number
+     * @param choice - do / skip
+     * @returns The updated digest
+     * @throws SignalDigestError(404) unknown digest / item, (409) already answered
+     */
+    choose(id: string, n: number, choice: SignalChoice): Promise<SignalDigest>;
+    /**
+     * A Slack `block_actions` payload. Ignores anything that is not a click on
+     * one of this instance's digest cards by the owner.
+     *
+     * @param payload - Slack payload
+     * @returns What happened
+     */
+    handleInteraction(payload: BlockActionsPayload): Promise<SignalInteractionOutcome>;
+    /**
+     * Record the answer; on Do open the ticket and tell the lead; redraw the card.
+     *
+     * @param id - Digest id
+     * @param n - Item number
+     * @param choice - do / skip
+     * @param by - Slack user id, or `dashboard`
+     * @returns The updated digest, or null when the item was not open
+     */
+    private apply;
+    /**
+     * Open the experiment ticket of a Do.
+     *
+     * @param digest - Digest
+     * @param item - The action
+     * @returns The ticket id, or why there is none
+     */
+    private openTicket;
+    /**
+     * Create the experiment card of a Do (#986), linked to its ticket, as the
+     * lead (its prediction is recorded under the lead). Only when the action
+     * names a metric and the digest has the seo-ops config.
+     *
+     * @param digest - Digest
+     * @param item - The action
+     * @param ticketId - The ticket the Do opened
+     * @returns The card id, why there is none, or null when none was asked for
+     */
+    private openExperiment;
+    /**
+     * What the lead is told after a Do.
+     *
+     * @param digest - Digest
+     * @param item - The answered action
+     * @returns Message text
+     */
+    private doNote;
+    /**
+     * Replace the site's earlier unanswered actions: they become `expired` and
+     * their cards say so.
+     *
+     * @param site - Site
+     */
+    private expireOpen;
+    /**
+     * Post the card: the lead's team channel from the lead's bot, else the
+     * owner's DM.
+     *
+     * @param digest - Digest without a card
+     * @returns The digest with `card`, or `postError`
+     */
+    private postCard;
+    /**
+     * Redraw a posted card.
+     *
+     * @param digest - Digest
+     * @returns True when Slack accepted the update
+     */
+    private refreshCard;
+    /**
+     * Tell the lead (best effort).
+     *
+     * @param digest - Digest
+     * @param text - Message
+     */
+    private tellAsker;
+}
+//# sourceMappingURL=signal-digest.service.d.ts.map

package/dist/backend/backend/src/services/signal-digest/signal-digest.service.d.ts.map

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