@dsh-cove/dsh-web-all 0.0.0-stage → 0.4.3

package/lib/types/host/services/notify/feishu-sender.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Outbound Feishu/Lark delivery for finished runs.
+ *
+ * This is the mirror of `lark-inbox/gateway.ts`: that file owns the inbound
+ * WebSocket connection and this one owns the outbound message call, and both
+ * hide the vendor SDK behind a narrow injected seam so the behaviour the
+ * capability actually promises can be tested without a network or a tenant.
+ *
+ * Two properties matter more than throughput here, because this runs from an
+ * event handler rather than from a request:
+ *
+ * 1. It never throws into the emitter. A notification that cannot be delivered
+ *    is logged and dropped; it must not turn a finished run into a failed one.
+ * 2. It stays under the application's rate limit. Feishu caps one application at
+ *    five calls per second, and one finished run addresses several recipients,
+ *    so sends are serialized with a minimum gap instead of fired in parallel.
+ *
+ * Messages are plain text rather than interactive cards on purpose: a card's
+ * schema is versioned and a rejected card is a silently lost notification,
+ * while a text message delivers the same three facts with nothing to validate.
+ */
+import { type RunNotice } from '../../../core/notify/contract.ts';
+import type { FeishuCredentials } from './config.ts';
+/** The vendor surface this module uses, so tests can supply their own. */
+export interface FeishuSenderSdk {
+    createClient(options: {
+        appId: string;
+        appSecret: string;
+        domain: unknown;
+    }): {
+        im: {
+            message: {
+                create(payload: unknown): Promise<unknown>;
+            };
+        };
+    };
+    domain: {
+        Feishu: unknown;
+        Lark: unknown;
+    };
+}
+/** One delivery's outcome, reported rather than thrown. */
+export interface DeliveryAttempt {
+    recipient: string;
+    ok: boolean;
+    /** Vendor error text when the call failed. */
+    error?: string;
+}
+/** Options for one sender instance. */
+export interface FeishuSenderOptions {
+    credentials: FeishuCredentials;
+    /** Open ids (`ou_…`), user ids, or chat ids to address as `open_id`. */
+    recipients: readonly string[];
+    /** Human name of the machine the run happened on. */
+    hostLabel: string;
+    log?: (message: string) => void;
+    sdk?: FeishuSenderSdk;
+    /** Minimum gap between two vendor calls, keeping the app under its rate limit. */
+    minGapMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Compose the message body for one delivery.
+ *
+ * The text states three things and nothing else: how it ended, which
+ * conversation it was, and which machine it ran on. It deliberately carries no
+ * session ids, no turn numbers and no raw reason kinds — those are diagnosable
+ * in the workspace, and putting them in a phone notification makes the one line
+ * that matters harder to find.
+ *
+ * @param notices - the finished runs this delivery covers, oldest first.
+ * @param hostLabel - the machine's name.
+ * @returns the message text, with no trailing newline.
+ */
+export declare function composeFeishuText(notices: readonly RunNotice[], hostLabel: string): string;
+/**
+ * Delivers composed messages to every configured recipient.
+ *
+ * One instance is bound to one credential set and one recipient list; the
+ * owning service rebuilds it when the configuration changes, so a credential
+ * rotation cannot leave a stale token cache behind.
+ */
+export declare class FeishuSender {
+    private readonly options;
+    private readonly log;
+    private readonly sdk;
+    private readonly minGapMs;
+    private readonly sleep;
+    private readonly now;
+    private client;
+    /** Serializes sends and carries the last call time, so the rate limit holds across callers. */
+    private chain;
+    private lastCallAt;
+    constructor(options: FeishuSenderOptions);
+    /** Recipients this sender will address. */
+    get recipients(): readonly string[];
+    /** Domain the credentials address. */
+    get domain(): string;
+    private vendorClient;
+    /**
+     * Deliver one text message to every recipient, serially and rate limited.
+     * @param text - the message body.
+     * @returns one attempt per recipient; empty when no recipient is configured.
+     */
+    send(text: string): Promise<DeliveryAttempt[]>;
+    private sendOne;
+    private respectGap;
+    /**
+     * Deliver and reduce the result to one log line.
+     *
+     * Event handlers cannot await a promise they do not own, and a rejected one
+     * would be an unhandled rejection, so the caller uses this instead of
+     * {@link send} whenever the notification is fire-and-forget.
+     *
+     * @param notices - the finished runs to report.
+     */
+    notify(notices: readonly RunNotice[]): Promise<void>;
+}
+//# sourceMappingURL=feishu-sender.d.ts.map

package/lib/types/host/services/notify/feishu-sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feishu-sender.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/notify/feishu-sender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,kCAAkC,CAAA;AACnF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAEpD,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,YAAY,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG;QAC5E,EAAE,EAAE;YAAE,OAAO,EAAE;gBAAE,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;aAAE,CAAA;SAAE,CAAA;KAChE,CAAA;IACD,MAAM,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAA;CAC3C;AAQD,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAA;IACjB,EAAE,EAAE,OAAO,CAAA;IACX,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,uCAAuC;AACvC,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,iBAAiB,CAAA;IAC9B,wEAAwE;IACxE,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAA;IACjB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B,GAAG,CAAC,EAAE,eAAe,CAAA;IACrB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtC;AAKD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAiB1F;AAED;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA2B;IAC/C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiB;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;IACrD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAClC,OAAO,CAAC,MAAM,CAAyD;IACvE,+FAA+F;IAC/F,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,UAAU,CAAI;gBAEV,OAAO,EAAE,mBAAmB;IASxC,2CAA2C;IAC3C,IAAI,UAAU,IAAI,SAAS,MAAM,EAAE,CAElC;IAED,sCAAsC;IACtC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,OAAO,CAAC,YAAY;IAYpB;;;;OAIG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;YAUtC,OAAO;YA2BP,UAAU;IAMxB;;;;;;;;OAQG;IACG,MAAM,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAc3D"}

package/lib/types/host/services/notify/feishu-sender.js

@@ -0,0 +1,186 @@
+/**
+ * Outbound Feishu/Lark delivery for finished runs.
+ *
+ * This is the mirror of `lark-inbox/gateway.ts`: that file owns the inbound
+ * WebSocket connection and this one owns the outbound message call, and both
+ * hide the vendor SDK behind a narrow injected seam so the behaviour the
+ * capability actually promises can be tested without a network or a tenant.
+ *
+ * Two properties matter more than throughput here, because this runs from an
+ * event handler rather than from a request:
+ *
+ * 1. It never throws into the emitter. A notification that cannot be delivered
+ *    is logged and dropped; it must not turn a finished run into a failed one.
+ * 2. It stays under the application's rate limit. Feishu caps one application at
+ *    five calls per second, and one finished run addresses several recipients,
+ *    so sends are serialized with a minimum gap instead of fired in parallel.
+ *
+ * Messages are plain text rather than interactive cards on purpose: a card's
+ * schema is versioned and a rejected card is a silently lost notification,
+ * while a text message delivers the same three facts with nothing to validate.
+ */
+import { Domain, Client } from '@larksuiteoapi/node-sdk';
+import { OUTCOME_LABEL_ZH } from "../../../core/notify/contract.js";
+/** The real SDK, narrowed to {@link FeishuSenderSdk}. */
+const officialSdk = {
+    domain: { Feishu: Domain.Feishu, Lark: Domain.Lark },
+    createClient: options => new Client(options),
+};
+/** Default gap: five calls per second is the application ceiling, so 250 ms is the floor. */
+const DEFAULT_MIN_GAP_MS = 250;
+/**
+ * Compose the message body for one delivery.
+ *
+ * The text states three things and nothing else: how it ended, which
+ * conversation it was, and which machine it ran on. It deliberately carries no
+ * session ids, no turn numbers and no raw reason kinds — those are diagnosable
+ * in the workspace, and putting them in a phone notification makes the one line
+ * that matters harder to find.
+ *
+ * @param notices - the finished runs this delivery covers, oldest first.
+ * @param hostLabel - the machine's name.
+ * @returns the message text, with no trailing newline.
+ */
+export function composeFeishuText(notices, hostLabel) {
+    const machine = hostLabel.trim() === '' ? '' : `机器：${hostLabel.trim()}`;
+    if (notices.length === 0)
+        return machine;
+    const lines = [];
+    if (notices.length === 1) {
+        const notice = notices[0];
+        lines.push(`运行结束：${OUTCOME_LABEL_ZH[notice.outcome]}`);
+        if (notice.title !== '')
+            lines.push(`会话：${notice.title}`);
+    }
+    else {
+        lines.push(`${notices.length} 个会话运行结束`);
+        for (const notice of notices) {
+            const label = OUTCOME_LABEL_ZH[notice.outcome];
+            lines.push(notice.title === '' ? `- ${label}` : `- ${label} · ${notice.title}`);
+        }
+    }
+    if (machine !== '')
+        lines.push(machine);
+    return lines.join('\n');
+}
+/**
+ * Delivers composed messages to every configured recipient.
+ *
+ * One instance is bound to one credential set and one recipient list; the
+ * owning service rebuilds it when the configuration changes, so a credential
+ * rotation cannot leave a stale token cache behind.
+ */
+export class FeishuSender {
+    options;
+    log;
+    sdk;
+    minGapMs;
+    sleep;
+    now;
+    client;
+    /** Serializes sends and carries the last call time, so the rate limit holds across callers. */
+    chain = Promise.resolve();
+    lastCallAt = 0;
+    constructor(options) {
+        this.options = options;
+        this.log = options.log ?? (() => undefined);
+        this.sdk = options.sdk ?? officialSdk;
+        this.minGapMs = options.minGapMs ?? DEFAULT_MIN_GAP_MS;
+        this.now = options.now ?? Date.now;
+        this.sleep = options.sleep ?? (ms => new Promise(resolve => { setTimeout(resolve, ms); }));
+    }
+    /** Recipients this sender will address. */
+    get recipients() {
+        return this.options.recipients;
+    }
+    /** Domain the credentials address. */
+    get domain() {
+        return this.options.credentials.domain;
+    }
+    vendorClient() {
+        if (this.client !== undefined)
+            return this.client;
+        const domain = this.options.credentials.domain;
+        const mapped = domain === 'feishu' ? this.sdk.domain.Feishu : this.sdk.domain.Lark;
+        this.client = this.sdk.createClient({
+            appId: this.options.credentials.appId,
+            appSecret: this.options.credentials.appSecret,
+            domain: mapped,
+        });
+        return this.client;
+    }
+    /**
+     * Deliver one text message to every recipient, serially and rate limited.
+     * @param text - the message body.
+     * @returns one attempt per recipient; empty when no recipient is configured.
+     */
+    async send(text) {
+        const body = text.trim();
+        if (body === '' || this.options.recipients.length === 0)
+            return [];
+        const attempts = [];
+        for (const recipient of this.options.recipients) {
+            attempts.push(await this.sendOne(recipient, body));
+        }
+        return attempts;
+    }
+    async sendOne(recipient, text) {
+        // Serialize every call through one chain: `notify()` is not concurrency safe
+        // and the vendor limit is per application, not per recipient.
+        const run = this.chain.then(async () => {
+            await this.respectGap();
+            try {
+                const response = await this.vendorClient().im.message.create({
+                    params: { receive_id_type: 'open_id' },
+                    data: { receive_id: recipient, msg_type: 'text', content: JSON.stringify({ text }) },
+                });
+                const code = response?.code;
+                // The SDK resolves even for a business error, so the envelope decides.
+                if (typeof code === 'number' && code !== 0) {
+                    return { recipient, ok: false, error: `feishu code ${code}: ${String(response.msg ?? '')}` };
+                }
+                return { recipient, ok: true };
+            }
+            catch (error) {
+                return { recipient, ok: false, error: error instanceof Error ? error.message : String(error) };
+            }
+            finally {
+                this.lastCallAt = this.now();
+            }
+        });
+        // Keep the chain alive after a rejection so one failure cannot block later sends.
+        this.chain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async respectGap() {
+        if (this.minGapMs <= 0)
+            return;
+        const elapsed = this.now() - this.lastCallAt;
+        if (this.lastCallAt !== 0 && elapsed < this.minGapMs)
+            await this.sleep(this.minGapMs - elapsed);
+    }
+    /**
+     * Deliver and reduce the result to one log line.
+     *
+     * Event handlers cannot await a promise they do not own, and a rejected one
+     * would be an unhandled rejection, so the caller uses this instead of
+     * {@link send} whenever the notification is fire-and-forget.
+     *
+     * @param notices - the finished runs to report.
+     */
+    async notify(notices) {
+        if (notices.length === 0)
+            return;
+        const text = composeFeishuText(notices, this.options.hostLabel);
+        const attempts = await this.send(text);
+        const failed = attempts.filter(attempt => !attempt.ok);
+        const delivered = attempts.length - failed.length;
+        if (attempts.length > 0 && failed.length === 0) {
+            this.log(`dsh-notify: 已推送 ${delivered} 条飞书通知`);
+            return;
+        }
+        for (const attempt of failed) {
+            this.log(`dsh-notify: 推送给 ${attempt.recipient} 失败：${attempt.error ?? '未知错误'}`);
+        }
+    }
+}

package/lib/types/host/services/notify/host-routes.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The one host route the notification capability serves: a read-only feed of
+ * finished runs.
+ *
+ * It is a privileged read surface like every other web-all host route family
+ * and goes through the shared admission fence, because the feed names the
+ * conversations this machine has been running. A partially mounted plugin can
+ * never widen access: without the fence service the strict loopback rule
+ * applies.
+ *
+ * There is deliberately no write route. A client's read watermark lives on the
+ * client, so the host keeps no per-client state to acknowledge and exposes no
+ * mutation an attacker could aim at. The only effect a caller can have is
+ * reading, which is why this family needs no CSRF-shaped defence beyond the
+ * fence itself.
+ */
+import type { IncomingMessage } from 'node:http';
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
+import type { NoticeLog } from '../../../core/notify/feed.ts';
+/** Query values one feed read is built from. */
+export interface FeedQuery {
+    /** Notices strictly newer than this id. */
+    since: number;
+    /** Maximum notices to return. */
+    limit: number;
+}
+/** What the route handler needs from its owning service. */
+export interface NotifyRouteDeps {
+    /** Retained notices, read fresh per request. */
+    log: () => NoticeLog;
+    /** Notices one read returns when the caller does not say. */
+    defaultLimit: () => number;
+    /** Host access fence; defaults to the strict loopback rule. */
+    isTrusted?: (request: IncomingMessage) => boolean;
+    /** Whether the capability is enabled right now, read per request. */
+    enabled?: () => boolean;
+}
+/**
+ * Read `since` and `limit` out of a request URL.
+ *
+ * Both are clamped rather than rejected: a client sending nonsense is asking
+ * for an answer, not for a diagnostic, and the bounded log already limits what
+ * any of these values can do.
+ *
+ * @param request - the request whose query string is read.
+ * @param defaultLimit - the limit used when the caller does not supply one.
+ * @returns the effective query.
+ */
+export declare function readFeedQuery(request: IncomingMessage, defaultLimit: number): FeedQuery;
+/**
+ * The authority to report as this feed's origin.
+ *
+ * It comes from the request's own `Host` header rather than from configuration,
+ * because the caller reached the machine under that name and a client listing
+ * several machines must be able to label each row with what it dialed. A header
+ * carrying separators or whitespace is not an authority and is reported empty
+ * instead of being echoed into a document.
+ *
+ * @param request - the request being answered.
+ * @returns the authority, or '' when the header is unusable.
+ */
+export declare function requestAuthority(request: IncomingMessage): string;
+/**
+ * Build the feed route.
+ * @param deps - the owning service's read surface.
+ * @returns the routes to register on the web server.
+ */
+export declare function makeNotifyRoutes(deps: NotifyRouteDeps): WebRoute[];
+//# sourceMappingURL=host-routes.d.ts.map

package/lib/types/host/services/notify/host-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-routes.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/notify/host-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,WAAW,CAAA;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAQ/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AAE7D,gDAAgD;AAChD,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAA;IACb,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAA;CACd;AAED,4DAA4D;AAC5D,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,GAAG,EAAE,MAAM,SAAS,CAAA;IACpB,6DAA6D;IAC7D,YAAY,EAAE,MAAM,MAAM,CAAA;IAC1B,+DAA+D;IAC/D,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAA;IACjD,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,OAAO,CAAA;CACxB;AAOD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS,CAiBvF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAKjE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,QAAQ,EAAE,CAyBlE"}

package/lib/types/host/services/notify/host-routes.js

@@ -0,0 +1,112 @@
+/**
+ * The one host route the notification capability serves: a read-only feed of
+ * finished runs.
+ *
+ * It is a privileged read surface like every other web-all host route family
+ * and goes through the shared admission fence, because the feed names the
+ * conversations this machine has been running. A partially mounted plugin can
+ * never widen access: without the fence service the strict loopback rule
+ * applies.
+ *
+ * There is deliberately no write route. A client's read watermark lives on the
+ * client, so the host keeps no per-client state to acknowledge and exposes no
+ * mutation an attacker could aim at. The only effect a caller can have is
+ * reading, which is why this family needs no CSRF-shaped defence beyond the
+ * fence itself.
+ */
+import { NOTIFY_FEED_PATH, clampLimit, clampWatermark, } from "../../../core/notify/contract.js";
+import { isLoopbackRequest } from "../access-trust/trust.js";
+function writeJson(response, status, body) {
+    response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+    response.end(JSON.stringify(body));
+}
+/**
+ * Read `since` and `limit` out of a request URL.
+ *
+ * Both are clamped rather than rejected: a client sending nonsense is asking
+ * for an answer, not for a diagnostic, and the bounded log already limits what
+ * any of these values can do.
+ *
+ * @param request - the request whose query string is read.
+ * @param defaultLimit - the limit used when the caller does not supply one.
+ * @returns the effective query.
+ */
+export function readFeedQuery(request, defaultLimit) {
+    let search = '';
+    try {
+        search = new URL(request.url ?? '/', 'http://feed.invalid').search;
+    }
+    catch {
+        search = '';
+    }
+    let params;
+    try {
+        params = new URLSearchParams(search);
+    }
+    catch {
+        params = new URLSearchParams();
+    }
+    return {
+        since: clampWatermark(params.get('since') ?? ''),
+        limit: clampLimit(params.get('limit') ?? '', defaultLimit),
+    };
+}
+/**
+ * The authority to report as this feed's origin.
+ *
+ * It comes from the request's own `Host` header rather than from configuration,
+ * because the caller reached the machine under that name and a client listing
+ * several machines must be able to label each row with what it dialed. A header
+ * carrying separators or whitespace is not an authority and is reported empty
+ * instead of being echoed into a document.
+ *
+ * @param request - the request being answered.
+ * @returns the authority, or '' when the header is unusable.
+ */
+export function requestAuthority(request) {
+    const raw = request.headers.host;
+    const value = typeof raw === 'string' ? raw.trim() : '';
+    if (value === '' || value.length > 255 || /[\s/\\@?#]/.test(value))
+        return '';
+    return value;
+}
+/**
+ * Build the feed route.
+ * @param deps - the owning service's read surface.
+ * @returns the routes to register on the web server.
+ */
+export function makeNotifyRoutes(deps) {
+    const isTrusted = deps.isTrusted ?? isLoopbackRequest;
+    const enabled = deps.enabled ?? (() => true);
+    return [
+        {
+            kind: 'exact',
+            path: NOTIFY_FEED_PATH,
+            handler: (request, response) => {
+                if (!isTrusted(request)) {
+                    writeJson(response, 403, { error: 'forbidden' });
+                    return;
+                }
+                // The capability's switch gates reads as well as writes. A disabled
+                // capability that still answers would publish the list of conversations
+                // this machine has been running, which is the whole reason it is off.
+                if (!enabled()) {
+                    writeJson(response, 409, { error: 'notify-disabled' });
+                    return;
+                }
+                if (request.method !== 'GET') {
+                    writeJson(response, 405, { error: 'method-not-allowed' });
+                    return;
+                }
+                const query = readFeedQuery(request, deps.defaultLimit());
+                const log = deps.log();
+                const body = {
+                    origin: requestAuthority(request),
+                    latest: log.latest,
+                    notices: log.since(query.since, query.limit),
+                };
+                writeJson(response, 200, body);
+            },
+        },
+    ];
+}

package/lib/types/host/services/notify/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Notification capability: records finished runs, serves them, and pushes them.
+ *
+ * Where it sits. `dsh-session` already owns the durable answer to "what
+ * happened" (the append-only log) and `dsh-agent` owns the live answer to "is
+ * anything still running" (`agent/status`). This domain adds the third thing
+ * neither provides: a small, recent, cross-surface answer to "did the work I
+ * left running finish, and how did it end" that a phone or a desktop fleet list
+ * can read without holding a session log.
+ *
+ * What it therefore does NOT do. It keeps no durable copy of anything the
+ * session log already holds — see `core/notify/feed.ts` for why the notice log
+ * is deliberately in-memory. It records nothing for subagent sessions, because
+ * a child's turns are internal to a parent's work and a dot that lights up for
+ * every delegation is a dot nobody trusts. It records nothing for a turn that
+ * never entered a step, because an empty turn is not finished work.
+ *
+ * Two delivery shapes, one setting. `each-turn` reports every finished turn;
+ * `idle` waits until the agent has no driver left and reports the batch, which
+ * is what a notification is for. The feed ignores the setting entirely and
+ * always records every eligible turn, so a client's badge stays accurate no
+ * matter which push shape the deployment chose.
+ *
+ * @module dsh-web-all/notify
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type RunNotice } from '../../../core/notify/contract.ts';
+import { resolveFeishuCredentials, type NotifyConfig } from './config.ts';
+export { Config, NOTIFY_SETTINGS_NAMESPACE, resolveFeishuCredentials } from './config.ts';
+export { FeishuSender, composeFeishuText } from './feishu-sender.ts';
+export { makeNotifyRoutes, readFeedQuery, requestAuthority } from './host-routes.ts';
+export type { DeliveryAttempt } from './feishu-sender.ts';
+/** The sender surface this domain needs, so tests can supply their own. */
+export interface NotifySender {
+    notify(notices: readonly RunNotice[]): Promise<void>;
+    readonly recipients: readonly string[];
+    readonly domain: string;
+}
+/** Injectables that let tests run the domain without a tenant or a clock. */
+export interface NotifyServiceDeps {
+    env?: NodeJS.ProcessEnv;
+    /** Name this machine reports in a pushed message. */
+    hostLabel?: string;
+    /** Builds the outbound sender; returns null when nothing can be sent. */
+    createSender?: (options: {
+        credentials: ReturnType<typeof resolveFeishuCredentials>;
+        recipients: readonly string[];
+        hostLabel: string;
+    }) => NotifySender | null;
+}
+/** Minimal shape of the session the domain reads. */
+interface SessionLike {
+    id?: unknown;
+    header?: {
+        origin?: unknown;
+        delegationDepth?: unknown;
+    } | undefined;
+}
+/**
+ * Whether a session belongs to a subagent.
+ *
+ * `delegationDepth` is the durable field (a resumed child keeps its depth);
+ * `origin` is the coarser presentation marker. Either one answering "child" is
+ * enough, because recording a child's finished turn would put internal
+ * delegation on the same list as the user's own work.
+ *
+ * @param session - the session the event belongs to.
+ * @returns true when the session is a subagent child.
+ */
+export declare function isSubagentSession(session: SessionLike | undefined): boolean;
+/**
+ * Register the notification capability.
+ *
+ * @param ctx - host plugin context.
+ * @param base - namespace value used when the family settings document has none.
+ * @param deps - injectables for tests.
+ * @returns the disposer releasing the route, the subscriptions and the sender.
+ */
+export declare function register(ctx: Context, base?: NotifyConfig, deps?: NotifyServiceDeps): () => void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/host/services/notify/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/notify/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAIlD,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,kCAAkC,CAAA;AAMnF,OAAO,EAIL,wBAAwB,EACxB,KAAK,YAAY,EAClB,MAAM,aAAa,CAAA;AAIpB,OAAO,EAAE,MAAM,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AACzF,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AACpE,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACpF,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAKzD,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,yEAAyE;IACzE,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QACvB,WAAW,EAAE,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAA;QACxD,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;QAC7B,SAAS,EAAE,MAAM,CAAA;KAClB,KAAK,YAAY,GAAG,IAAI,CAAA;CAC1B;AASD,qDAAqD;AACrD,UAAU,WAAW;IACnB,EAAE,CAAC,EAAE,OAAO,CAAA;IACZ,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,CAAA;CACrE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAM3E;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,GAAE,YAAiB,EAAE,IAAI,GAAE,iBAAsB,GAAG,MAAM,IAAI,CA6LxG"}