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

package/src/host/services/lark-inbox/tools.ts

@@ -0,0 +1,124 @@
+/** Agent tools for consuming the local inbox queue. */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool, type GenericCallView, type ToolDefinition } from '@deepseek-ai/dsh-tools'
+import type { InboxItem, InboxStore } from './inbox-store.ts'
+import { registerResources } from '../resources.ts'
+
+const NOT_RUNNING = 'dsh-lark-inbox 未运行：请在设置里配置 appId/appSecret 并启用插件'
+const ACK_STATUSES = ['done', 'pending', 'dead', 'not-found'] as const
+
+function clampLimit(limit: number | undefined): number {
+  const value = limit ?? 10
+  return Number.isFinite(value) ? Math.min(50, Math.max(1, Math.trunc(value))) : 10
+}
+
+function preview(item: InboxItem) {
+  const envelope = item.envelope
+  return {
+    eventId: envelope.eventId,
+    receivedAt: envelope.receivedAt,
+    chatType: envelope.chatType ?? '',
+    senderOpenId: envelope.senderOpenId ?? '',
+    messageType: envelope.messageType ?? '',
+    contentPreview: envelope.content.slice(0, 300),
+  }
+}
+
+function popped(item: InboxItem) {
+  const envelope = item.envelope
+  return {
+    eventId: envelope.eventId,
+    receivedAt: envelope.receivedAt,
+    chatType: envelope.chatType ?? '',
+    senderOpenId: envelope.senderOpenId ?? '',
+    messageType: envelope.messageType ?? '',
+    content: envelope.content,
+    messageId: envelope.messageId ?? '',
+  }
+}
+
+export function createInboxTools(getStore: () => InboxStore | undefined): ToolDefinition[] {
+  return [
+    defineTool({
+      name: 'lark_inbox_peek',
+      description: 'List pending Feishu/Lark bot messages without locking them. Returns queue pending/processing/dead counters, or an error when the inbox is disabled or unconfigured.',
+      parameters: { limit: { type: 'integer', default: 10, description: 'Maximum pending messages (clamped to 1..50).' } },
+      output: {
+        schema: {
+          type: 'object', additionalProperties: false, properties: {
+            items: { type: 'array', items: { type: 'object', additionalProperties: false, properties: {
+              eventId: { type: 'string', required: true }, receivedAt: { type: 'string', required: true },
+              chatType: { type: 'string', required: true }, senderOpenId: { type: 'string', required: true },
+              messageType: { type: 'string', required: true }, contentPreview: { type: 'string', required: true },
+            } } },
+            pending: { type: 'integer' }, processing: { type: 'integer' }, dead: { type: 'integer' }, error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+      },
+      async execute(args) {
+        const store = getStore()
+        if (!store) return { error: NOT_RUNNING }
+        const stats = store.stats()
+        return { items: store.peek(clampLimit(args.limit)).map(preview), pending: stats.pending, processing: stats.processing, dead: stats.dead }
+      },
+      presentCall(args): GenericCallView { return { card: 'generic', title: 'Peek lark inbox', kind: 'read', rawInput: args } },
+    }),
+    defineTool({
+      name: 'lark_inbox_pop',
+      description: 'Claim the oldest pending Feishu/Lark message into processing. You must settle its eventId with lark_inbox_ack; stale claims are recovered before each pop.',
+      parameters: {},
+      output: {
+        schema: { type: 'object', additionalProperties: false, properties: {
+          item: { oneOf: [
+            { type: 'object', additionalProperties: false, properties: {
+              eventId: { type: 'string', required: true }, receivedAt: { type: 'string', required: true },
+              chatType: { type: 'string', required: true }, senderOpenId: { type: 'string', required: true },
+              messageType: { type: 'string', required: true }, content: { type: 'string', required: true }, messageId: { type: 'string', required: true },
+            } },
+            { type: 'null' },
+          ] }, pending: { type: 'integer' }, error: { type: 'string' },
+        } },
+        render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+      },
+      async execute() {
+        const store = getStore()
+        if (!store) return { error: NOT_RUNNING }
+        store.recoverStale()
+        const item = store.pop()
+        return { item: item === null ? null : popped(item), pending: store.stats().pending }
+      },
+      presentCall(args): GenericCallView { return { card: 'generic', title: 'Pop next lark inbox message', kind: 'read', rawInput: args } },
+    }),
+    defineTool({
+      name: 'lark_inbox_ack',
+      description: 'Settle a message claimed by lark_inbox_pop. ok=true marks done; ok=false retries it or moves it to dead after maxAttempts.',
+      parameters: {
+        event_id: { type: 'string', required: true, description: 'eventId returned by peek or pop.' },
+        ok: { type: 'boolean', required: true, description: 'true to finish, false to retry.' },
+        note: { type: 'string', description: 'Optional non-persisted decision note.' },
+      },
+      output: {
+        schema: { type: 'object', additionalProperties: false, properties: { status: { type: 'string', enum: ACK_STATUSES }, error: { type: 'string' } } },
+        render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+      },
+      async execute(args) {
+        const store = getStore()
+        if (!store) return { error: NOT_RUNNING }
+        const raw = args.ok ? store.ack(args.event_id) : store.nack(args.event_id)
+        const status: (typeof ACK_STATUSES)[number] = typeof raw === 'string' && (ACK_STATUSES as readonly string[]).includes(raw)
+          ? raw as (typeof ACK_STATUSES)[number]
+          : args.ok ? 'done' : 'pending'
+        return { status }
+      },
+      presentCall(args): GenericCallView { return { card: 'generic', title: 'Acknowledge lark inbox message', kind: 'read', rawInput: args } },
+    }),
+  ]
+}
+
+export function registerInboxTools(ctx: Context, getStore: () => InboxStore | undefined): () => void {
+  return registerResources(own => {
+    for (const tool of createInboxTools(getStore)) own(ctx.tools.register(tool))
+  })
+}

package/src/host/services/lark-inbox/wizard.ts

@@ -0,0 +1,206 @@
+/** Host-side lark-cli credential wizard. */
+
+import { spawn as nodeSpawn, type ChildProcess, type SpawnOptions } from 'node:child_process'
+import { mkdir } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+export class WizardSettingsUnavailableError extends Error {
+  readonly code = 'WIZARD_SETTINGS_UNAVAILABLE'
+  constructor() {
+    super('dsh-lark-inbox: settings 服务不可用，无法写入飞书凭据')
+    this.name = 'WizardSettingsUnavailableError'
+  }
+}
+
+export type WizardPhase =
+  | { phase: 'idle' }
+  | { phase: 'awaiting-browser'; mode: 'new'; verificationUrl: string; qrFilePath: string | null }
+  | { phase: 'awaiting-secret'; mode: 'bind'; appId: string; consoleUrl: string }
+  | { phase: 'done'; appId: string; needsSecretPaste: boolean }
+  | { phase: 'failed'; error: string }
+
+export type SpawnFn = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess
+
+export interface LarkWizardOptions {
+  settingsWrite(patch: { appId?: string; appSecret?: string }): Promise<void>
+  log?(level: 'info' | 'warn' | 'error', message: string): void
+  larkCli?: string
+  qrDir?: string
+  spawn?: SpawnFn
+}
+
+const INSTALL_HINT = '未找到 lark-cli，请先安装：npm i -g @larksuite/cli'
+
+function extractVerificationUrl(text: string): string | undefined {
+  const field = /["'](?:verification_uri_complete|verification_url)["']\s*[:=]\s*["']([^"']+)["']/i.exec(text)
+  if (field) return field[1]
+  const bare = /https:\/\/open\.feishu\.cn\/[^\s"'<>]+/i.exec(text)
+  return bare && !bare[0].includes('wss:') && !bare[0].includes('console') ? bare[0] : undefined
+}
+
+function extractOneTimeSecret(text: string): string | undefined {
+  const context = /(?:app[_-]?secret|secret)["'\s:=]+/gi
+  let match: RegExpExecArray | null
+  while ((match = context.exec(text)) !== null) {
+    const value = /^["']?([A-Za-z0-9._~\-]{8,})["']?/.exec(text.slice(match.index + match[0].length))?.[1]
+    if (value && !/^\*+$/.test(value)) return value
+  }
+  return undefined
+}
+
+function redactSecrets(text: string): string {
+  return text.replace(/((?:app[_-]?secret|secret)["'\s:=]+)([A-Za-z0-9._~\-]{8,}|"?\*+"?)/gi, '$1[redacted]')
+}
+
+export async function writeWithConflictRetry(write: () => Promise<void>): Promise<void> {
+  try {
+    await write()
+  } catch (error) {
+    if ((error as { code?: unknown } | null)?.code !== 'SETTINGS_CONFLICT') throw error
+    await write()
+  }
+}
+
+export class LarkWizard {
+  private readonly options: LarkWizardOptions
+  private readonly cli: string
+  private readonly qrDir: string
+  private readonly spawn: SpawnFn
+  private readonly log: NonNullable<LarkWizardOptions['log']>
+  private current: WizardPhase = { phase: 'idle' }
+  private child: ChildProcess | undefined
+
+  constructor(options: LarkWizardOptions) {
+    this.options = options
+    this.cli = options.larkCli ?? 'lark-cli'
+    this.qrDir = options.qrDir ?? join(process.env.TMPDIR ?? tmpdir(), 'dsh-lark-inbox-wizard')
+    this.spawn = options.spawn ?? ((command, args, spawnOptions) => nodeSpawn(command, args, spawnOptions))
+    this.log = options.log ?? (() => undefined)
+  }
+
+  state(): WizardPhase { return this.current }
+
+  async startNew(): Promise<{ verificationUrl: string; qrFilePath: string | null }> {
+    await this.cancel()
+    await mkdir(this.qrDir, { recursive: true })
+    let resolveUrl!: (url: string) => void
+    let rejectUrl!: (error: Error) => void
+    const urlSeen = new Promise<string>((resolve, reject) => { resolveUrl = resolve; rejectUrl = reject })
+    const child = this.spawn(this.cli, ['config', 'init', '--new'], { stdio: ['ignore', 'pipe', 'pipe'], cwd: this.qrDir, shell: false })
+    this.child = child
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    child.stdout?.on('data', chunk => {
+      stdout += String(chunk)
+      const url = extractVerificationUrl(stdout)
+      if (url !== undefined && !settled) { settled = true; resolveUrl(url) }
+    })
+    child.stderr?.on('data', chunk => { stderr += String(chunk) })
+    child.on('error', (error: NodeJS.ErrnoException) => {
+      if (this.child === child) this.child = undefined
+      const message = error.code === 'ENOENT' ? INSTALL_HINT : `lark-cli 启动失败：${redactSecrets(error.message)}`
+      this.current = { phase: 'failed', error: message }
+      if (!settled) { settled = true; rejectUrl(new Error(message)) }
+    })
+    child.on('exit', (code: number | null, signal: NodeJS.Signals | null) => {
+      if (this.child === child) this.child = undefined
+      if (!settled) { settled = true; rejectUrl(new Error('lark-cli 未输出授权链接即退出')); return }
+      void this.completeInit(code, signal, stdout, stderr)
+    })
+    const verificationUrl = await urlSeen
+    let qrFilePath: string | null = null
+    try { if (await this.generateQr(verificationUrl)) qrFilePath = join(this.qrDir, 'qr.png') } catch { qrFilePath = null }
+    if (this.child === child) this.current = { phase: 'awaiting-browser', mode: 'new', verificationUrl, qrFilePath }
+    return { verificationUrl, qrFilePath }
+  }
+
+  startBind(appId: string): { consoleUrl: string } {
+    const consoleUrl = `https://open.feishu.cn/app/${appId}`
+    this.current = { phase: 'awaiting-secret', mode: 'bind', appId, consoleUrl }
+    return { consoleUrl }
+  }
+
+  async finishBind(appSecret: string): Promise<void> {
+    const secret = appSecret.trim()
+    if (secret === '') {
+      const error = new Error('appSecret 不能为空')
+      this.current = { phase: 'failed', error: error.message }
+      throw error
+    }
+    const current = this.current
+    if (current.phase !== 'awaiting-secret') {
+      const error = new Error('当前不在绑定流程，请先调用 startBind')
+      this.current = { phase: 'failed', error: error.message }
+      throw error
+    }
+    try {
+      await this.options.settingsWrite({ appId: current.appId, appSecret: secret })
+      this.current = { phase: 'done', appId: current.appId, needsSecretPaste: false }
+      this.log('info', 'dsh-lark-inbox: 已绑定飞书应用并写入凭据')
+    } catch (error) {
+      this.current = { phase: 'failed', error: redactSecrets(error instanceof Error ? error.message : String(error)) }
+      throw error
+    }
+  }
+
+  async cancel(): Promise<void> {
+    const child = this.child
+    this.child = undefined
+    if (child) { try { child.kill('SIGTERM') } catch { /* already exited */ } }
+    this.current = { phase: 'idle' }
+  }
+
+  private generateQr(url: string): Promise<boolean> {
+    return new Promise(resolve => {
+      const child = this.spawn(this.cli, ['auth', 'qrcode', url, '--output', 'qr.png'], { stdio: ['ignore', 'ignore', 'ignore'], cwd: this.qrDir, shell: false })
+      child.on('error', () => resolve(false))
+      child.on('exit', code => resolve(code === 0))
+    })
+  }
+
+  private async completeInit(code: number | null, signal: NodeJS.Signals | null, stdout: string, stderr: string): Promise<void> {
+    if (signal) return
+    if (code !== 0) {
+      const tail = stderr.trim() === '' ? `lark-cli config init 退出码 ${code ?? 'null'}` : stderr.slice(-400)
+      this.current = { phase: 'failed', error: redactSecrets(tail) }
+      return
+    }
+    try {
+      const appId = await this.configShowAppId()
+      const secret = extractOneTimeSecret(stdout)
+      if (secret !== undefined) {
+        await this.options.settingsWrite({ appId, appSecret: secret })
+        this.current = { phase: 'done', appId, needsSecretPaste: false }
+        this.log('info', 'dsh-lark-inbox: 已创建飞书应用并写入凭据')
+      } else {
+        await this.options.settingsWrite({ appId })
+        this.current = { phase: 'done', appId, needsSecretPaste: true }
+        this.log('info', 'dsh-lark-inbox: 已写入 appId，仍需粘贴 appSecret')
+      }
+    } catch (error) {
+      this.current = { phase: 'failed', error: redactSecrets(error instanceof Error ? error.message : String(error)) }
+    }
+  }
+
+  private configShowAppId(): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const child = this.spawn(this.cli, ['config', 'show'], { stdio: ['ignore', 'pipe', 'pipe'], cwd: this.qrDir, shell: false })
+      let stdout = ''
+      let stderr = ''
+      child.stdout?.on('data', chunk => { stdout += String(chunk) })
+      child.stderr?.on('data', chunk => { stderr += String(chunk) })
+      child.on('error', (error: NodeJS.ErrnoException) => reject(new Error(redactSecrets(error.code === 'ENOENT' ? INSTALL_HINT : error.message))))
+      child.on('exit', code => {
+        if (code !== 0) { reject(new Error(redactSecrets(stderr.trim() === '' ? `lark-cli config show 退出码 ${code ?? 'null'}` : stderr.slice(-400)))); return }
+        try {
+          const parsed = JSON.parse(stdout) as { appId?: unknown }
+          if (typeof parsed.appId === 'string' && parsed.appId !== '') { resolve(parsed.appId); return }
+        } catch { /* regex fallback */ }
+        const match = /"appId"\s*:\s*"([^"]+)"/.exec(stdout)
+        match ? resolve(match[1]) : reject(new Error('lark-cli config show 未返回 appId'))
+      })
+    })
+  }
+}

package/src/host/services/lifecycle.ts

@@ -0,0 +1,107 @@
+/** Lifecycle owner for all host service-domain registrations in the web-all entity. */
+
+export type ServiceDisposer = () => void | Promise<void>
+
+export interface ServiceRegistrationDiagnostic {
+  service: string
+  phase: 'register' | 'dispose'
+  message: string
+  error: unknown
+  at: number
+}
+
+export interface ServiceLifecycleOptions {
+  onDiagnostic?: (diagnostic: ServiceRegistrationDiagnostic) => void
+  now?: () => number
+}
+
+export interface ServiceLifecycleOwner {
+  readonly signal: AbortSignal
+  readonly diagnostics: readonly ServiceRegistrationDiagnostic[]
+  mount(service: string, register: () => ServiceDisposer): void
+  track(service: string, registration: Promise<ServiceDisposer>): void
+  dispose(): Promise<void>
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function isAbort(error: unknown): boolean {
+  return error instanceof Error && (error.name === 'AbortError' || /aborted/i.test(error.message))
+}
+
+/**
+ * Own sync and async service registrations under one deterministic lifetime.
+ * Async registrations that settle after disposal are torn down immediately;
+ * owner disposal aborts and awaits every tracked registration before returning.
+ */
+export function createServiceLifecycleOwner(options: ServiceLifecycleOptions = {}): ServiceLifecycleOwner {
+  const controller = new AbortController()
+  const diagnostics: ServiceRegistrationDiagnostic[] = []
+  const disposers: Array<{ service: string; dispose: ServiceDisposer }> = []
+  const pending = new Set<Promise<void>>()
+  let disposed = false
+  let disposing: Promise<void> | undefined
+
+  const report = (service: string, phase: ServiceRegistrationDiagnostic['phase'], error: unknown): void => {
+    const diagnostic = { service, phase, message: errorMessage(error), error, at: (options.now ?? Date.now)() }
+    diagnostics.push(diagnostic)
+    // Observability must never become a second failure that interrupts rollback.
+    try { options.onDiagnostic?.(diagnostic) } catch { /* retained in diagnostics */ }
+  }
+
+  const runDisposer = async (service: string, dispose: ServiceDisposer): Promise<void> => {
+    try { await dispose() } catch (error) { report(service, 'dispose', error) }
+  }
+
+  const add = (service: string, dispose: ServiceDisposer): void => {
+    if (disposed) {
+      const late = runDisposer(service, dispose)
+      pending.add(late)
+      void late.finally(() => pending.delete(late))
+      return
+    }
+    disposers.push({ service, dispose })
+  }
+
+  const owner: ServiceLifecycleOwner = {
+    signal: controller.signal,
+    get diagnostics() { return diagnostics },
+    mount(service, register) {
+      if (disposed) return
+      try { add(service, register()) } catch (error) { report(service, 'register', error) }
+    },
+    track(service, registration) {
+      const tracked = registration.then(
+        dispose => { add(service, dispose) },
+        error => { if (!(disposed && isAbort(error))) report(service, 'register', error) },
+      )
+      pending.add(tracked)
+      void tracked.finally(() => pending.delete(tracked))
+    },
+    dispose() {
+      if (disposing !== undefined) return disposing
+      disposed = true
+      controller.abort(new DOMException('web-all service owner disposed', 'AbortError'))
+      disposing = (async () => {
+        while (pending.size > 0) await Promise.allSettled([...pending])
+        for (const entry of disposers.splice(0).reverse()) await runDisposer(entry.service, entry.dispose)
+        while (pending.size > 0) await Promise.allSettled([...pending])
+      })()
+      return disposing
+    },
+  }
+  return owner
+}
+
+/** Reject promptly on owner abort without allowing the underlying task to register late resources. */
+export async function abortable<T>(operation: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (signal === undefined) return operation
+  signal.throwIfAborted()
+  return await new Promise<T>((resolve, reject) => {
+    const abort = (): void => reject(signal.reason ?? new DOMException('aborted', 'AbortError'))
+    signal.addEventListener('abort', abort, { once: true })
+    void operation.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort))
+  })
+}

package/src/host/services/memoir/index.ts

@@ -0,0 +1,80 @@
+/**
+ * memoir host 服务域（全新实现；行为契约参考旧包）。
+ *
+ * 记忆系统：store（按项目路径分键的条目存储）+ settings + 
+ * /api/dsh-memoir/* 路由族 + agent 工具（memoir_record/read/update）。
+ * 注册入口 register(ctx, deps)，由 host 装配器统一调用。
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-tools'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import { MemoirStore, renderHotMemory } from './store.ts'
+import { MemoirSettingsStore } from './settings.ts'
+import { registerRoutes } from './routes.ts'
+import { makeMemoirTools } from './tools.ts'
+import { registerResources } from '../resources.ts'
+
+export { MemoirStore, type MemoirEntry, type SectionKey } from './store.ts'
+export { MemoirSettingsStore, type MemoirSettings } from './settings.ts'
+
+const SECTION_ORDER = 150
+export const MEMOIR_GUIDANCE = 'dsh-memoir 提供项目持久记忆。下方仅注入本项目高优先级记忆；需要历史细节时调用 memoir_read；产生可复用的工作结论、经验或后续行动时调用 memoir_record。'
+export const MEMOIR_SECTION_HEADING = '## 项目持久记忆（自动注入）'
+export const PROMPT_MEMORY_VARIABLE = 'project_memory'
+export const PROMPT_MEMORY_REFERENCE = '{{project_memory}}'
+
+interface MemoirAssembleContext {
+  agent?: { session?: { header?: { cwd?: string } } }
+}
+
+/** Build the variable value; raw memory never enters section text. */
+export function memoirVariableText(store: MemoirStore, context: MemoirAssembleContext, maxTokens: number): string {
+  const cwd = context.agent?.session?.header?.cwd
+  if (typeof cwd !== 'string' || cwd === '') return MEMOIR_GUIDANCE
+  const hot = renderHotMemory(store.project(cwd), maxTokens)
+  return hot === '' ? MEMOIR_GUIDANCE : `${MEMOIR_GUIDANCE}\n\n${MEMOIR_SECTION_HEADING}\n${hot}`
+}
+
+/** 服务域依赖。 */
+export interface MemoirServiceDeps {
+  /** 存储路径（默认 ~/.dsh/dsh-memoir.json）。 */
+  storePath?: string
+  /** 设置路径（默认 ~/.dsh/dsh-memoir.settings.json）。 */
+  settingsPath?: string
+  /** 日志。 */
+  logger?: { warn(error: unknown): void }
+}
+
+/** 服务域注册入口；返回统一 disposer。 */
+export function register(ctx: Context, deps: MemoirServiceDeps = {}): () => void {
+  const logger = deps.logger ?? { warn: (error: unknown) => { console.warn('[web-all:memoir]', error) } }
+  const store = new MemoirStore(deps.storePath)
+  const settingsStore = new MemoirSettingsStore(deps.settingsPath)
+  const settings = (): ReturnType<MemoirSettingsStore['load']> => settingsStore.load()
+  const saveSettings = (value: ReturnType<MemoirSettingsStore['load']>): void => { settingsStore.save(value) }
+
+  return registerResources(own => {
+    own(registerRoutes(ctx, { store, settings, saveSettings, logger }))
+    for (const tool of makeMemoirTools(store, settings)) own(ctx.tools.register(tool))
+
+    let disposePrompt: (() => void) | undefined
+    const syncPrompt = (): void => {
+      disposePrompt?.()
+      disposePrompt = undefined
+      const current = settings()
+      if (!current.enabled || !current.announceToAgent) return
+      disposePrompt = registerResources(ownPrompt => {
+        ownPrompt(ctx.systemPrompt.variable(PROMPT_MEMORY_VARIABLE, context =>
+          memoirVariableText(store, context as MemoirAssembleContext, settings().hotMemoryMaxTokens)))
+        ownPrompt(ctx.systemPrompt.section({
+          name: 'plugin:dsh-memoir',
+          order: SECTION_ORDER,
+          text: PROMPT_MEMORY_REFERENCE,
+        }))
+      })
+    }
+    own(() => { disposePrompt?.() })
+    own(settingsStore.subscribe(() => syncPrompt()))
+    syncPrompt()
+  })
+}