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

package/src/core/lark-inbox/queue.ts

@@ -0,0 +1,100 @@
+/** Pure queue-envelope logic shared by host and browser TypeScript programs. */
+
+export const ENVELOPE_VERSION = 1 as const
+export const INBOX_EVENT_TYPE = 'im.message.receive_v1' as const
+
+export interface LarkInboxEnvelope {
+  envelopeVersion: 1
+  eventId: string
+  receivedAt: string
+  eventType: string
+  chatType?: 'p2p' | 'group'
+  chatId?: string
+  senderOpenId?: string
+  messageId?: string
+  messageType?: string
+  content: string
+  mentionBot?: boolean
+  raw?: unknown
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+function resolveSenderOpenId(sender: unknown, inner: unknown): string | undefined {
+  if (!isRecord(sender)) return isRecord(inner) ? asString(inner.sender_id) : undefined
+  const senderId = sender.sender_id
+  if (typeof senderId === 'string' && senderId.length > 0) return senderId
+  if (isRecord(senderId)) {
+    const openId = asString(senderId.open_id)
+    if (openId) return openId
+  }
+  return isRecord(inner) ? asString(inner.sender_id) : undefined
+}
+
+/** Normalize either SDK event shape into the stable queue envelope. */
+export function toEnvelope(
+  event: unknown,
+  opts: { mentionBot?: boolean; receivedAt?: string } = {},
+): LarkInboxEnvelope {
+  const source = isRecord(event) ? event : {}
+  const header = isRecord(source.header) ? source.header : {}
+  const inner = isRecord(source.event) ? source.event : source
+  const message = isRecord(inner.message) ? inner.message : {}
+  const messageId = asString(message.message_id) ?? asString(inner.message_id)
+  const eventId = asString(header.event_id) ?? messageId ?? ''
+  const senderOpenId = resolveSenderOpenId(isRecord(inner.sender) ? inner.sender : undefined, inner)
+  const chatTypeRaw = asString(message.chat_type) ?? asString(inner.chat_type)
+  const chatType = chatTypeRaw === 'p2p' || chatTypeRaw === 'group' ? chatTypeRaw : undefined
+  const contentRaw = message.content
+  let content = ''
+  if (typeof contentRaw === 'string') content = contentRaw
+  else if (isRecord(contentRaw)) content = JSON.stringify(contentRaw)
+
+  return {
+    envelopeVersion: ENVELOPE_VERSION,
+    eventId,
+    receivedAt: opts.receivedAt ?? new Date().toISOString(),
+    eventType: INBOX_EVENT_TYPE,
+    chatType,
+    chatId: asString(message.chat_id) ?? asString(inner.chat_id),
+    senderOpenId,
+    messageId,
+    messageType: asString(message.message_type) ?? asString(inner.message_type),
+    content,
+    mentionBot: opts.mentionBot,
+    raw: source,
+  }
+}
+
+export function envelopeToLine(envelope: LarkInboxEnvelope): string {
+  return JSON.stringify(envelope) + '\n'
+}
+
+export function parseEnvelopeLine(line: string): LarkInboxEnvelope | null {
+  try {
+    const parsed: unknown = JSON.parse(line)
+    if (!isRecord(parsed) || parsed.envelopeVersion !== ENVELOPE_VERSION || typeof parsed.eventId !== 'string') return null
+    return parsed as unknown as LarkInboxEnvelope
+  } catch {
+    return null
+  }
+}
+
+export function dayPart(ts: number): string {
+  const date = new Date(ts)
+  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`
+}
+
+function sanitizeSegment(segment: string): string {
+  return segment.replace(/[^a-zA-Z0-9._-]/g, '_')
+}
+
+export function inboxFilePath(rootDir: string, eventType: string, ts: number): string {
+  return `${rootDir}/${sanitizeSegment(eventType)}/${dayPart(ts)}.jsonl`
+}

package/src/core/memoir/protocol.ts

@@ -0,0 +1,46 @@
+/**
+ * memoir 跨半区 wire 契约（host 与 client 双 program 编译）。
+ *
+ * 常量 + 纯类型：/api/dsh-memoir 前缀、section 枚举、条目/设置 shape。
+ * 不携带运行时身份。
+ */
+
+export const MEMOIR_API_PREFIX = '/api/dsh-memoir'
+
+/** 记忆分区。 */
+export type SectionKey = 'work' | 'lessons' | 'actions' | 'note'
+export const SECTION_KEYS: readonly SectionKey[] = ['work', 'lessons', 'actions', 'note']
+
+/** 条目状态。 */
+export type MemoirStatus = 'active' | 'superseded' | 'archived'
+
+/** 一个记忆条目（与路由/README 渲染契约一致）。 */
+export interface MemoirEntry {
+  id: string
+  title: string
+  content: string
+  section: SectionKey
+  status: MemoirStatus
+  createdAt: number
+  updatedAt: number
+  pinned: boolean
+  importance: number
+  tags?: string[]
+  supersedes?: string[]
+}
+
+/** 用户可调设置。 */
+export interface MemoirSettings {
+  enabled: boolean
+  announceToAgent: boolean
+  autoDistill: boolean
+  autoDistillEvery: number
+  autoDistillCooldownMin: number
+  autoDistillMinTools: number
+  hotMemoryTokens: number
+  hotMemoryMaxTokens: number
+  readDefaultLimit: number
+  readMaxLimit: number
+  sessionSnapshotMax: number
+  queryCacheSize: number
+}

package/src/core/no-browser-auth/contract.ts

@@ -0,0 +1,25 @@
+/**
+ * Cross-runtime contract for the optional BrowserAuth bypass.
+ *
+ * The bypass only changes the browser-token authentication decision. The
+ * connection service's Host/Origin request fence remains the authority for
+ * deciding whether a browser request can reach DSH at all.
+ */
+
+/** Stable settings/config namespace retained from the standalone capability. */
+export const NO_BROWSER_AUTH_NAMESPACE = 'dsh-no-browser-auth'
+
+/** The private BrowserAuth surface used by the host adapter. */
+export interface BrowserAuthLike {
+  isAuthenticated(request: unknown): boolean
+}
+
+/** Structural subset of the host connection service used by this capability. */
+export interface BrowserConnectionLike {
+  browserAuth?: BrowserAuthLike
+}
+
+/** Explicit opt-in configuration. Disabled by default inside web-all. */
+export interface NoBrowserAuthConfig {
+  enabled?: boolean
+}

package/src/core/notify/contract.ts

@@ -0,0 +1,236 @@
+/**
+ * The one description of a finished-run notice, shared by the host that records
+ * it and every surface that reads it.
+ *
+ * A notice answers one question — "did the work I left running finish, and how
+ * did it end?" — so the wire shape stays small enough to render as a phone
+ * notification title. Two of the three consumers (the desktop client and the
+ * mobile client) parse this JSON without this package's types, so the shape is
+ * documented here once and every reader narrows defensively.
+ *
+ * @module dsh-web-all/notify-contract
+ */
+
+/** Host route family prefix for the notification feed. */
+export const NOTIFY_API_PREFIX = '/api/dsh-notify'
+
+/** The read route every client polls. */
+export const NOTIFY_FEED_PATH = `${NOTIFY_API_PREFIX}/feed`
+
+/** Notices the host keeps and returns by default. */
+export const NOTIFY_DEFAULT_LIMIT = 20
+
+/** Upper bound for one request's `limit`, so a client cannot ask for everything. */
+export const NOTIFY_MAX_LIMIT = 100
+
+/** Sessions whose titles the host remembers, so a long-lived host cannot grow unbounded. */
+export const NOTIFY_TITLE_MEMORY = 200
+
+/**
+ * How a finished turn ended, collapsed from the extensible `TurnEndReason` map
+ * into the three answers a person acts on.
+ */
+export type NotifyOutcome = 'completed' | 'failed' | 'stopped'
+
+/** One finished turn, as the feed reports it. */
+export interface RunNotice {
+  /** Strictly increasing across the host's lifetime; a client's read watermark. */
+  readonly id: number
+  /** Epoch milliseconds when the turn ended. */
+  readonly at: number
+  /** Session the turn belonged to. */
+  readonly sessionId: string
+  /** Session title, else a short excerpt of the first human prompt, else ''. */
+  readonly title: string
+  /** Turn number inside the session. */
+  readonly turn: number
+  /** Raw `TurnEndReason` kind, kept verbatim because plugins extend that map. */
+  readonly reason: string
+  /** The collapse of `reason` a client can act on without knowing the map. */
+  readonly outcome: NotifyOutcome
+}
+
+/** What one finished turn is built from, before the host assigns its id. */
+export type RunNoticeInput = Omit<RunNotice, 'id' | 'outcome'> & { readonly outcome?: NotifyOutcome }
+
+/** The feed document. */
+export interface NotifyFeed {
+  /**
+   * Authority serving this feed, taken from the request's `Host` header.
+   *
+   * It is the origin the caller actually reached, not a configured name, so a
+   * client aggregating several machines can label each row with what it dialed.
+   */
+  readonly origin: string
+  /** Newest notice id, or 0 when none. A client stores it as its watermark. */
+  readonly latest: number
+  /** Notices newer than the request's `since`, oldest first, capped by `limit`. */
+  readonly notices: readonly RunNotice[]
+}
+
+/** Reasons that mean the model finished the work it was given. */
+const COMPLETED_REASONS = new Set(['completed', 'max-tokens'])
+
+/** Reasons that mean the turn ended because something went wrong. */
+const FAILED_REASONS = new Set(['error', 'blocked'])
+
+/** Reasons that mean the turn ended without either succeeding or failing. */
+const STOPPED_REASONS = new Set(['aborted', 'interrupted', 'forked'])
+
+/**
+ * Collapse one `TurnEndReason` kind into the outcome a client acts on.
+ *
+ * An unrecognized reason comes from a plugin that merged a new variant into the
+ * reason map. Reporting it as `completed` would put a success claim on something
+ * no one has inspected, so an unknown closure takes the neutral outcome and the
+ * caller still has {@link RunNotice.reason} to render verbatim.
+ *
+ * @param reason - the raw reason kind, or '' when the event carried none.
+ * @returns the outcome to record.
+ */
+export function outcomeOf(reason: string): NotifyOutcome {
+  if (COMPLETED_REASONS.has(reason)) return 'completed'
+  if (FAILED_REASONS.has(reason)) return 'failed'
+  if (STOPPED_REASONS.has(reason)) return 'stopped'
+  return 'stopped'
+}
+
+/** Chinese label for one outcome, shared so the three surfaces cannot drift. */
+export const OUTCOME_LABEL_ZH: Readonly<Record<NotifyOutcome, string>> = {
+  completed: '已完成',
+  failed: '出错',
+  stopped: '已结束',
+}
+
+/** Whether an outcome is worth interrupting a person for. */
+export function isNotifiable(outcome: NotifyOutcome): boolean {
+  return outcome === 'completed' || outcome === 'failed'
+}
+
+/**
+ * Clamp a request's `limit` into the range the host is willing to answer.
+ * @param value - the parsed query value, of unknown quality.
+ * @param fallback - the value used when `value` is not a usable number.
+ * @returns a whole number within 1..{@link NOTIFY_MAX_LIMIT}.
+ */
+export function clampLimit(value: unknown, fallback: number = NOTIFY_DEFAULT_LIMIT): number {
+  const parsed = parseWhole(value)
+  if (parsed === null) return fallback
+  if (parsed < 1) return 1
+  return parsed > NOTIFY_MAX_LIMIT ? NOTIFY_MAX_LIMIT : parsed
+}
+
+/**
+ * Read a whole number out of a query value.
+ *
+ * An absent or blank value is `null` rather than zero: `Number('')` is 0, which
+ * would silently turn "the caller said nothing" into "the caller asked for the
+ * smallest possible answer".
+ *
+ * @param value - the raw value, of unknown quality.
+ * @returns the truncated number, or null when there is no number there.
+ */
+function parseWhole(value: unknown): number | null {
+  if (typeof value === 'number') return Number.isFinite(value) ? Math.trunc(value) : null
+  if (typeof value !== 'string') return value === null || value === undefined ? null : parseWhole(Number(value))
+  const text = value.trim()
+  if (text === '') return null
+  const parsed = Number(text)
+  return Number.isFinite(parsed) ? Math.trunc(parsed) : null
+}
+
+/**
+ * Clamp a client's read watermark. A malformed watermark means "nothing seen
+ * yet" (0) rather than a throw, because a client that cannot parse its stored
+ * value should be told everything again instead of nothing.
+ * @param value - the parsed watermark, of unknown quality.
+ * @returns a non-negative whole number.
+ */
+export function clampWatermark(value: unknown): number {
+  const parsed = parseWhole(value)
+  if (parsed === null || parsed < 0) return 0
+  return parsed
+}
+
+/**
+ * Reconcile a client's stored watermark with the feed it just read.
+ *
+ * Notice ids count from one host process, so a restarted host serves ids that
+ * start over. A watermark stored against the previous process would then be
+ * higher than every new id and would hide each new notice forever, which is the
+ * one failure mode a red dot must not have. A regression therefore means "the
+ * host is a different process now; start over", and the caller stores 0 and
+ * treats the whole held log as new.
+ *
+ * @param previous - the watermark the client stored.
+ * @param latest - the feed's newest id.
+ * @returns the watermark the client should keep and compare against.
+ */
+export function reconcileWatermark(previous: number, latest: number): number {
+  if (!Number.isFinite(latest) || latest < 0) return previous
+  return latest < previous ? 0 : previous
+}
+
+/**
+ * The notices a client has not seen, under the reconciliation rule above.
+ * @param feed - the decoded feed document.
+ * @param watermark - the client's stored watermark.
+ * @returns notices newer than the effective watermark, oldest first.
+ */
+export function newNotices(feed: NotifyFeed, watermark: number): RunNotice[] {
+  const effective = reconcileWatermark(clampWatermark(watermark), feed.latest)
+  return feed.notices.filter(notice => notice.id > effective)
+}
+
+function asString(value: unknown): string {
+  return typeof value === 'string' ? value : ''
+}
+
+function asWhole(value: unknown, fallback = 0): number {
+  const parsed = typeof value === 'number' ? value : Number(value)
+  return Number.isFinite(parsed) ? Math.trunc(parsed) : fallback
+}
+
+/**
+ * Narrow one decoded notice from the wire.
+ *
+ * Every field is re-derived rather than cast, so an unknown or truncated
+ * payload degrades into a notice with blank strings instead of an `undefined`
+ * reaching a renderer.
+ *
+ * @param value - one decoded element of `notices`.
+ * @returns the notice, or null when the element is not an object at all.
+ */
+export function parseRunNotice(value: unknown): RunNotice | null {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return null
+  const record = value as Record<string, unknown>
+  const reason = asString(record.reason)
+  const rawOutcome = asString(record.outcome)
+  const outcome: NotifyOutcome = rawOutcome === 'completed' || rawOutcome === 'failed' || rawOutcome === 'stopped'
+    ? rawOutcome
+    : outcomeOf(reason)
+  return {
+    id: asWhole(record.id),
+    at: asWhole(record.at),
+    sessionId: asString(record.sessionId),
+    title: asString(record.title),
+    turn: asWhole(record.turn),
+    reason,
+    outcome,
+  }
+}
+
+/**
+ * Narrow a whole feed document from the wire.
+ * @param value - the decoded JSON body.
+ * @returns the feed, or null when the body is not a feed object.
+ */
+export function parseFeed(value: unknown): NotifyFeed | null {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return null
+  const record = value as Record<string, unknown>
+  const notices = Array.isArray(record.notices)
+    ? record.notices.map(parseRunNotice).filter((notice): notice is RunNotice => notice !== null)
+    : []
+  const latest = asWhole(record.latest, notices.reduce((max, notice) => Math.max(max, notice.id), 0))
+  return { origin: asString(record.origin), latest, notices }
+}

package/src/core/notify/feed.ts

@@ -0,0 +1,235 @@
+/**
+ * The two bounded pieces of state the notification host keeps: the recent
+ * notice log a client polls, and the session titles a notice quotes.
+ *
+ * Both are deliberately in memory only. A notice answers "did my work finish"
+ * for a window of a few minutes; persisting it would create a second durable
+ * record of the session log that DSH already owns, and would have to answer
+ * questions about retention, migration and conflicting truth. A restart
+ * therefore forgets the feed, and a client's watermark simply replays from a
+ * fresh, empty log.
+ *
+ * @module dsh-web-all/notify-feed
+ */
+
+import {
+  NOTIFY_DEFAULT_LIMIT,
+  NOTIFY_TITLE_MEMORY,
+  outcomeOf,
+  type RunNotice,
+  type RunNoticeInput,
+} from './contract.ts'
+
+/**
+ * A bounded log of finished turns, oldest first.
+ *
+ * Ids are assigned from a counter that never resets while the host lives, so a
+ * client watermark stays meaningful even after older entries have been evicted:
+ * "newer than 40" keeps working when the log has already dropped everything
+ * below 35.
+ */
+export class NoticeLog {
+  private readonly limit: number
+  private seq = 0
+  private entries: RunNotice[] = []
+
+  /**
+   * @param limit - how many notices to retain; clamped to at least one so a
+   *   misconfigured host still answers with something.
+   */
+  constructor(limit: number = NOTIFY_DEFAULT_LIMIT) {
+    this.limit = Number.isFinite(limit) && limit >= 1 ? Math.trunc(limit) : NOTIFY_DEFAULT_LIMIT
+  }
+
+  /** Newest assigned id, or 0 when nothing has been recorded. */
+  get latest(): number {
+    return this.seq
+  }
+
+  /** How many notices are currently retained. */
+  get size(): number {
+    return this.entries.length
+  }
+
+  /**
+   * Record one finished turn.
+   * @param input - the turn facts; an absent outcome is derived from the reason.
+   * @returns the stored notice, including its assigned id.
+   */
+  append(input: RunNoticeInput): RunNotice {
+    this.seq += 1
+    const notice: RunNotice = {
+      id: this.seq,
+      at: input.at,
+      sessionId: input.sessionId,
+      title: input.title,
+      turn: input.turn,
+      reason: input.reason,
+      outcome: input.outcome ?? outcomeOf(input.reason),
+    }
+    this.entries.push(notice)
+    if (this.entries.length > this.limit) this.entries.splice(0, this.entries.length - this.limit)
+    return notice
+  }
+
+  /**
+   * Notices newer than a client's watermark, oldest first.
+   * @param watermark - the client's last seen id; 0 (or anything unparsable) replays what is held.
+   * @param limit - maximum notices to return; at least one.
+   * @returns a fresh array of notices.
+   */
+  since(watermark: number, limit: number): RunNotice[] {
+    const floor = Number.isFinite(watermark) && watermark > 0 ? Math.trunc(watermark) : 0
+    const cap = Number.isFinite(limit) && limit >= 1 ? Math.trunc(limit) : 1
+    const out: RunNotice[] = []
+    for (const notice of this.entries) {
+      if (notice.id <= floor) continue
+      out.push(notice)
+      if (out.length >= cap) break
+    }
+    return out
+  }
+
+  /** Everything currently retained, oldest first. */
+  snapshot(): readonly RunNotice[] {
+    return [...this.entries]
+  }
+
+  /** Drop every retained notice. Ids keep counting, so a stale watermark still orders correctly. */
+  clear(): void {
+    this.entries = []
+  }
+}
+
+/** One session's remembered naming material. */
+interface TitleEntry {
+  /** An explicit or generated title, which always outranks a prompt excerpt. */
+  title: string
+  /** The first human prompt's excerpt, used until a real title exists. */
+  prompt: string
+}
+
+/**
+ * Remembers how each session is named, so a notice can say which conversation
+ * finished instead of quoting an opaque `session-7`.
+ *
+ * A session's own title event is preferred, because `dsh-session-title` already
+ * decided which messages are eligible input and normalized the result. Until
+ * one exists, the first human prompt stands in. Both maps are bounded by last
+ * write, so a host that runs for weeks does not accumulate one entry per
+ * conversation it has ever seen.
+ */
+export class TitleBook {
+  private readonly capacity: number
+  private readonly entries = new Map<string, TitleEntry>()
+
+  /**
+   * @param capacity - sessions to remember; clamped to at least one.
+   */
+  constructor(capacity: number = NOTIFY_TITLE_MEMORY) {
+    this.capacity = Number.isFinite(capacity) && capacity >= 1 ? Math.trunc(capacity) : NOTIFY_TITLE_MEMORY
+  }
+
+  /** How many sessions are remembered. */
+  get size(): number {
+    return this.entries.size
+  }
+
+  private entry(sessionId: string): TitleEntry {
+    const existing = this.entries.get(sessionId)
+    if (existing !== undefined) {
+      // Re-insert so the most recently written session is the last evicted.
+      this.entries.delete(sessionId)
+      this.entries.set(sessionId, existing)
+      return existing
+    }
+    const created: TitleEntry = { title: '', prompt: '' }
+    this.entries.set(sessionId, created)
+    while (this.entries.size > this.capacity) {
+      const oldest = this.entries.keys().next()
+      if (oldest.done === true) break
+      this.entries.delete(oldest.value)
+    }
+    return created
+  }
+
+  /**
+   * Record a session title, which outranks any prompt excerpt.
+   * @param sessionId - the titled session.
+   * @param title - the title text; blank is ignored so a nameless update cannot erase a name.
+   */
+  setTitle(sessionId: string, title: string): void {
+    const text = title.trim()
+    if (sessionId === '' || text === '') return
+    this.entry(sessionId).title = excerpt(text, 60)
+  }
+
+  /**
+   * Record a candidate prompt excerpt. The first one wins, because a session is
+   * recognized by what it was opened to do, not by its most recent follow-up.
+   * @param sessionId - the session the prompt belongs to.
+   * @param text - the human prompt text.
+   */
+  rememberPrompt(sessionId: string, text: string): void {
+    const text2 = text.trim()
+    if (sessionId === '' || text2 === '') return
+    const entry = this.entry(sessionId)
+    if (entry.prompt === '') entry.prompt = excerpt(text2, 60)
+  }
+
+  /**
+   * How to name one session in a notice.
+   * @param sessionId - the session to name.
+   * @returns the title, else the prompt excerpt, else '' when nothing is known.
+   */
+  titleOf(sessionId: string): string {
+    const entry = this.entries.get(sessionId)
+    if (entry === undefined) return ''
+    return entry.title !== '' ? entry.title : entry.prompt
+  }
+
+  /** Forget one disposed session. */
+  forget(sessionId: string): void {
+    this.entries.delete(sessionId)
+  }
+
+  /** Forget every session. */
+  clear(): void {
+    this.entries.clear()
+  }
+}
+
+/**
+ * One-line excerpt safe to put in a notification.
+ * @param text - any text, possibly multi-line.
+ * @param max - maximum code points to keep.
+ * @returns whitespace-collapsed text, truncated with an ellipsis when it was longer.
+ */
+export function excerpt(text: string, max: number): string {
+  const collapsed = text.replace(/\s+/g, ' ').trim()
+  const points = [...collapsed]
+  if (points.length <= max) return collapsed
+  return `${points.slice(0, Math.max(1, max - 1)).join('')}…`
+}
+
+/**
+ * Pull the plain text out of one message's content blocks.
+ *
+ * Only text blocks carry quotable prose; every other block kind (an image, a
+ * file reference) is skipped rather than stringified, because a title made of a
+ * serialized block would be worse than no title.
+ *
+ * @param content - the message's `content` field, of unknown quality.
+ * @returns the concatenated text, space separated.
+ */
+export function textOfContent(content: unknown): string {
+  if (!Array.isArray(content)) return ''
+  const parts: string[] = []
+  for (const block of content) {
+    if (typeof block !== 'object' || block === null) continue
+    const record = block as Record<string, unknown>
+    if (record.type !== 'text') continue
+    if (typeof record.text === 'string' && record.text.trim() !== '') parts.push(record.text)
+  }
+  return parts.join(' ')
+}