@modesto_ma/dsh-channels 0.0.0-stage → 0.1.0

package/src/config.ts

@@ -0,0 +1,206 @@
+/**
+ * Plugin configuration: schema, defaults, and credential-reference validation.
+ *
+ * `appId` / `appSecret` are NOT secrets themselves — they are credential
+ * *references* (POSIX shell identifiers such as `FEISHU_APP_ID`), resolved at
+ * startup through the host's `ctx.credentials` seam, which layers
+ * `$DSH_HOME/.credentials.yaml` (the managed, writable store) between the
+ * process environment and `.env` fallbacks — the same seam the DeepSeek
+ * adapter uses for `DEEPSEEK_API_KEY`. Secrets therefore never sit in the
+ * composition file.
+ *
+ * @module dsh-channels/config
+ */
+
+import { z } from 'zod'
+import { WORKSPACE_RETENTION_VALUES } from './cleanup.ts'
+
+export const FEISHU_LOGGER_LEVELS = ['debug', 'info', 'warn', 'error'] as const
+export type FeishuLoggerLevel = (typeof FEISHU_LOGGER_LEVELS)[number]
+
+/** Same shape as the host credentials seam's `CredentialRef` (shell identifier). */
+export const CREDENTIAL_REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/** Default route-table GC threshold: 30 days without activity. */
+export const DEFAULT_ROUTE_TTL_MS = 30 * 24 * 60 * 60 * 1000
+
+/** Default HITL approval decision window: 5 minutes per question. */
+export const DEFAULT_APPROVAL_TIMEOUT_MS = 5 * 60 * 1000
+
+/** Default structured-question window: 5 minutes per `ask_user_question` call. */
+export const DEFAULT_QUESTION_TIMEOUT_MS = 5 * 60 * 1000
+
+/** A credential reference: `FEISHU_APP_ID`-style name resolved through ctx.credentials. */
+const credentialRefSchema = z.string().regex(
+  CREDENTIAL_REF_PATTERN,
+  'must be a credential reference name such as FEISHU_APP_ID (resolved through the dsh credentials seam, e.g. $DSH_HOME/.credentials.yaml) — plaintext secrets are not accepted',
+)
+
+export const configSchema = z.object({
+  /** Feishu app id credential reference (e.g. `FEISHU_APP_ID`). */
+  appId: credentialRefSchema,
+  /** Feishu app secret credential reference (e.g. `FEISHU_APP_SECRET`). */
+  appSecret: credentialRefSchema,
+  /**
+   * Root directory for per-(user, chat) workspace directories — the filesystem
+   * root where files produced by channel sessions land. Read per session
+   * establishment, so editing it only affects sessions created afterwards
+   * (existing workspaces are never migrated). The Web settings panel may
+   * override it, but only with an absolute path (`~` expanded) — the relative
+   * default below is kept for profile-level compatibility and resolves
+   * against the host process cwd.
+   */
+  baseDir: z.string().min(1).default('./channels-data'),
+  /**
+   * Optional path of the Web settings overlay (default
+   * `$DSH_HOME/dsh-channels/settings.json`). The Web panel writes only
+   * editable fields there; this path is for embedded hosts, tests, or users
+   * who want multiple instances with different overlays.
+   */
+  settingsFile: z.string().min(1).optional(),
+  /** LLM provider route for sessions this plugin creates (optional → deployment default). */
+  provider: z.string().optional(),
+  /** Model id for sessions this plugin creates (optional → deployment default). */
+  model: z.string().optional(),
+  /** Exact model-advertised reasoning-effort id (optional → adapter/provider default). */
+  reasoningEffort: z.string().min(1).optional(),
+  /** Output-token cap per model request (optional → adapter default). */
+  maxTokens: z.number().int().positive().optional(),
+  /**
+   * Agent preset id sessions this plugin creates are composed from
+   * (optional → the roster default, e.g. `standard`). In web-profile
+   * deployments the model-facing tools exist only inside agent presets, so
+   * leaving this unset mounts the default; name a leaner preset (e.g. one
+   * with only bash/fs) to restrict what the bot can do.
+   */
+  agentPreset: z.string().optional(),
+  /** Streaming card refresh interval in milliseconds. */
+  refreshMs: z.number().int().min(200).max(10_000).default(500),
+  /**
+   * Keep-alive interval for the card's activity status line (tool calls,
+   * subagent / workflow progress). While a turn produces no text deltas, the
+   * line's elapsed counter is re-rendered at this cadence so the card never
+   * sits silently. Min 1 s keeps Feishu card-update traffic modest.
+   */
+  statusRefreshMs: z.number().int().min(1_000).max(60_000).default(5_000),
+  /** Accept p2p (private) chats. */
+  dmMode: z.enum(['open', 'disabled']).default('open'),
+  /**
+   * In normal (non-topic) groups, require an @-mention of the bot to start a
+   * session. Messages inside a topic the bot already owns never require a
+   * mention. Disable to answer every group message.
+   */
+  requireMention: z.boolean().default(true),
+  /** SDK logger level. */
+  loggerLevel: z.enum(FEISHU_LOGGER_LEVELS).default('info'),
+  /**
+   * Reply-in-thread fallbacks. `degrade` (default) falls back to a chat-scoped
+   * conversation when Feishu refuses a topic (p2p / topic-less groups);
+   * `strict` fails the reply instead.
+   */
+  threadFallback: z.enum(['degrade', 'strict']).default('degrade'),
+  /**
+   * Route-table GC threshold. Route records (and stale in-flight repair
+   * snapshots) whose last activity is older than this many milliseconds are
+   * retired at startup and on every periodic sweep. Real thread routes leave a
+   * minimal persistent tombstone, so a later message in the visibly old topic
+   * is rejected instead of silently creating a context-free Session. Degraded
+   * chat-scoped routes are deleted normally. The DSH session and workspace
+   * stay untouched. `0` disables route retirement entirely.
+   */
+  routeTtlMs: z.number().int().min(0).default(DEFAULT_ROUTE_TTL_MS),
+  /**
+   * HITL approval decision window: how long one approval decision card waits
+   * for an 允许/拒绝 click before failing closed (`rejected`; the card is
+   * patched to 已超时). The pending turn is blocked while the question is
+   * open, so the window trades user think-time against agent stall time.
+   */
+  approvalTimeoutMs: z.number().int().min(10_000).max(3_600_000).default(DEFAULT_APPROVAL_TIMEOUT_MS),
+  /**
+   * Accept inbound Feishu images, files, and merged-forward chat records and
+   * save them below `<workspace>/attachments/`. Nothing is forwarded to the
+   * model automatically: the Agent reads whichever attachment the
+   * conversation needs with its ordinary filesystem tools. Disabled keeps
+   * attachment messages inert (no save, no turn).
+   */
+  acceptAttachments: z.boolean().default(true),
+  /**
+   * Delete the workspace directories of stale conversations. `off` (default)
+   * never deletes; `7d`/`30d`/`90d`/`180d` remove plugin-created workspaces
+   * whose last activity is older than the threshold. The managed Web panel
+   * exposes this as a select, previews the candidates, and can run one
+   * cleanup manually. DSH Session logs are never deleted.
+   */
+  workspaceRetention: z.enum(WORKSPACE_RETENTION_VALUES).default('off'),
+  /**
+   * Run the workspace-retention cleanup at startup and once per day. Off by
+   * default: deletion is irreversible, so it stays an explicit opt-in even
+   * when a retention threshold is configured.
+   */
+  workspaceRetentionAuto: z.boolean().default(false),
+  /**
+   * Send a one-time onboarding card on the first private message of a chat
+   * (facts + command cheat sheet). Persisted per chat; never repeats.
+   */
+  welcomeOnboarding: z.boolean().default(true),
+  /**
+   * Allow `/permissions <name>` to switch this Session's sandbox + approval
+   * preset from Feishu. Read-only `/permissions` always works; switching is
+   * security-sensitive (it can widen the sandbox), so it is off by default.
+   */
+  allowPermissionSwitch: z.boolean().default(false),
+  /**
+   * Admission policy for inbound Feishu traffic.
+   *
+   * - `guarded` (default): only the configured administrator can talk in
+   *   private chats, and a group conversation additionally requires the group
+   *   to be authorized and the sender to be the administrator or an explicitly
+   *   authorized user.
+   * - `open`: legacy behavior — any user inside the app's availability scope
+   *   can start a conversation. Debug/compatibility only; unsafe.
+   */
+  accessMode: z.enum(['open', 'guarded']).default('guarded'),
+  /**
+   * The unique administrator's Feishu open_id (`ou_...`). Set it in the Web
+   * settings panel (or the profile config). Get it by sending `/userid` to the
+   * bot in a private chat. While `accessMode` is `guarded` and this is unset,
+   * every conversation is refused (fail closed); `/userid` and a fixed notice
+   * stay available so the deployment can be bootstrapped.
+   */
+  adminOpenId: z.string().regex(
+    /^ou_[A-Za-z0-9_-]+$/,
+    'must be a Feishu open_id such as ou_xxx (send /userid to the bot in a private chat to see it)',
+  ).optional(),
+  /**
+   * Lifetime of one pending authorization request and of the DM card that asks
+   * the administrator to approve a group or a user. Expired requests stay in
+   * the store as an audit trail but can no longer be decided.
+   */
+  authRequestTtlDays: z.number().int().min(1).max(30).default(7),
+  /**
+   * Structured-question decision window for the model's `ask_user_question`
+   * tool (`user-questions/request`). A blocking ask that gets no answer in
+   * this window fails closed with an explicit error; a host *timed* wait owns
+   * its own deadline and is left to the host signal instead.
+   */
+  questionTimeoutMs: z.number().int().min(10_000).max(3_600_000).default(DEFAULT_QUESTION_TIMEOUT_MS),
+})
+
+export type FeishuConfig = z.infer<typeof configSchema>
+
+/**
+ * Validate the raw loader config. Values stay credential *references*; the
+ * secrets themselves resolve through `ctx.credentials` at startup.
+ * @param raw - the config object the cordis loader passed (may be undefined).
+ * @returns the validated config.
+ */
+export function resolveConfig(raw: unknown): FeishuConfig {
+  const parsed = configSchema.safeParse(raw ?? {})
+  if (!parsed.success) {
+    const details = parsed.error.issues
+      .map(issue => `  - ${issue.path.join('.') || '(root)'}: ${issue.message}`)
+      .join('\n')
+    throw new Error(`dsh-channels: invalid configuration:\n${details}`)
+  }
+  return parsed.data
+}

package/src/domain.ts

@@ -0,0 +1,428 @@
+/**
+ * Durable routing domain: thread/chat keys → bound DSH session records.
+ *
+ * Opened through the host's `ctx.storageDomain` facility; the spec is plain
+ * data (no runtime import of DSH packages), so the plugin carries zero
+ * runtime dependency on host internals — everything flows through `ctx`.
+ *
+ * @module dsh-channels/domain
+ */
+
+import { z } from 'zod'
+
+/** Route key kinds. `thread` = real Feishu topic; `chat` = degraded chat-scoped fallback. */
+export const ROUTE_RECORD_VERSION = 1
+
+export const sessionHistoryEntrySchema = z.object({
+  /** One Session that has been bound to this route. */
+  sessionId: z.string().min(1),
+  /** Epoch ms when the Session was created. */
+  createdAt: z.number().int().nonnegative(),
+})
+
+export type SessionHistoryEntry = z.infer<typeof sessionHistoryEntrySchema>
+
+export const routeRecordSchema = z.object({
+  /** Route key the record is stored under (thread_id or chat:<chatId>). */
+  key: z.string().min(1),
+  /** Kind of the key. */
+  kind: z.enum(['thread', 'chat']),
+  /** Bound DSH session id. */
+  sessionId: z.string().min(1),
+  /** Feishu chat the session lives in. */
+  chatId: z.string().min(1),
+  /** `p2p` or `group`. */
+  chatType: z.enum(['p2p', 'group']),
+  /** Workspace owner (sender open_id). */
+  senderOpenId: z.string().min(1),
+  /** Workspace directory for this (chat, user) pair. */
+  workspacePath: z.string().min(1),
+  /** Message id of the latest streaming card (updated per turn). */
+  cardMessageId: z.string().min(1),
+  /** Epoch ms when the record was created. */
+  createdAt: z.number().int().nonnegative(),
+  /** Epoch ms of the last activity routed through this record. */
+  lastActivityAt: z.number().int().nonnegative(),
+  /** Sessions this topic has pointed at, oldest first. Optional for v1 compatibility. */
+  sessionHistory: z.array(sessionHistoryEntrySchema).optional(),
+})
+
+export type RouteRecord = z.infer<typeof routeRecordSchema>
+
+/**
+ * Minimal persistent tombstone for a thread route retired by route TTL.
+ *
+ * Deleting the active route alone would make a later message look like a new
+ * conversation and silently create another Session in the same Feishu topic.
+ * The tombstone preserves only enough identity to reject that message across
+ * process restarts; the old Session and workspace remain host-owned.
+ */
+export const expiredRouteRecordSchema = z.object({
+  /** Expired Feishu thread id (also the table key). */
+  key: z.string().min(1),
+  /** Feishu chat containing the expired topic. */
+  chatId: z.string().min(1),
+  /** Original chat type, retained for diagnostics and future policy. */
+  chatType: z.enum(['p2p', 'group']),
+  /** Original route owner; never used to grant access after expiry. */
+  senderOpenId: z.string().min(1),
+  /** Epoch ms when the route was retired. */
+  expiredAt: z.number().int().nonnegative(),
+  /** Workspace the retired route belonged to; absent in tombstones written by
+   *  older plugin versions, so the field must stay optional. */
+  workspacePath: z.string().min(1).optional(),
+  /** Epoch ms of the last activity through the route before retirement.
+   *  Optional for the same legacy-compatibility reason; consumers fall back to
+   *  `expiredAt` when it is absent. */
+  lastActivityAt: z.number().int().nonnegative().optional(),
+})
+
+export type ExpiredRouteRecord = z.infer<typeof expiredRouteRecordSchema>
+
+/**
+ * Normalize legacy and partially duplicated histories without mutating the
+ * durable record. The current Session is always represented, duplicate ids
+ * collapse to their earliest timestamp, and output order is deterministic.
+ */
+export function normalizeSessionHistory(record: RouteRecord): SessionHistoryEntry[] {
+  const bySession = new Map<string, SessionHistoryEntry>()
+  for (const entry of record.sessionHistory ?? []) {
+    const existing = bySession.get(entry.sessionId)
+    if (existing === undefined || entry.createdAt < existing.createdAt) {
+      bySession.set(entry.sessionId, { ...entry })
+    }
+  }
+  if (!bySession.has(record.sessionId)) {
+    bySession.set(record.sessionId, { sessionId: record.sessionId, createdAt: record.createdAt })
+  }
+  return [...bySession.values()].sort((left, right) => left.createdAt - right.createdAt)
+}
+
+/** Materialize the optional legacy history field for in-memory consumers. */
+export function normalizeRouteRecord(record: RouteRecord): RouteRecord {
+  return { ...record, sessionHistory: normalizeSessionHistory(record) }
+}
+
+/** Append a newly created Session to one normalized route history. */
+export function appendSessionHistory(
+  record: RouteRecord,
+  sessionId: string,
+  createdAt: number,
+): SessionHistoryEntry[] {
+  return normalizeSessionHistory({
+    ...record,
+    sessionId,
+    sessionHistory: [...normalizeSessionHistory(record), { sessionId, createdAt }],
+  })
+}
+
+/**
+ * In-flight turn snapshot: everything needed to repair a streaming card that a
+ * restart left mid-flight (stuck panel, leftover Typing reaction, never-patched
+ * segment cards). Keyed by the turn's MAIN card message id — unique per turn
+ * and known at attach time — so overlapping turns of one session never
+ * overwrite each other. Written before the route record, updated as segment
+ * cards resolve, deleted when the turn finalizes (or the creation fails).
+ */
+export const INFLIGHT_VERSION = 1
+
+export const inflightCardSchema = z.object({
+  /** Feishu message id of one segment card. */
+  messageId: z.string().min(1),
+  /** Delivery mode; `text` messages are complete and never patched by repair. */
+  mode: z.enum(['card', 'text']),
+})
+
+export type InflightCard = z.infer<typeof inflightCardSchema>
+
+export const inflightSnapshotSchema = z.object({
+  /** Key the snapshot is stored under (= `cards[0].messageId`, the main card). */
+  key: z.string().min(1),
+  /** DSH session the turn belongs to. */
+  sessionId: z.string().min(1),
+  /** Feishu chat the cards live in (reaction targeting). */
+  chatId: z.string().min(1),
+  /** User message that triggered the turn (Typing/DONE reaction anchor). */
+  triggerMessageId: z.string().min(1),
+  /** Reaction id of the Typing reaction (absent when the add failed). */
+  reactionId: z.string().optional(),
+  /** Segment cards in order; `[0]` is the main card. */
+  cards: z.array(inflightCardSchema).min(1),
+  /** Epoch ms when the turn attached. */
+  startedAt: z.number().int().nonnegative(),
+  /** Repair attempts spent (cap: 2 — see `repairInflight`). */
+  attempts: z.number().int().nonnegative(),
+})
+
+export type InflightSnapshot = z.infer<typeof inflightSnapshotSchema>
+
+/**
+ * Access-control grants (v1 format, added without a domain version bump —
+ * see the notes on `feishuDomain` below).
+ *
+ * One record per authorized group: the group gate is the first of the two
+ * independent admission gates. Inside an authorized group only the
+ * administrator and explicitly authorized users may start conversations.
+ */
+export const accessGroupRecordSchema = z.object({
+  /** Feishu chat id (`oc_...`) — also the table key. */
+  chatId: z.string().min(1),
+  /** Human-readable group name captured at authorization time (optional). */
+  name: z.string().optional(),
+  /** Which authorization entry produced this grant. */
+  source: z.enum(['command', 'card', 'panel']),
+  /** Administrator open_id that authorized it. */
+  addedBy: z.string().min(1),
+  /** Epoch ms when it was authorized. */
+  addedAt: z.number().int().nonnegative(),
+})
+
+export type AccessGroupRecord = z.infer<typeof accessGroupRecordSchema>
+
+/**
+ * One authorized user (`open_id`), global across every authorized group.
+ * Private chats are administrator-only, so this grant only affects group
+ * conversations.
+ */
+export const accessUserRecordSchema = z.object({
+  /** Feishu open id (`ou_...`) — also the table key. */
+  openId: z.string().min(1),
+  /** Display name captured when the user was authorized (optional). */
+  name: z.string().optional(),
+  /** Which authorization entry produced this grant. */
+  source: z.enum(['command', 'card', 'panel']),
+  /** Administrator open_id that authorized it. */
+  addedBy: z.string().min(1),
+  /** Epoch ms when it was authorized. */
+  addedAt: z.number().int().nonnegative(),
+})
+
+export type AccessUserRecord = z.infer<typeof accessUserRecordSchema>
+
+/**
+ * One authorization request the administrator has been (or should be) asked
+ * about. Requests are persisted so the DM card stays decidable across plugin
+ * restarts; settled records are kept as an audit trail and for request
+ * de-duplication/cooldown.
+ */
+export const accessRequestRecordSchema = z.object({
+  /** Opaque token carried by the card buttons — also the table key. */
+  token: z.string().min(1),
+  /** What is being requested. */
+  kind: z.enum(['group', 'user']),
+  /** `chat_id` for a group request; `open_id` for a user request. */
+  targetId: z.string().min(1),
+  /** Chat the request originated from, when applicable. */
+  chatId: z.string().optional(),
+  /** Group name captured for the card (group requests, or the group the user was seen in). */
+  groupName: z.string().optional(),
+  /** User who triggered a user request. */
+  requesterOpenId: z.string().optional(),
+  /** Display name of that user, when the event carried one. */
+  requesterName: z.string().optional(),
+  /** Lifecycle state; only `pending` requests accept a card action. */
+  status: z.enum(['pending', 'approved', 'denied', 'expired']),
+  /** Epoch ms when the request was created. */
+  createdAt: z.number().int().nonnegative(),
+  /** Epoch ms after which a pending request can no longer be decided. */
+  expiresAt: z.number().int().nonnegative(),
+  /** DM message id of the administrator card, once delivery succeeded. */
+  messageId: z.string().optional(),
+})
+
+export type AccessRequestRecord = z.infer<typeof accessRequestRecordSchema>
+
+/**
+ * One processed inbound message, keyed by its Feishu message id. Feishu
+ * redelivers un-acked events on WS reconnect, so every accepted message is
+ * recorded here BEFORE its side effects begin; redeliveries then hit the
+ * table (or the in-process guard) and are dropped. Records are pruned by the
+ * GC sweep after a fixed retention window (24 h — redelivery windows are
+ * minutes).
+ */
+export const PROCESSED_VERSION = 1
+
+export const processedRecordSchema = z.object({
+  /** Key the record is stored under (the Feishu message id). */
+  key: z.string().min(1),
+  /** Epoch ms when the message was accepted for processing. */
+  processedAt: z.number().int().nonnegative(),
+})
+
+export type ProcessedRecord = z.infer<typeof processedRecordSchema>
+
+export interface FeishuDomainSpecShape {
+  name: 'channels_routes'
+  version: 1
+  global: {
+    schema: z.ZodType<FeishuDomainGlobal>
+    initial: FeishuDomainGlobal
+  }
+  tables: {
+    routes: {
+      valueSchema: typeof routeRecordSchema
+      __key?: string
+    }
+    inflight: {
+      valueSchema: typeof inflightSnapshotSchema
+      __key?: string
+    }
+    processed: {
+      valueSchema: typeof processedRecordSchema
+      __key?: string
+    }
+    expired_routes: {
+      valueSchema: typeof expiredRouteRecordSchema
+      __key?: string
+    }
+    access_groups: {
+      valueSchema: typeof accessGroupRecordSchema
+      __key?: string
+    }
+    access_users: {
+      valueSchema: typeof accessUserRecordSchema
+      __key?: string
+    }
+    access_requests: {
+      valueSchema: typeof accessRequestRecordSchema
+      __key?: string
+    }
+  }
+}
+
+export const feishuDomainGlobalSchema = z.object({
+  /** Legacy: img_key of a previously uploaded chevron icon. Kept optional so
+   *  storage written by older plugin versions still validates; the card now
+   *  uses the built-in `standard_icon` chevron and never writes this. */
+  chevronImgKey: z.string().optional(),
+  /** p2p chats already shown the one-time onboarding card (bounded list). */
+  welcomedChats: z.array(z.string()).optional(),
+})
+
+export type FeishuDomainGlobal = z.infer<typeof feishuDomainGlobalSchema>
+
+/**
+ * Domain declaration for the host's storage facility. Plain data plus zod
+ * schemas — deliberately not built with `defineDomain` so this module has no
+ * runtime import of `@deepseek-ai/dsh-storage-domain`.
+ */
+export const feishuDomain: FeishuDomainSpecShape = {
+  name: 'channels_routes',
+  version: 1,
+  global: {
+    schema: feishuDomainGlobalSchema,
+    initial: {} satisfies FeishuDomainGlobal,
+  },
+  tables: {
+    routes: { valueSchema: routeRecordSchema },
+    inflight: { valueSchema: inflightSnapshotSchema },
+    processed: { valueSchema: processedRecordSchema },
+    expired_routes: { valueSchema: expiredRouteRecordSchema },
+    access_groups: { valueSchema: accessGroupRecordSchema },
+    access_users: { valueSchema: accessUserRecordSchema },
+    access_requests: { valueSchema: accessRequestRecordSchema },
+  },
+}
+
+export type FeishuDomainSpec = typeof feishuDomain
+
+/** Normalized table handle for the routes table. */
+export interface RoutesTable {
+  get(key: string): RouteRecord | undefined
+  put(key: string, value: RouteRecord): Promise<unknown> | void
+  delete(key: string): Promise<unknown> | void
+  entries(): IterableIterator<[string, RouteRecord]>
+}
+
+/** Normalized table handle for the inflight table (repair snapshots). */
+export interface InflightTable {
+  get(key: string): InflightSnapshot | undefined
+  put(key: string, value: InflightSnapshot): Promise<unknown> | void
+  /**
+   * Atomic read-modify-write on the host's write chain (mirrors `KvTable`).
+   * Rejects with `missing-key` when the key is absent (e.g. the turn finalize
+   * deleted the snapshot while a late segment delivery was still landing).
+   */
+  update(key: string, fn: (current: InflightSnapshot) => InflightSnapshot): Promise<unknown>
+  delete(key: string): Promise<unknown> | void
+  entries(): IterableIterator<[string, InflightSnapshot]>
+}
+
+/** Normalized table handle for the processed-message dedup table. */
+export interface ProcessedTable {
+  get(key: string): ProcessedRecord | undefined
+  put(key: string, value: ProcessedRecord): Promise<unknown> | void
+  delete(key: string): Promise<unknown> | void
+  entries(): IterableIterator<[string, ProcessedRecord]>
+}
+
+/** Persistent thread tombstones used to reject post-TTL messages. */
+export interface ExpiredRoutesTable {
+  get(key: string): ExpiredRouteRecord | undefined
+  put(key: string, value: ExpiredRouteRecord): Promise<unknown> | void
+  entries(): IterableIterator<[string, ExpiredRouteRecord]>
+}
+
+/** Normalized table handle for authorized groups (key = `chat_id`). */
+export interface AccessGroupsTable {
+  get(key: string): AccessGroupRecord | undefined
+  put(key: string, value: AccessGroupRecord): Promise<unknown> | void
+  delete(key: string): Promise<unknown> | void
+  entries(): IterableIterator<[string, AccessGroupRecord]>
+}
+
+/** Normalized table handle for authorized users (key = `open_id`). */
+export interface AccessUsersTable {
+  get(key: string): AccessUserRecord | undefined
+  put(key: string, value: AccessUserRecord): Promise<unknown> | void
+  delete(key: string): Promise<unknown> | void
+  entries(): IterableIterator<[string, AccessUserRecord]>
+}
+
+/** Normalized table handle for authorization requests (key = opaque token). */
+export interface AccessRequestsTable {
+  get(key: string): AccessRequestRecord | undefined
+  put(key: string, value: AccessRequestRecord): Promise<unknown> | void
+  delete(key: string): Promise<unknown> | void
+  entries(): IterableIterator<[string, AccessRequestRecord]>
+}
+
+/** Normalized domain handle. */
+export interface FeishuDomainHandle {
+  routes: RoutesTable
+  inflight: InflightTable
+  processed: ProcessedTable
+  expiredRoutes: ExpiredRoutesTable
+  accessGroups: AccessGroupsTable
+  accessUsers: AccessUsersTable
+  accessRequests: AccessRequestsTable
+  getGlobal(): FeishuDomainGlobal
+  setGlobal(value: FeishuDomainGlobal): Promise<unknown> | void
+  close(): Promise<void>
+}
+
+/** The raw shape `ctx.storageDomain.open()` resolves to (cast at the seam).
+ *  Mirrors `KvTable` from `@deepseek-ai/dsh-storage-domain`: reads are sync,
+ *  writes go through `put`/`delete` (NOT `set`), and `update` provides the
+ *  atomic read-modify-write used by the inflight merge. */
+export interface RawDomainHandle {
+  table(name: string): {
+    get(key: string): unknown
+    put(key: string, value: unknown): Promise<unknown>
+    update(key: string, fn: (current: unknown) => unknown): Promise<unknown>
+    delete(key: string): Promise<unknown>
+    entries(): IterableIterator<[string, unknown]>
+  }
+  global: {
+    get(): unknown
+    set(value: unknown): Promise<unknown>
+  }
+  close(): Promise<void>
+}
+
+/** Build a chat-scoped fallback key for degraded (topic-less) routing. */
+export function chatRouteKey(chatType: 'p2p' | 'group', chatId: string, senderOpenId: string): string {
+  return chatType === 'p2p'
+    ? `chat:p2p:${chatId}:${senderOpenId}`
+    : `chat:group:${chatId}:${senderOpenId}`
+}

package/src/dsh-types.ts

@@ -0,0 +1,11 @@
+/**
+ * Public type barrel for the DeepSeek Harness host surface.
+ *
+ * The bridge used to live in this one file; it is now split by domain under
+ * `src/host/` (core / agent / commands / interaction / services) and this
+ * module keeps the stable import specifier for consumers and tests.
+ *
+ * @module dsh-channels/dsh-types
+ */
+
+export * from './host/index.ts'