@v587d/capital-generation 2.12.0 → 2.13.0

package/automation/schema.js

@@ -0,0 +1,359 @@
+/**
+ * Strict storage and wire schemas for the automation domain. Every object is a
+ * `strictObject`: an unknown field is a write error, not something JSON will silently drop.
+ * Run/notification records are disposable; task records are authoritative.
+ */
+import { z } from 'zod'
+import {
+  ACTIVE_RUN_STATUSES,
+  MAX_DESCRIPTION_CHARS,
+  MAX_ERROR_MESSAGE_CHARS,
+  MAX_ERRORS_PER_RUN,
+  MAX_INSTRUCTION_CHARS,
+  MAX_MAX_STEPS,
+  MAX_MAX_TOOL_CALLS,
+  MAX_RUN_TIMEOUT_MINUTES,
+  MAX_TITLE_CHARS,
+  MIN_MAX_STEPS,
+  MIN_MAX_TOOL_CALLS,
+  MIN_RUN_TIMEOUT_MINUTES,
+  RUN_STATUSES,
+} from './defaults.js'
+
+const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/
+
+/** Canonical UTC ISO instant; `Date.parse` alone accepts offsets and seconds variants. */
+export const isoInstant = z.string().refine((value) => ISO_UTC.test(value) && new Date(value).toISOString() === value, {
+  message: 'must be a canonical UTC ISO instant',
+})
+
+const TIME_OF_DAY = /^(?:[01]\d|2[0-3]):[0-5]\d$/
+
+export function isValidTimeZone(value) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 64) return false
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: value }).format(0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export const timeZone = z.string().min(1).max(64).refine(isValidTimeZone, { message: 'must be a valid IANA time zone' })
+
+/** Registered Workspace id; empty/absent means the profile's dedicated automation workspace. */
+export const workspaceId = z.string().max(120)
+
+export const TriggerSchema = z.strictObject({
+  kind: z.literal('schedule'),
+  cadence: z.enum(['daily', 'weekly', 'monthly']),
+  time: z.string().regex(TIME_OF_DAY, { message: 'must be HH:mm' }),
+  timezone: timeZone,
+  weekdays: z.array(z.number().int().min(1).max(7)).min(1).max(7).optional(),
+  dayOfMonth: z.number().int().min(1).max(28).optional(),
+  tradingDaysOnly: z.boolean(),
+}).superRefine((trigger, ctx) => {
+  if (trigger.cadence === 'weekly') {
+    if (trigger.weekdays === undefined) ctx.addIssue({ code: 'custom', path: ['weekdays'], message: 'weekly requires weekdays' })
+    else if (new Set(trigger.weekdays).size !== trigger.weekdays.length) ctx.addIssue({ code: 'custom', path: ['weekdays'], message: 'weekdays must be unique' })
+    if (trigger.dayOfMonth !== undefined) ctx.addIssue({ code: 'custom', path: ['dayOfMonth'], message: 'weekly must not carry dayOfMonth' })
+  }
+  if (trigger.cadence === 'monthly') {
+    if (trigger.dayOfMonth === undefined) ctx.addIssue({ code: 'custom', path: ['dayOfMonth'], message: 'monthly requires dayOfMonth' })
+    if (trigger.weekdays !== undefined) ctx.addIssue({ code: 'custom', path: ['weekdays'], message: 'monthly must not carry weekdays' })
+  }
+  if (trigger.cadence === 'daily') {
+    if (trigger.weekdays !== undefined) ctx.addIssue({ code: 'custom', path: ['weekdays'], message: 'daily must not carry weekdays' })
+    if (trigger.dayOfMonth !== undefined) ctx.addIssue({ code: 'custom', path: ['dayOfMonth'], message: 'daily must not carry dayOfMonth' })
+  }
+})
+
+export const LimitsSchema = z.strictObject({
+  runTimeoutMinutes: z.number().int().min(MIN_RUN_TIMEOUT_MINUTES).max(MAX_RUN_TIMEOUT_MINUTES),
+  idleTimeoutMinutes: z.number().int().min(1).max(30),
+  maxSteps: z.number().int().min(MIN_MAX_STEPS).max(MAX_MAX_STEPS),
+  maxToolCalls: z.number().int().min(MIN_MAX_TOOL_CALLS).max(MAX_MAX_TOOL_CALLS),
+})
+
+export const NotificationsSchema = z.strictObject({
+  inApp: z.boolean(),
+  onFailure: z.boolean(),
+  onSuccess: z.boolean(),
+})
+
+export const ExecutionModeSchema = z.enum(['news', 'market', 'review', 'research'])
+
+/** User-writable configuration. Server-owned fields are deliberately absent. */
+export const TaskConfigSchema = z.strictObject({
+  category: z.enum(['news', 'market', 'review', 'research']),
+  title: z.string().min(1).max(MAX_TITLE_CHARS),
+  description: z.string().max(MAX_DESCRIPTION_CHARS),
+  trigger: TriggerSchema,
+  instruction: z.string().min(1).max(MAX_INSTRUCTION_CHARS),
+  mode: ExecutionModeSchema,
+  cwdKind: z.literal('profile'),
+  workspaceId: workspaceId.optional(),
+  limits: LimitsSchema,
+  notifications: NotificationsSchema,
+})
+
+export const TaskOverridesSchema = z.strictObject({
+  category: z.enum(['news', 'market', 'review', 'research']).optional(),
+  title: z.string().min(1).max(MAX_TITLE_CHARS).optional(),
+  description: z.string().max(MAX_DESCRIPTION_CHARS).optional(),
+  trigger: TriggerSchema.optional(),
+  instruction: z.string().min(1).max(MAX_INSTRUCTION_CHARS).optional(),
+  mode: ExecutionModeSchema.optional(),
+  workspaceId: workspaceId.optional(),
+  limits: LimitsSchema.optional(),
+  notifications: NotificationsSchema.optional(),
+})
+
+export const TaskStateSchema = z.enum(['dormant', 'active', 'paused'])
+
+export const AutomationTaskSchema = z.strictObject({
+  id: z.string().min(1).max(80),
+  schemaVersion: z.literal(1),
+  definitionVersion: z.number().int().min(0),
+  origin: z.enum(['builtin', 'custom']),
+  sourceBuiltinId: z.string().min(1).max(80).optional(),
+  profileKey: z.string().min(1).max(80),
+  profileName: z.string().min(1).max(200),
+  state: TaskStateSchema,
+  category: z.enum(['news', 'market', 'review', 'research']),
+  title: z.string().min(1).max(MAX_TITLE_CHARS),
+  description: z.string().max(MAX_DESCRIPTION_CHARS),
+  trigger: TriggerSchema,
+  instruction: z.string().min(1).max(MAX_INSTRUCTION_CHARS),
+  mode: ExecutionModeSchema,
+  cwdKind: z.literal('profile'),
+  workspaceId: workspaceId.optional(),
+  limits: LimitsSchema,
+  notifications: NotificationsSchema,
+  overrides: TaskOverridesSchema.optional(),
+  scheduleAnchorAt: isoInstant,
+  lastHandledOccurrenceKey: z.string().max(300).optional(),
+  lastScheduledFor: isoInstant.optional(),
+  createdAt: isoInstant,
+  updatedAt: isoInstant,
+})
+
+/** Durable builtin override row. Runtime fields (state, anchors) always sit on the record. */
+export const TaskRecordSchema = z.strictObject({
+  schemaVersion: z.literal(1),
+  id: z.string().min(1).max(80),
+  origin: z.enum(['builtin', 'custom']),
+  sourceBuiltinId: z.string().min(1).max(80).optional(),
+  profileKey: z.string().min(1).max(80),
+  profileName: z.string().min(1).max(200),
+  state: TaskStateSchema,
+  definitionVersion: z.number().int().min(0),
+  custom: TaskConfigSchema.optional(),
+  overrides: TaskOverridesSchema.optional(),
+  scheduleAnchorAt: isoInstant,
+  lastHandledOccurrenceKey: z.string().max(300).optional(),
+  lastScheduledFor: isoInstant.optional(),
+  createdAt: isoInstant,
+  updatedAt: isoInstant,
+})
+
+export const RunErrorSchema = z.strictObject({
+  at: isoInstant,
+  phase: z.enum(['schedule', 'session', 'turn', 'tool', 'llm', 'timeout', 'storage']),
+  severity: z.enum(['error', 'warning']),
+  code: z.string().min(1).max(80),
+  message: z.string().min(1).max(MAX_ERROR_MESSAGE_CHARS),
+  tool: z.string().max(80).optional(),
+  callId: z.string().max(120).optional(),
+})
+
+export const RunRecordSchema = z.strictObject({
+  schemaVersion: z.literal(1),
+  id: z.string().min(1).max(80),
+  profileKey: z.string().min(1).max(80),
+  taskId: z.string().min(1).max(80),
+  taskTitle: z.string().min(1).max(MAX_TITLE_CHARS),
+  trigger: z.enum(['scheduled', 'manual']),
+  occurrenceKey: z.string().min(1).max(300),
+  scheduleVersion: z.string().min(1).max(80).optional(),
+  scheduledFor: isoInstant.optional(),
+  status: z.enum(RUN_STATUSES),
+  sessionId: z.string().min(1).max(120).optional(),
+  sessionTitle: z.string().min(1).max(200).optional(),
+  queuedAt: isoInstant,
+  startedAt: isoInstant.optional(),
+  finishedAt: isoInstant.optional(),
+  durationMs: z.number().int().min(0).optional(),
+  steps: z.number().int().min(0),
+  toolCalls: z.number().int().min(0),
+  blockedRequiresUser: z.boolean(),
+  errors: z.array(RunErrorSchema).max(MAX_ERRORS_PER_RUN),
+  summary: z.string().max(2_000).optional(),
+})
+
+export const AttemptRecordSchema = z.strictObject({
+  schemaVersion: z.literal(1),
+  id: z.string().min(1).max(300),
+  profileKey: z.string().min(1).max(80),
+  taskId: z.string().min(1).max(80),
+  runId: z.string().min(1).max(80),
+  occurrenceKey: z.string().min(1).max(300),
+  state: z.enum(['claimed', 'session_created', 'prompt_submitted', 'accepted', 'failed', 'unknown']),
+  createdAt: isoInstant,
+  updatedAt: isoInstant,
+})
+
+export const NotificationSchema = z.strictObject({
+  schemaVersion: z.literal(1),
+  id: z.string().min(1).max(80),
+  profileKey: z.string().min(1).max(80),
+  kind: z.enum(['run_failed', 'run_timeout', 'run_succeeded', 'scheduler_standby', 'calendar_unavailable', 'skipped']),
+  title: z.string().min(1).max(120),
+  message: z.string().max(MAX_ERROR_MESSAGE_CHARS),
+  runId: z.string().min(1).max(80).optional(),
+  taskId: z.string().min(1).max(80).optional(),
+  createdAt: isoInstant,
+  readAt: isoInstant.optional(),
+})
+
+export const OwnerRecordSchema = z.strictObject({
+  schemaVersion: z.literal(1),
+  profileKey: z.string().min(1).max(80),
+  ownerId: z.string().min(1).max(120),
+  fencingToken: z.string().min(1).max(120),
+  leaseExpiresAt: isoInstant,
+  heartbeatAt: isoInstant,
+  schedulerState: z.enum(['active', 'standby']),
+  updatedAt: isoInstant,
+})
+
+/** Create/patch wire schemas: no profile, owner, session, preset or cwd field exists at all. */
+export const TaskCreateSchema = z.strictObject({
+  title: z.string().min(1).max(MAX_TITLE_CHARS),
+  description: z.string().max(MAX_DESCRIPTION_CHARS).optional(),
+  instruction: z.string().min(1).max(MAX_INSTRUCTION_CHARS),
+  category: z.enum(['news', 'market', 'review', 'research']),
+  trigger: TriggerSchema,
+  mode: ExecutionModeSchema,
+  workspaceId: workspaceId.optional(),
+  limits: LimitsSchema.optional(),
+  notifications: NotificationsSchema.optional(),
+})
+
+export const TaskPatchSchema = z.strictObject({
+  title: z.string().min(1).max(MAX_TITLE_CHARS).optional(),
+  description: z.string().max(MAX_DESCRIPTION_CHARS).optional(),
+  instruction: z.string().min(1).max(MAX_INSTRUCTION_CHARS).optional(),
+  category: z.enum(['news', 'market', 'review', 'research']).optional(),
+  trigger: TriggerSchema.optional(),
+  mode: ExecutionModeSchema.optional(),
+  workspaceId: workspaceId.optional(),
+  limits: LimitsSchema.optional(),
+  notifications: NotificationsSchema.optional(),
+})
+
+export const NotificationsReadSchema = z.strictObject({
+  ids: z.array(z.string().min(1).max(80)).max(200).optional(),
+  all: z.boolean().optional(),
+}).refine((value) => value.all === true || (value.ids !== undefined && value.ids.length > 0), {
+  message: 'either all=true or a non-empty ids array is required',
+})
+
+export const BuiltinDefaultsSchema = z.strictObject({
+  state: z.literal('dormant'),
+  category: z.enum(['news', 'market', 'review', 'research']),
+  title: z.string().min(1).max(MAX_TITLE_CHARS),
+  description: z.string().max(MAX_DESCRIPTION_CHARS),
+  trigger: TriggerSchema,
+  instruction: z.string().min(1).max(MAX_INSTRUCTION_CHARS),
+  mode: ExecutionModeSchema,
+  cwdKind: z.literal('profile'),
+  limits: LimitsSchema,
+  notifications: NotificationsSchema,
+})
+
+export const BuiltinDefinitionSchema = z.strictObject({
+  id: z.string().min(1).max(80),
+  version: z.number().int().min(1),
+  category: z.enum(['news', 'market', 'review', 'research']),
+  defaults: BuiltinDefaultsSchema,
+})
+
+/** Reject values JSON would silently change: undefined, NaN/Infinity, holes, non-object members. */
+export function assertCleanJson(value, path = '$') {
+  if (value === undefined) throw new TypeError(`undefined is not allowed at ${path}`)
+  if (typeof value === 'number' && !Number.isFinite(value)) throw new TypeError(`non-finite number at ${path}`)
+  if (typeof value === 'function' || typeof value === 'symbol' || typeof value === 'bigint') {
+    throw new TypeError(`unsupported value at ${path}`)
+  }
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) {
+      if (!(index in value)) throw new TypeError(`sparse array hole at ${path}[${index}]`)
+      assertCleanJson(value[index], `${path}[${index}]`)
+    }
+    return
+  }
+  if (value !== null && typeof value === 'object') {
+    const proto = Object.getPrototypeOf(value)
+    if (proto !== Object.prototype && proto !== null) throw new TypeError(`non-plain object at ${path}`)
+    for (const [key, item] of Object.entries(value)) assertCleanJson(item, `${path}.${key}`)
+  }
+}
+
+export function parseStrict(schema, value, label) {
+  try {
+    assertCleanJson(value)
+  } catch (error) {
+    throw new SchemaError('invalid_record', `${label}: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  const result = schema.safeParse(value)
+  if (!result.success) {
+    const issue = result.error.issues[0]
+    const where = issue?.path?.length ? ` at ${issue.path.join('.')}` : ''
+    throw new SchemaError('invalid_record', `${label}${where}: ${issue?.message ?? 'invalid value'}`)
+  }
+  return result.data
+}
+
+export class SchemaError extends Error {
+  constructor(code, message) {
+    super(message)
+    this.name = 'SchemaError'
+    this.code = code
+  }
+}
+
+export function isActiveRun(status) {
+  return ACTIVE_RUN_STATUSES.includes(status)
+}
+
+/** Merge order: code definition -> legal user override -> server runtime fields. */
+export function resolveTaskRecord(record, definition) {
+  const base = record.origin === 'builtin'
+    ? definition?.defaults
+    : record.custom
+  if (base === undefined) throw new SchemaError('invalid_record', `task ${record.id} has no resolvable base configuration`)
+  const overrides = record.overrides ?? {}
+  const merged = {
+    ...base,
+    ...overrides,
+    state: record.state,
+  }
+  const task = {
+    id: record.id,
+    schemaVersion: 1,
+    definitionVersion: record.definitionVersion,
+    origin: record.origin,
+    ...(record.sourceBuiltinId === undefined ? {} : { sourceBuiltinId: record.sourceBuiltinId }),
+    profileKey: record.profileKey,
+    profileName: record.profileName,
+    ...merged,
+    ...(record.overrides === undefined ? {} : { overrides: record.overrides }),
+    scheduleAnchorAt: record.scheduleAnchorAt,
+    ...(record.lastHandledOccurrenceKey === undefined ? {} : { lastHandledOccurrenceKey: record.lastHandledOccurrenceKey }),
+    ...(record.lastScheduledFor === undefined ? {} : { lastScheduledFor: record.lastScheduledFor }),
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+  }
+  return parseStrict(AutomationTaskSchema, task, 'automation task')
+}

package/automation/service.js

@@ -0,0 +1,338 @@
+/**
+ * API service. All mutations serialize on one promise chain so a manual run, a tick claim, and
+ * a page cancel cannot interleave profile-visible state. Every lookup goes through the store's
+ * profile filter; the wire body never selects a profile.
+ */
+import {
+  DEFAULT_AUTOMATION_SETTINGS,
+  MAX_IDLE_TIMEOUT_MINUTES,
+  MAX_MAX_STEPS,
+  MAX_MAX_TOOL_CALLS,
+  MAX_RUN_TIMEOUT_MINUTES,
+  MIN_IDLE_TIMEOUT_MINUTES,
+  MIN_MAX_STEPS,
+  MIN_MAX_TOOL_CALLS,
+  MIN_RUN_TIMEOUT_MINUTES,
+} from './defaults.js'
+import {
+  NotificationsReadSchema,
+  TaskCreateSchema,
+  TaskPatchSchema,
+  parseStrict,
+} from './schema.js'
+import { sanitizeMessage } from './redact.js'
+
+const MAX_RUN_PAGE_LIMIT = 2_000
+const RUN_CURSOR_PATTERN = /^[A-Za-z0-9_-]{1,120}$/
+
+function invalidQuery(message) {
+  return new AutomationError('invalid_query', message, 400)
+}
+
+function runLimitOf(value) {
+  if (value === undefined) return 50
+  if (typeof value !== 'string' && typeof value !== 'number') throw invalidQuery('运行分页 limit 无效。')
+  const text = String(value)
+  if (!/^[1-9]\d{0,3}$/.test(text)) throw invalidQuery('运行分页 limit 必须是 1–2000 的整数。')
+  const limit = Number(text)
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_RUN_PAGE_LIMIT) {
+    throw invalidQuery('运行分页 limit 必须是 1–2000 的整数。')
+  }
+  return limit
+}
+
+function runCursorOf(value) {
+  if (value === undefined || value === '') return undefined
+  if (typeof value !== 'string' || !RUN_CURSOR_PATTERN.test(value)) {
+    throw new AutomationError('invalid_cursor', '运行分页游标无效。', 400)
+  }
+  return value
+}
+
+export class AutomationError extends Error {
+  constructor(code, message, status = 400, extra = {}) {
+    super(message)
+    this.name = 'AutomationError'
+    this.code = code
+    this.status = status
+    this.extra = extra
+  }
+}
+
+export function createAutomationService(options) {
+  const { store, scheduler, runner, calendar, profile, workspaces, version, settings, now = () => Date.now() } = options
+  let chain = Promise.resolve()
+
+  function serialize(operation) {
+    const next = chain.then(operation, operation)
+    chain = next.then(() => {}, () => {})
+    return next
+  }
+
+  async function withTask(id) {
+    const task = await store.getTask(id)
+    if (task === undefined) throw new AutomationError('task_not_found', '任务不存在。', 404)
+    return task
+  }
+
+  async function runningTask(task) {
+    const active = await store.activeRunForTask(task.id)
+    if (active !== undefined) {
+      throw new AutomationError('run_in_progress', '任务仍在运行，请先取消或等待终态。', 409, { runId: active.id })
+    }
+  }
+
+  async function assertWorkspace(workspaceId) {
+    if (workspaceId === undefined || workspaceId === '') return
+    if (workspaces === undefined) {
+      throw new AutomationError('workspace_unavailable', '工作区服务暂时不可用，不能指定工作区。', 503)
+    }
+    try {
+      await workspaces.validate(workspaceId)
+    } catch (error) {
+      if (error?.code === 'workspace_not_found') {
+        throw new AutomationError('workspace_not_found', error.message, 400)
+      }
+      throw new AutomationError('workspace_unavailable', error?.message ?? '工作区服务暂时不可用。', 503)
+    }
+  }
+
+  async function listTasks() {
+    const tasks = await store.listTasks()
+    const { runs } = await store.listRunsPage({ limit: 2_000 })
+    const runsByTask = new Map()
+    for (const run of runs) {
+      const taskRuns = runsByTask.get(run.taskId)
+      if (taskRuns === undefined) runsByTask.set(run.taskId, [run])
+      else taskRuns.push(run)
+    }
+    const notifications = await store.listNotifications({ unreadOnly: true, limit: 200 })
+    const unread = new Map()
+    for (const item of notifications) {
+      if (item.taskId === undefined) continue
+      unread.set(item.taskId, (unread.get(item.taskId) ?? 0) + 1)
+    }
+    return tasks.map((task) => ({
+      ...store.decorateTask(task, runsByTask.get(task.id) ?? []),
+      unread: unread.get(task.id) ?? 0,
+    }))
+  }
+
+  async function meta() {
+    let storage = { state: 'ready', error: null }
+    try {
+      await store.open()
+    } catch (error) {
+      storage = { state: 'unavailable', error: sanitizeMessage(String(error)) }
+    }
+    let workspaceList = []
+    let workspaceError
+    try {
+      workspaceList = await workspaces?.list?.() ?? []
+    } catch (error) {
+      workspaceError = sanitizeMessage(String(error?.message ?? error))
+    }
+    return {
+      profile: { key: store.profileKey, name: profile.displayName, state: 'current' },
+      version,
+      storage,
+      workspaces: workspaceList,
+      defaultWorkspaceId: workspaceList.find((item) => item.default === true)?.id ?? null,
+      ...(workspaceError === undefined ? {} : { workspaceError }),
+      scheduler: scheduler === undefined ? { state: 'unavailable' } : scheduler.status(),
+      calendar: calendar?.status?.(new Date(now())) ?? { available: false, source: 'none' },
+      execution: {
+        preset: 'capital-generation',
+        cwdKind: 'profile',
+        policy: 'automation-v1',
+        modes: ['news', 'market', 'review', 'research'],
+        cadences: ['daily', 'weekly', 'monthly'],
+        limits: {
+          runTimeoutMinutes: [MIN_RUN_TIMEOUT_MINUTES, MAX_RUN_TIMEOUT_MINUTES],
+          idleTimeoutMinutes: [MIN_IDLE_TIMEOUT_MINUTES, MAX_IDLE_TIMEOUT_MINUTES],
+          maxSteps: [MIN_MAX_STEPS, MAX_MAX_STEPS],
+          maxToolCalls: [MIN_MAX_TOOL_CALLS, MAX_MAX_TOOL_CALLS],
+        },
+        settings: settings(),
+      },
+    }
+  }
+
+  async function createTask(input) {
+    const parsed = parseStrict(TaskCreateSchema, input, 'task')
+    const defaults = { ...DEFAULT_AUTOMATION_SETTINGS, ...settings() }
+    const resolved = {
+      ...parsed,
+      limits: parsed.limits ?? {
+        runTimeoutMinutes: defaults.runTimeoutMinutes,
+        idleTimeoutMinutes: defaults.idleTimeoutMinutes,
+        maxSteps: defaults.maxSteps,
+        maxToolCalls: defaults.maxToolCalls,
+      },
+      notifications: parsed.notifications ?? {
+        inApp: defaults.inAppNotifications !== false,
+        onFailure: true,
+        onSuccess: false,
+      },
+    }
+    return serialize(async () => {
+      await assertWorkspace(parsed.workspaceId)
+      const record = await store.createTask(resolved)
+      return store.getTask(record.id)
+    })
+  }
+
+  async function patchTask(id, input) {
+    const parsed = parseStrict(TaskPatchSchema, input, 'task')
+    if (Object.keys(parsed).length === 0) throw new AutomationError('empty_patch', '没有需要修改的字段。', 400)
+    return serialize(async () => {
+      await withTask(id)
+      await assertWorkspace(parsed.workspaceId)
+      const record = await store.patchTask(id, parsed)
+      if (record === undefined) throw new AutomationError('task_not_found', '任务不存在。', 404)
+      return store.getTask(id)
+    })
+  }
+
+  async function deleteTask(id) {
+    return serialize(async () => {
+      const task = await withTask(id)
+      if (task.origin !== 'custom') throw new AutomationError('builtin_not_deletable', '内置任务只能暂停或休眠，不能删除。', 409)
+      await runningTask(task)
+      const deleted = await store.deleteTask(id)
+      if (!deleted) throw new AutomationError('task_not_found', '任务不存在。', 404)
+      return { deleted: true, id }
+    })
+  }
+
+  async function changeState(id, action) {
+    return serialize(async () => {
+      const task = await withTask(id)
+      if (action === 'activate') {
+        if (task.state === 'active') return task
+        return store.getTask((await store.setTaskState(id, 'active')).id)
+      }
+      if (action === 'pause') {
+        if (task.state === 'paused') return task
+        if (task.state !== 'active') throw new AutomationError('invalid_state', '只有运行中的任务可以暂停。', 409)
+        return store.getTask((await store.setTaskState(id, 'paused')).id)
+      }
+      if (action === 'hibernate') {
+        if (task.origin !== 'builtin') throw new AutomationError('invalid_origin', '自定义任务请直接删除；休眠只用于恢复内置默认。', 409)
+        await runningTask(task)
+        return store.getTask((await store.setTaskState(id, 'dormant')).id)
+      }
+      throw new AutomationError('invalid_action', '未知的任务动作。', 400)
+    })
+  }
+
+  async function copyTask(id) {
+    return serialize(async () => {
+      const task = await withTask(id)
+      if (task.origin !== 'builtin') throw new AutomationError('invalid_origin', '只有内置任务可以复制为自定义任务。', 409)
+      const record = await store.copyBuiltin(id)
+      if (record === undefined) throw new AutomationError('task_not_found', '任务不存在。', 404)
+      return store.getTask(record.id)
+    })
+  }
+
+  async function runTask(id) {
+    return serialize(async () => {
+      const task = await withTask(id)
+      if (scheduler === undefined) throw new AutomationError('scheduler_unavailable', '调度器不可用。', 503)
+      const result = await scheduler.runNow(task)
+      if (!result.ok) throw new AutomationError(result.code, result.message, result.code === 'scheduler_unavailable' ? 503 : 409, result.runId === undefined ? {} : { runId: result.runId })
+      return result.run
+    })
+  }
+
+  async function cancelRun(id) {
+    return serialize(async () => {
+      const run = await store.getRun(id)
+      if (run === undefined) throw new AutomationError('run_not_found', '运行记录不存在。', 404)
+      if (store.isActiveRun(run.status) !== true) throw new AutomationError('run_not_active', '该运行已经结束。', 409)
+      const live = runner?.cancelRun?.(id) === true
+      if (!live) {
+        await store.updateRun(id, {
+          status: 'canceled',
+          finishedAt: new Date(now()).toISOString(),
+          durationMs: Math.max(0, now() - Date.parse(run.queuedAt)),
+        })
+      }
+      return { canceling: true, id }
+    })
+  }
+
+  async function getRun(id) {
+    const run = await store.getRun(id)
+    if (run === undefined) throw new AutomationError('run_not_found', '运行记录不存在。', 404)
+    return {
+      ...store.publicRun(run),
+      attempts: await store.listAttemptsForRun(id),
+    }
+  }
+
+  async function listRuns(query = {}) {
+    const limit = runLimitOf(query.limit)
+    const before = runCursorOf(query.before)
+    const page = await store.listRunsPage({ limit, before })
+    if (page.invalidCursor) throw new AutomationError('invalid_cursor', '运行分页游标无效。', 400)
+    return {
+      runs: page.runs.map((run) => store.publicRun(run)),
+      nextBefore: page.nextBefore ?? null,
+    }
+  }
+
+  async function listNotifications(query = {}) {
+    let unreadOnly = false
+    if (query.unread !== undefined) {
+      if (query.unread === true || query.unread === '1' || query.unread === 'true') unreadOnly = true
+      else if (query.unread !== false && query.unread !== '0' && query.unread !== 'false') {
+        throw invalidQuery('通知 unread 参数无效。')
+      }
+    }
+    return {
+      notifications: await store.listNotifications({ unreadOnly, limit: 200 }),
+      unread: await store.unreadNotificationCount(),
+    }
+  }
+
+  async function markNotificationsRead(input) {
+    const parsed = parseStrict(NotificationsReadSchema, input, 'notifications/read')
+    return { changed: await store.markNotificationsRead(parsed) }
+  }
+
+  async function taskDetail(id) {
+    const task = await withTask(id)
+    const page = await store.listRunsPage({ limit: 20, taskId: id })
+    const runs = page.runs.map((run) => store.publicRun(run))
+    const notifications = await store.listNotifications({ taskId: id, limit: 200 })
+    return { task: store.decorateTask(task, page.runs), runs, notifications }
+  }
+
+  return {
+    serialize,
+    meta,
+    listTasks,
+    taskDetail,
+    createTask,
+    patchTask,
+    deleteTask,
+    changeState,
+    copyTask,
+    runTask,
+    cancelRun,
+    getRun,
+    listRuns,
+    listNotifications,
+    markNotificationsRead,
+    storageState: async () => {
+      try {
+        await store.open()
+        return { state: 'ready' }
+      } catch (error) {
+        return { state: 'unavailable', error: sanitizeMessage(String(error)) }
+      }
+    },
+  }
+}