work-ally 0.2.0-alpha.1

package/bridge/src/session-store.ts

@@ -0,0 +1,380 @@
+import path from 'node:path';
+import { conversationKey, ensureDir, nowIso, readJsonFile, sanitizeSegment } from './utils.ts';
+import {
+  clearInboundReceipt,
+  completeInboundReceipt,
+  getInboundReceipt,
+  getOutboundDelivery,
+  listPendingOutboundDeliveries,
+  markOutboundDelivered,
+  noteInboundReceipt,
+  recordOutboundDelivery,
+  type ReceiptClaimResult,
+} from './session-store-delivery.ts';
+import {
+  clearPendingUserInput,
+  findHiddenPendingUserInput,
+  findApproval,
+  findApprovalByRequestId,
+  findPendingUserInputByRequestId,
+  getApproval,
+  getPendingUserInput,
+  listHiddenPendingApprovals,
+  listPendingApprovals,
+  markApprovalVisible,
+  markPendingUserInputVisible,
+  notePendingUserInput,
+  recordApproval,
+  resolveApproval,
+} from './session-store-human-gate.ts';
+import {
+  bindThread as bindStoredThread,
+  clearActiveTurn as clearStoredActiveTurn,
+  ensureSession as ensureStoredSession,
+  ensureSessionDirs as ensureStoredSessionDirs,
+  listSessions as listStoredSessions,
+  normalizeSessionMeta,
+  noteLatestInbound as noteStoredLatestInbound,
+} from './session-store-meta.ts';
+import {
+  getInboundAcceptance as getStoredInboundAcceptance,
+  noteInboundObserved as noteStoredInboundObserved,
+  updateInboundAcceptance as updateStoredInboundAcceptance,
+} from './session-store-inbound-acceptance.ts';
+import {
+  findLatestDeliveryIssue,
+  getTurnLedger,
+  getTurnRecord,
+  markActiveTurn,
+  markTurnDelivery,
+  markTurnRunning,
+  markTurnSuppressed,
+  noteTurnTerminalState,
+  recordTurn,
+} from './session-store-turn-ledger.ts';
+import type {
+  ApprovalRecord,
+  ConversationRef,
+  InboundAcceptanceRecord,
+  InboundReceipt,
+  OutboundDeliveryRecord,
+  PendingUserInputRecord,
+  SessionMeta,
+  TurnLedgerRecord,
+  TurnRecord,
+  UserInputRequest,
+} from './types.ts';
+
+export class SessionStore {
+  private readonly sessionsDir: string;
+
+  constructor(sessionsDir: string) {
+    this.sessionsDir = sessionsDir;
+    ensureDir(sessionsDir);
+  }
+
+  resolveSessionKey(ref: ConversationRef): string {
+    return conversationKey(ref.channel, ref.conversationId);
+  }
+
+  resolveSessionDir(ref: ConversationRef): string {
+    return path.join(this.sessionsDir, this.resolveSessionKey(ref));
+  }
+
+  private sessionMetaStoreDeps() {
+    return {
+      sessionsDir: this.sessionsDir,
+      resolveSessionKey: (ref: ConversationRef) => this.resolveSessionKey(ref),
+      resolveSessionDir: (ref: ConversationRef) => this.resolveSessionDir(ref),
+      metaFile: (ref: ConversationRef) => this.metaFile(ref),
+      eventsFile: (ref: ConversationRef) => this.eventsFile(ref),
+    };
+  }
+
+  private humanGateStoreDeps() {
+    return {
+      sessionsDir: this.sessionsDir,
+      ensureSessionDirs: (ref: ConversationRef) => this.ensureSessionDirs(ref),
+      ensureSession: (ref: ConversationRef) => this.ensureSession(ref),
+      getSession: (ref: ConversationRef) => this.getSession(ref),
+      normalizeMeta: (ref: ConversationRef, current: SessionMeta | null, now?: string) => this.normalizeMeta(ref, current, now),
+      metaFile: (ref: ConversationRef) => this.metaFile(ref),
+      eventsFile: (ref: ConversationRef) => this.eventsFile(ref),
+      approvalFile: (ref: ConversationRef, approvalId: string) => this.approvalFile(ref, approvalId),
+      pendingUserInputFile: (ref: ConversationRef, requestId: string | number) => this.pendingUserInputFile(ref, requestId),
+    };
+  }
+
+  private inboundAcceptanceStoreDeps() {
+    return {
+      ensureSessionDirs: (ref: ConversationRef) => this.ensureSessionDirs(ref),
+      eventsFile: (ref: ConversationRef) => this.eventsFile(ref),
+      inboundAcceptanceFile: (ref: ConversationRef, messageId: string) => this.inboundAcceptanceFile(ref, messageId),
+    };
+  }
+
+  private turnLedgerStoreDeps() {
+    return {
+      ensureSessionDirs: (ref: ConversationRef) => this.ensureSessionDirs(ref),
+      ensureSession: (ref: ConversationRef) => this.ensureSession(ref),
+      getSession: (ref: ConversationRef) => this.getSession(ref),
+      resolveSessionDir: (ref: ConversationRef) => this.resolveSessionDir(ref),
+      metaFile: (ref: ConversationRef) => this.metaFile(ref),
+      eventsFile: (ref: ConversationRef) => this.eventsFile(ref),
+      turnLedgerFile: (ref: ConversationRef, turnId: string) => this.turnLedgerFile(ref, turnId),
+      updateInboundAcceptance: (
+        ref: ConversationRef,
+        messageId: string,
+        seed: Partial<InboundAcceptanceRecord> = {},
+        mutate?: (record: InboundAcceptanceRecord, now: string) => void,
+      ) => this.updateInboundAcceptance(ref, messageId, seed, mutate),
+    };
+  }
+
+  private deliveryStoreDeps() {
+    return {
+      ensureSessionDirs: (ref: ConversationRef) => this.ensureSessionDirs(ref),
+      resolveSessionDir: (ref: ConversationRef) => this.resolveSessionDir(ref),
+      eventsFile: (ref: ConversationRef) => this.eventsFile(ref),
+      receiptFile: (ref: ConversationRef, messageId: string) => this.receiptFile(ref, messageId),
+      seenInboundFile: (ref: ConversationRef, messageId: string) => this.seenInboundFile(ref, messageId),
+      outboundDeliveryFile: (ref: ConversationRef, sourceKey: string) => this.outboundDeliveryFile(ref, sourceKey),
+      getSession: (ref: ConversationRef) => this.getSession(ref),
+      getInboundAcceptance: (ref: ConversationRef, messageId: string) => this.getInboundAcceptance(ref, messageId),
+      noteInboundObserved: (ref: ConversationRef, messageId: string) => this.noteInboundObserved(ref, messageId),
+    };
+  }
+
+  private ensureSessionDirs(ref: ConversationRef): string {
+    return ensureStoredSessionDirs(this.sessionMetaStoreDeps(), ref);
+  }
+
+  private normalizeMeta(ref: ConversationRef, current: SessionMeta | null, now = nowIso()): SessionMeta {
+    return normalizeSessionMeta(this.sessionMetaStoreDeps(), ref, current, now);
+  }
+
+  private metaFile(ref: ConversationRef): string {
+    return path.join(this.resolveSessionDir(ref), 'meta.json');
+  }
+
+  private eventsFile(ref: ConversationRef): string {
+    return path.join(this.resolveSessionDir(ref), 'events.ndjson');
+  }
+
+  private approvalFile(ref: ConversationRef, approvalId: string): string {
+    return path.join(this.resolveSessionDir(ref), 'approvals', `${sanitizeSegment(approvalId)}.json`);
+  }
+
+  private receiptFile(ref: ConversationRef, messageId: string): string {
+    return path.join(this.resolveSessionDir(ref), 'receipts', `${sanitizeSegment(messageId)}.json`);
+  }
+
+  private pendingUserInputFile(ref: ConversationRef, requestId: string | number): string {
+    return path.join(this.resolveSessionDir(ref), 'user-inputs', `${sanitizeSegment(String(requestId))}.json`);
+  }
+
+  private seenInboundFile(ref: ConversationRef, messageId: string): string {
+    return path.join(this.resolveSessionDir(ref), 'seen-inbounds', `${sanitizeSegment(messageId)}.json`);
+  }
+
+  private turnLedgerFile(ref: ConversationRef, turnId: string): string {
+    return path.join(this.resolveSessionDir(ref), 'turn-ledger', `${sanitizeSegment(turnId)}.json`);
+  }
+
+  private outboundDeliveryFile(ref: ConversationRef, sourceKey: string): string {
+    return path.join(this.resolveSessionDir(ref), 'outbound-delivery', `${sanitizeSegment(sourceKey)}.json`);
+  }
+
+  private inboundAcceptanceFile(ref: ConversationRef, messageId: string): string {
+    return path.join(this.resolveSessionDir(ref), 'inbound-ledger', `${sanitizeSegment(messageId)}.json`);
+  }
+
+  private updateInboundAcceptance(
+    ref: ConversationRef,
+    messageId: string,
+    seed: Partial<InboundAcceptanceRecord> = {},
+    mutate?: (record: InboundAcceptanceRecord, now: string) => void,
+  ): InboundAcceptanceRecord {
+    return updateStoredInboundAcceptance(this.inboundAcceptanceStoreDeps(), ref, messageId, seed, mutate);
+  }
+
+  ensureSession(ref: ConversationRef): SessionMeta {
+    return ensureStoredSession(this.sessionMetaStoreDeps(), ref);
+  }
+
+  getSession(ref: ConversationRef): SessionMeta | null {
+    const meta = readJsonFile(this.metaFile(ref)) as SessionMeta | null;
+    if (!meta) {
+      return null;
+    }
+    return this.normalizeMeta(ref, meta, meta.updatedAt || nowIso());
+  }
+
+  bindThread(ref: ConversationRef, threadId: string | null): SessionMeta {
+    return bindStoredThread(this.sessionMetaStoreDeps(), ref, threadId);
+  }
+
+  noteLatestInbound(ref: ConversationRef, details: { messageId?: string | null; promptPreview?: string | null }): SessionMeta {
+    return noteStoredLatestInbound(this.sessionMetaStoreDeps(), ref, details);
+  }
+
+  markActiveTurn(
+    ref: ConversationRef,
+    turnId: string,
+    details?: { messageId?: string | null; promptPreview?: string | null },
+  ): SessionMeta {
+    return markActiveTurn(this.turnLedgerStoreDeps(), ref, turnId, details);
+  }
+
+  markTurnRunning(ref: ConversationRef, turnId: string): TurnLedgerRecord {
+    return markTurnRunning(this.turnLedgerStoreDeps(), ref, turnId);
+  }
+
+  noteTurnTerminalState(
+    ref: ConversationRef,
+    turnId: string,
+    details: { threadId: string; status: string; reply?: string | null; error?: string | null },
+  ): TurnLedgerRecord {
+    return noteTurnTerminalState(this.turnLedgerStoreDeps(), ref, turnId, details);
+  }
+
+  markTurnSuppressed(
+    ref: ConversationRef,
+    turnId: string,
+    details: { threadId?: string | null; suppressedByMessageId?: string | null; suppressedByTurnId?: string | null; reason: string },
+  ): TurnLedgerRecord {
+    return markTurnSuppressed(this.turnLedgerStoreDeps(), ref, turnId, details);
+  }
+
+  markTurnDelivery(ref: ConversationRef, turnId: string, status: 'delivered' | 'delivery_unavailable'): TurnLedgerRecord {
+    return markTurnDelivery(this.turnLedgerStoreDeps(), ref, turnId, status);
+  }
+
+  findLatestDeliveryIssue(ref: ConversationRef): TurnLedgerRecord | null {
+    return findLatestDeliveryIssue(this.turnLedgerStoreDeps(), ref);
+  }
+
+  getTurnLedger(ref: ConversationRef, turnId: string): TurnLedgerRecord | null {
+    return getTurnLedger(this.turnLedgerStoreDeps(), ref, turnId);
+  }
+
+  getTurnRecord(ref: ConversationRef, turnId: string): TurnRecord | null {
+    return getTurnRecord(this.turnLedgerStoreDeps(), ref, turnId);
+  }
+
+  clearActiveTurn(ref: ConversationRef): SessionMeta {
+    return clearStoredActiveTurn(this.sessionMetaStoreDeps(), ref);
+  }
+
+  hasActiveTurn(ref: ConversationRef): boolean {
+    const meta = this.getSession(ref);
+    return Boolean(meta?.activeTurnId);
+  }
+
+  noteInboundObserved(ref: ConversationRef, messageId: string): InboundAcceptanceRecord {
+    return noteStoredInboundObserved(this.inboundAcceptanceStoreDeps(), ref, messageId);
+  }
+
+  getInboundAcceptance(ref: ConversationRef, messageId: string): InboundAcceptanceRecord | null {
+    return getStoredInboundAcceptance(this.inboundAcceptanceStoreDeps(), ref, messageId);
+  }
+
+  noteInboundReceipt(ref: ConversationRef, messageId: string): ReceiptClaimResult {
+    return noteInboundReceipt(this.deliveryStoreDeps(), ref, messageId);
+  }
+
+  completeInboundReceipt(ref: ConversationRef, messageId: string): InboundReceipt {
+    return completeInboundReceipt(this.deliveryStoreDeps(), ref, messageId);
+  }
+
+  clearInboundReceipt(ref: ConversationRef, messageId: string): void {
+    return clearInboundReceipt(this.deliveryStoreDeps(), ref, messageId);
+  }
+
+  getInboundReceipt(ref: ConversationRef, messageId: string): InboundReceipt | null {
+    return getInboundReceipt(this.deliveryStoreDeps(), ref, messageId);
+  }
+
+  recordTurn(ref: ConversationRef, turn: TurnRecord): void {
+    return recordTurn(this.turnLedgerStoreDeps(), ref, turn);
+  }
+
+  recordApproval(ref: ConversationRef, approval: ApprovalRecord, options: { visible?: boolean } = {}): void {
+    return recordApproval(this.humanGateStoreDeps(), ref, approval, options);
+  }
+
+  markApprovalVisible(ref: ConversationRef, approvalId: string): ApprovalRecord | null {
+    return markApprovalVisible(this.humanGateStoreDeps(), ref, approvalId);
+  }
+
+  resolveApproval(ref: ConversationRef, approvalId: string, status: ApprovalRecord['status']): ApprovalRecord | null {
+    return resolveApproval(this.humanGateStoreDeps(), ref, approvalId, status);
+  }
+
+  notePendingUserInput(ref: ConversationRef, request: UserInputRequest, options: { visible?: boolean } = {}): PendingUserInputRecord {
+    return notePendingUserInput(this.humanGateStoreDeps(), ref, request, options);
+  }
+
+  markPendingUserInputVisible(ref: ConversationRef, requestId: string | number): PendingUserInputRecord | null {
+    return markPendingUserInputVisible(this.humanGateStoreDeps(), ref, requestId);
+  }
+
+  getPendingUserInput(ref: ConversationRef): PendingUserInputRecord | null {
+    return getPendingUserInput(this.humanGateStoreDeps(), ref);
+  }
+
+  findPendingUserInputByRequestId(requestId: string | number): { meta: SessionMeta; request: PendingUserInputRecord } | null {
+    return findPendingUserInputByRequestId(this.humanGateStoreDeps(), requestId);
+  }
+
+  clearPendingUserInput(ref: ConversationRef, details?: { messageId?: string | null; answerPreview?: string | null }): void {
+    return clearPendingUserInput(this.humanGateStoreDeps(), ref, details);
+  }
+
+  listSessions(): SessionMeta[] {
+    return listStoredSessions(this.sessionMetaStoreDeps());
+  }
+
+  findApproval(approvalId: string): { meta: SessionMeta; approval: ApprovalRecord } | null {
+    return findApproval(this.humanGateStoreDeps(), approvalId);
+  }
+
+  findApprovalByRequestId(requestId: string | number): { meta: SessionMeta; approval: ApprovalRecord } | null {
+    return findApprovalByRequestId(this.humanGateStoreDeps(), requestId);
+  }
+
+  getApproval(ref: ConversationRef, approvalId: string): ApprovalRecord | null {
+    return getApproval(this.humanGateStoreDeps(), ref, approvalId);
+  }
+
+  listPendingApprovals(ref: ConversationRef): ApprovalRecord[] {
+    return listPendingApprovals(this.humanGateStoreDeps(), ref);
+  }
+
+  listHiddenPendingApprovals(ref: ConversationRef, turnId?: string | null): ApprovalRecord[] {
+    return listHiddenPendingApprovals(this.humanGateStoreDeps(), ref, turnId);
+  }
+
+  findHiddenPendingUserInput(ref: ConversationRef, turnId?: string | null): PendingUserInputRecord | null {
+    return findHiddenPendingUserInput(this.humanGateStoreDeps(), ref, turnId);
+  }
+
+  recordOutboundDelivery(
+    ref: ConversationRef,
+    record: Omit<OutboundDeliveryRecord, 'updatedAt'>,
+  ): OutboundDeliveryRecord {
+    return recordOutboundDelivery(this.deliveryStoreDeps(), ref, record);
+  }
+
+  markOutboundDelivered(ref: ConversationRef, sourceKey: string): OutboundDeliveryRecord | null {
+    return markOutboundDelivered(this.deliveryStoreDeps(), ref, sourceKey);
+  }
+
+  getOutboundDelivery(ref: ConversationRef, sourceKey: string): OutboundDeliveryRecord | null {
+    return getOutboundDelivery(this.deliveryStoreDeps(), ref, sourceKey);
+  }
+
+  listPendingOutboundDeliveries(ref: ConversationRef): OutboundDeliveryRecord[] {
+    return listPendingOutboundDeliveries(this.deliveryStoreDeps(), ref);
+  }
+}

package/bridge/src/system-notify.ts

@@ -0,0 +1,220 @@
+import { pathToFileURL } from 'node:url';
+import { FakeChannelAdapter } from './channels/fake/adapter.ts';
+import { FeishuAdapter } from './channels/feishu/adapter.ts';
+import {
+  describeChannelDeliveryIssue,
+  isNonFatalChannelDeliveryError,
+  normalizeChannelDeliveryError,
+  recordBridgeDeliveryIssue,
+  clearBridgeDeliveryIssue,
+} from './channel-delivery.ts';
+import type { WorkAllyConfig } from './config.ts';
+import { loadConfig, validateConfig } from './config.ts';
+import { SessionStore } from './session-store.ts';
+import type { ChannelAdapter } from './channel-types.ts';
+import type { ConversationRef, SessionMeta } from './types.ts';
+
+export type SystemNoticeKind = 'start' | 'stop' | 'text';
+export type NoticeTargetSource = 'latest_session' | 'default_push_target' | 'allowlisted_user';
+
+export interface ResolvedNoticeConversationRef {
+  conversationRef: ConversationRef;
+  source: NoticeTargetSource;
+}
+
+export interface SendSystemNoticeOptions {
+  config?: WorkAllyConfig;
+  channel?: Pick<ChannelAdapter, 'send'>;
+  sessionStore?: Pick<SessionStore, 'listSessions'>;
+  strictDelivery?: boolean;
+}
+
+export interface SendSystemNoticeResult {
+  delivered: boolean;
+  skippedReason?: 'channel_not_feishu' | 'no_target' | 'delivery_unavailable';
+  issue?: ReturnType<typeof describeChannelDeliveryIssue>;
+}
+
+export const SYSTEM_MESSAGE_PREFIX = '**【系统消息】**';
+export const START_NOTICE_TEXT = `${SYSTEM_MESSAGE_PREFIX} 我来上班咯，有事随时叫我～`;
+export const STOP_NOTICE_TEXT = `${SYSTEM_MESSAGE_PREFIX} 我先下班咯，拜拜～`;
+
+function createChannel(config: WorkAllyConfig): ChannelAdapter {
+  if (config.channel.impl === 'fake') {
+    return new FakeChannelAdapter({ handleInbound: async () => undefined });
+  }
+  return new FeishuAdapter(
+    { handleInbound: async () => undefined },
+    {
+      appId: config.feishu.appId!,
+      appSecret: config.feishu.appSecret!,
+      reactEmoji: config.feishu.reactEmoji,
+      allowedUserIds: config.channel.allowedUserIds,
+    },
+  );
+}
+
+function strictDeliveryEnabled(): boolean {
+  return ['1', 'true', 'yes', 'on'].includes(String(process.env.WORK_ALLY_SYSTEM_NOTICE_STRICT || '').trim().toLowerCase());
+}
+
+export function formatStartupDeliveryFailure(error: unknown): string {
+  const normalized = normalizeChannelDeliveryError('feishu', error);
+  if (isNonFatalChannelDeliveryError(normalized)) {
+    const issueMessageByKind: Record<string, string> = {
+      permission_denied: '当前机器人还没有发消息权限。',
+      app_not_ready: '当前机器人还没有完成审核发布。',
+    };
+    const issueMessage = issueMessageByKind[normalized.issue.kind] || '当前机器人还不能对外发消息。';
+    return `Feishu 启动探测失败（${normalized.issue.kind}）：${issueMessage} ${normalized.issue.guidance}`;
+  }
+  if (normalized instanceof Error) {
+    return normalized.message;
+  }
+  return String(normalized);
+}
+
+export function latestConversationRef(sessions: SessionMeta[]): ConversationRef | null {
+  const latest = [...sessions]
+    .filter((session) => session.conversationRef.channel === 'feishu')
+    .sort((left, right) => String(right.updatedAt).localeCompare(String(left.updatedAt)))[0];
+  return latest?.conversationRef || null;
+}
+
+export function formatSystemNoticeText(text: string): string {
+  const normalized = String(text || '').trim();
+  if (!normalized) {
+    return SYSTEM_MESSAGE_PREFIX;
+  }
+  if (normalized.startsWith(SYSTEM_MESSAGE_PREFIX)) {
+    return normalized;
+  }
+  return `${SYSTEM_MESSAGE_PREFIX} ${normalized}`;
+}
+
+export function resolveNoticeText(kind: SystemNoticeKind, customText?: string): string {
+  if (kind === 'start') {
+    return START_NOTICE_TEXT;
+  }
+  if (kind === 'stop') {
+    return STOP_NOTICE_TEXT;
+  }
+  return formatSystemNoticeText(customText || '');
+}
+
+export function resolveNoticeConversationRef(sessions: SessionMeta[], config: Pick<WorkAllyConfig, 'defaultPushTarget' | 'channel'>): ResolvedNoticeConversationRef | null {
+  const latest = latestConversationRef(sessions);
+  if (latest) {
+    return {
+      conversationRef: latest,
+      source: 'latest_session',
+    };
+  }
+
+  const pushTarget = String(config.defaultPushTarget || '').trim();
+  if (pushTarget) {
+    return {
+      conversationRef: {
+        channel: 'feishu',
+        conversationId: pushTarget,
+        userId: pushTarget,
+        chatType: pushTarget.startsWith('ou_') ? 'p2p' : 'dm',
+      },
+      source: 'default_push_target',
+    };
+  }
+
+  if (config.channel.allowedUserIds.length === 1) {
+    const userId = config.channel.allowedUserIds[0];
+    return {
+      conversationRef: {
+        channel: 'feishu',
+        conversationId: userId,
+        userId,
+        chatType: 'p2p',
+      },
+      source: 'allowlisted_user',
+    };
+  }
+
+  return null;
+}
+
+function shouldEnforceStrictDelivery(options: SendSystemNoticeOptions, target: ResolvedNoticeConversationRef): boolean {
+  return Boolean(options.strictDelivery && target.source !== 'allowlisted_user');
+}
+
+function normalizeNoticeKind(value: string | undefined): SystemNoticeKind {
+  const normalized = String(value || 'stop').trim().toLowerCase();
+  if (normalized === 'start') {
+    return 'start';
+  }
+  if (normalized === 'text') {
+    return 'text';
+  }
+  return 'stop';
+}
+
+export async function sendSystemNotice(kind: SystemNoticeKind, customText?: string, options: SendSystemNoticeOptions = {}): Promise<SendSystemNoticeResult> {
+  const config = options.config || loadConfig();
+  validateConfig(config);
+  if (config.channel.impl !== 'feishu') {
+    return { delivered: false, skippedReason: 'channel_not_feishu' };
+  }
+
+  const sessionStore = options.sessionStore || new SessionStore(config.paths.sessionsDir);
+  const target = resolveNoticeConversationRef(sessionStore.listSessions(), config);
+  if (!target) {
+    return { delivered: false, skippedReason: 'no_target' };
+  }
+
+  const channel = options.channel || createChannel(config);
+  const outbound = {
+    type: 'status_reply' as const,
+    conversationRef: target.conversationRef,
+    text: resolveNoticeText(kind, customText),
+  };
+
+  try {
+    await channel.send(outbound);
+    clearBridgeDeliveryIssue(config.paths.runtimeDir);
+    return { delivered: true };
+  } catch (error) {
+    const normalized = normalizeChannelDeliveryError(config.channel.impl, error);
+    if (isNonFatalChannelDeliveryError(normalized)) {
+      recordBridgeDeliveryIssue(config.paths.runtimeDir, normalized);
+      if (shouldEnforceStrictDelivery(options, target)) {
+        throw normalized;
+      }
+      return {
+        delivered: false,
+        skippedReason: 'delivery_unavailable',
+        issue: describeChannelDeliveryIssue(normalized),
+      };
+    }
+    throw normalized;
+  }
+}
+
+export async function main(args: string[] = process.argv.slice(2)): Promise<void> {
+  const kind = normalizeNoticeKind(args[0]);
+  const customText = kind === 'text' ? args.slice(1).join(' ').trim() : '';
+  if (kind === 'text' && !customText) {
+    return;
+  }
+
+  await sendSystemNotice(kind, customText, {
+    strictDelivery: strictDeliveryEnabled(),
+  });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    if (isNonFatalChannelDeliveryError(error)) {
+      console.error(formatStartupDeliveryFailure(error));
+      process.exit(2);
+    }
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}