@huakirax/dsh-plugin-pocket 0.0.0-stage → 0.1.0

package/src/settings-ops.js

@@ -0,0 +1,387 @@
+/**
+ * Desktop settings Host surfaces for the phone: models providers, plugins,
+ * schedules, and model API-key writes.
+ *
+ * Data shapes and Host call patterns follow deepseek-harness client modules
+ * (ui-settings-models, ui-plugin-manager, ui-schedule, settings-controller).
+ * Mobile nav (list → full-screen detail) follows the dsh-mobile panel pattern
+ * (Apache-2.0; see docs/THIRD_PARTY_NOTICES.md) without copying WebView UI.
+ */
+
+const str = (v) => typeof v === 'string' && v.length > 0
+const bad = (m) => Object.assign(new Error(m), { code: 'bad-request' })
+
+/** Conventional credential ref for a provider route (ui-settings-models deriveKeyRef). */
+export function deriveKeyRef(provider) {
+  return `${String(provider).toUpperCase().replace(/[^A-Z0-9]+/g, '_')}_API_KEY`
+}
+
+/** Walk a plain object by string path segments. */
+export function getPath(value, path) {
+  let cur = value
+  for (const key of path ?? []) {
+    if (cur === undefined || cur === null || typeof cur !== 'object') return undefined
+    cur = cur[key]
+  }
+  return cur
+}
+
+/** Join configurable directory with live routes (ui-settings-models joinProviderDirectory). */
+export function joinProviderDirectory(registered, directory) {
+  const active = new Set((registered ?? []).map((p) => p.id))
+  const rows = (directory ?? []).map((entry) => ({
+    provider: entry.provider,
+    displayName: entry.displayName ?? entry.provider,
+    settingsNs: entry.settingsNs ?? '',
+    settingsPath: [...(entry.settingsPath ?? [])],
+    active: active.has(entry.provider),
+    ...(entry.declared === undefined ? {} : { declared: entry.declared }),
+    ...(entry.error === undefined ? {} : { error: entry.error }),
+  }))
+  const rank = (id) => (id === 'deepseek-account' ? 0 : id === 'deepseek-official' ? 1 : 2)
+  return rows.sort((a, b) => rank(a.provider) - rank(b.provider))
+}
+
+function resolveSchemaNode(schema, raw) {
+  const uid = raw && typeof raw === 'object' ? raw.uid : raw
+  return uid !== undefined && schema?.refs ? schema.refs[uid] : raw
+}
+
+/** Read the Host's serialized Schemastery graph without loading client services. */
+function schemaNodeAtPath(schema, path) {
+  const resolve = (raw) => resolveSchemaNode(schema, raw)
+  let node = resolve(schema)
+  for (const key of path) {
+    if (node?.type === 'object') node = resolve(node.dict?.[key])
+    else if (node?.type === 'dict' || node?.type === 'array') node = resolve(node.inner)
+    else return undefined
+  }
+  return node
+}
+
+function protocolChoices(namespace) {
+  const schema = namespace?.schema
+  const node = schemaNodeAtPath(schema, ['providers', '\u0000probe', 'api'])
+  if (node?.type !== 'union' || !Array.isArray(node.list)) return []
+  return node.list.map((raw) => resolveSchemaNode(schema, raw)?.value)
+    .filter((value) => typeof value === 'string')
+}
+
+function hasPath(value, path) {
+  if (path.length === 0) return value !== undefined
+  const parent = getPath(value, path.slice(0, -1))
+  return parent !== null && typeof parent === 'object' && Object.hasOwn(parent, path.at(-1))
+}
+
+function projectCredentialInfo(info) {
+  if (!info || typeof info !== 'object') return { configured: false, writable: false }
+  return {
+    configured: Boolean(info.configured),
+    ...(info.source === undefined ? {} : { source: info.source }),
+    writable: Boolean(info.writable),
+  }
+}
+
+function namespaceView(descriptor) {
+  return {
+    ns: descriptor.ns,
+    revision: descriptor.revision,
+    value: descriptor.value,
+    user: descriptor.user,
+    base: descriptor.base,
+    schema: descriptor.schema,
+  }
+}
+
+/**
+ * Models settings ops over llm + settings + credentials Host services.
+ * Session model picker stays on existing models.catalog / models.select.
+ */
+export function modelsSettingsOps({ llm, settings, settingsController, credentials }) {
+  const describeSettings = () => {
+    if (settingsController?.describe) return settingsController.describe()
+    if (!settings?.describe) throw Object.assign(new Error('settings unavailable'), { code: 'unavailable' })
+    const raw = settings.describe({ redactSecrets: true })
+    return {
+      writable: settings.writable !== false,
+      hasDocument: true,
+      namespaces: (Array.isArray(raw) ? raw : []).map(namespaceView),
+    }
+  }
+
+  const describeCreds = async (refs) => {
+    if (!credentials?.describe) return { values: {}, error: refs.length ? 'credentials unavailable' : null }
+    try {
+      const entries = await Promise.all(refs.map(async (ref) => [
+        ref, projectCredentialInfo(await credentials.describe(ref)),
+      ]))
+      return { values: Object.fromEntries(entries), error: null }
+    } catch {
+      // Credential state enriches the page; an unavailable backend must not hide settings.
+      return { values: {}, error: 'credentials unavailable' }
+    }
+  }
+
+  return {
+    'models.providers': async () => {
+      if (!llm?.listProviders || !llm?.listConfigurableProviders) {
+        throw Object.assign(new Error('llm service unavailable'), { code: 'unavailable' })
+      }
+      const registered = llm.listProviders()
+      const directory = llm.listConfigurableProviders()
+      const providers = joinProviderDirectory(registered, directory)
+      const described = describeSettings()
+      const namespaces = new Map((described.namespaces ?? []).map((n) => [n.ns, n]))
+      const rows = providers.filter((entry) => namespaces.has(entry.settingsNs)).map((entry) => {
+        const ns = namespaces.get(entry.settingsNs)
+        const profile = getPath(ns.value, entry.settingsPath)
+        const configured = entry.settingsPath.length === 0 || profile !== undefined
+        const apiKeyEnv = entry.provider !== 'deepseek-account' && str(profile?.apiKeyEnv)
+          ? profile.apiKeyEnv
+          : undefined
+        return {
+          ...entry,
+          configured,
+          editable: described.writable !== false,
+          removable: entry.settingsPath.length > 0
+            && hasPath(ns.user, entry.settingsPath) && !hasPath(ns.base, entry.settingsPath),
+          apiKeyEnv,
+          profile: profile && typeof profile === 'object' ? profile : undefined,
+        }
+      })
+      const account = rows.find((row) => row.provider === 'deepseek-account')
+      if (account) {
+        try {
+          account.accountAvailable = account.active && (await llm.listModels(account.provider)).length > 0
+        } catch {
+          account.accountAvailable = false
+        }
+      }
+      const refs = [...new Set(rows.filter((row) => row.provider !== 'deepseek-account')
+        .map((row) => row.apiKeyEnv ?? deriveKeyRef(row.provider)))]
+      const { values: credentialsMap, error: credentialError } = await describeCreds(refs)
+      return {
+        writable: described.writable !== false && typeof settingsController?.mutate === 'function',
+        namespaces: described.namespaces ?? [],
+        protocols: protocolChoices(namespaces.get('llm-pi-ai')),
+        credentialError,
+        rows: rows.filter((row) => row.provider !== 'deepseek-account' || row.accountAvailable).map((row) => ({
+          ...row,
+          ...(row.provider === 'deepseek-account' ? {} : row.apiKeyEnv
+            ? { credential: credentialsMap[row.apiKeyEnv] }
+            : { derivedCredential: credentialsMap[deriveKeyRef(row.provider)] }),
+        })),
+      }
+    },
+
+    'models.providerGet': async (a) => {
+      if (!str(a.provider)) throw bad('provider required')
+      const listed = await modelsSettingsOps({ llm, settings, settingsController, credentials })['models.providers']()
+      const row = listed.rows.find((r) => r.provider === a.provider)
+      if (!row) throw Object.assign(new Error(`unknown provider: ${a.provider}`), { code: 'not-found' })
+      const namespace = listed.namespaces.find((ns) => ns.ns === row.settingsNs)
+      const modelsPath = [...row.settingsPath, 'models']
+      let catalog = []
+      let catalogError = null
+      if (row.active) {
+        try {
+          catalog = await llm.listModels(row.provider)
+        } catch {
+          catalogError = 'model catalog unavailable'
+        }
+      }
+      return {
+        writable: listed.writable, provider: row, namespace, protocols: listed.protocols,
+        catalog, catalogError,
+        inheritedModels: getPath(namespace?.base, modelsPath)
+          ?? schemaNodeAtPath(namespace?.schema, modelsPath)?.meta?.default,
+      }
+    },
+
+    'models.settingsMutate': async (a) => {
+      if (!str(a.ns) || !Array.isArray(a.ops)) throw bad('ns and ops required')
+      if (!Number.isSafeInteger(a.expectedRevision) || a.expectedRevision < 0) throw bad('expectedRevision required')
+      const controller = settingsController
+      if (controller?.mutate) {
+        return controller.mutate(a.ns, a.ops, a.expectedRevision)
+      }
+      throw Object.assign(new Error('safe settings controller unavailable'), { code: 'unavailable' })
+    },
+
+    'models.discover': async (a, signal) => {
+      if (!str(a.settingsNs)) throw bad('settingsNs required')
+      if (!llm?.discoverModels) throw Object.assign(new Error('llm discovery unavailable'), { code: 'unavailable' })
+      const models = await llm.discoverModels(a.settingsNs, a.request ?? {}, signal)
+      return { models }
+    },
+  }
+}
+
+/**
+ * Keep the official manager's business outcomes intact: an acknowledged RPC can
+ * still require restart, be overridden, or fail. Only advertise live methods.
+ */
+export function pluginsOps(pluginManager) {
+  if (!pluginManager) throw bad('pluginManager required')
+  const ops = {
+    'plugins.list': async () => {
+      const [bundles, plugins] = await Promise.all([
+        pluginManager.listBundles(),
+        pluginManager.listPlugins(),
+      ])
+      return {
+        bundles: bundles ?? [],
+        plugins: plugins ?? [],
+        managementAvailable: true,
+      }
+    },
+    'plugins.setEnabled': async (a) => {
+      if (typeof a.enabled !== 'boolean') throw bad('enabled boolean required')
+      if (str(a.bundle) && (str(a.id) || str(a.entryId))) throw bad('choose bundle or id, not both')
+      if (str(a.id) && str(a.entryId) && a.id !== a.entryId) throw bad('conflicting plugin ids')
+      if (str(a.bundle)) {
+        return pluginManager.setBundleEnabled(a.bundle, a.enabled)
+      }
+      if (str(a.id) || str(a.entryId)) {
+        return pluginManager.setPluginEnabled(a.id ?? a.entryId, a.enabled)
+      }
+      throw bad('bundle or id required')
+    },
+  }
+  const methods = [
+    ['plugins.install', 'installBundle', 'spec'],
+    ['plugins.uninstall', 'removeBundle', 'bundle'],
+    ['plugins.inspect', 'inspect', 'spec'],
+    ['plugins.cancelInstall', 'cancelInstall', 'requestId'],
+    ['plugins.waitForInstall', 'waitForInstall', 'requestId'],
+  ]
+  for (const [op, method, field] of methods) {
+    if (typeof pluginManager[method] !== 'function') continue
+    ops[op] = async (a, signal) => {
+      if (!str(a[field]) || !a[field].trim()) throw bad(`${field} required`)
+      if (op === 'plugins.inspect') return pluginManager.inspect(a.spec.trim(), a.options, signal)
+      if (op === 'plugins.install') return pluginManager.installBundle(a.spec.trim(), a.options)
+      return pluginManager[method](a[field])
+    }
+  }
+  if (typeof pluginManager.registries === 'function') {
+    ops['plugins.registries'] = () => pluginManager.registries()
+  }
+  return ops
+}
+
+/** Use the official redacted settings controller, including revision conflicts. */
+export function pluginSettingsOps(settingsController) {
+  return {
+    'plugins.settingsDescribe': () => settingsController.describe(),
+    'plugins.settingsMutate': async (a) => {
+      if (!str(a.ns) || !Array.isArray(a.ops)) throw bad('ns and ops required')
+      if (!Number.isSafeInteger(a.expectedRevision) || a.expectedRevision < 0) {
+        throw bad('expectedRevision required')
+      }
+      return settingsController.mutate(a.ns, a.ops, a.expectedRevision)
+    },
+  }
+}
+
+/**
+ * Built-in plugin inventory (settings → 内置插件), read-only roster plus enable
+ * when pluginManager can address the row.
+ */
+export function pluginInventoryOps(pluginInventory, pluginManager) {
+  return {
+    'plugins.inventory': async () => {
+      if (pluginInventory?.list) {
+        const snap = await pluginInventory.list()
+        return snap
+      }
+      if (pluginManager?.listPlugins) {
+        const plugins = await pluginManager.listPlugins()
+        return { entries: plugins, managementAvailable: true }
+      }
+      throw Object.assign(new Error('plugin inventory unavailable'), { code: 'unavailable' })
+    },
+  }
+}
+
+/**
+ * Schedule / automation tasks. create() is Host in-process (not a Remote);
+ * catalog/list/update/delete/history are Remotes. Desktop has no pause toggle —
+ * inactive means ended after delivery.
+ */
+export function scheduleOps(schedule) {
+  if (!schedule) throw bad('schedule service required')
+  return {
+    'schedule.catalog': () => schedule.catalog(),
+    'schedule.list': async (a) => {
+      if (!str(a.sessionId)) throw bad('sessionId required')
+      return schedule.list({ sessionId: a.sessionId })
+    },
+    'schedule.create': async (a, signal) => {
+      if (!str(a.sessionId)) throw bad('sessionId required')
+      if (!str(a.title) || !str(a.prompt)) throw bad('title and prompt required')
+      if (typeof schedule.create !== 'function') {
+        throw Object.assign(new Error('schedule.create unavailable'), { code: 'unavailable' })
+      }
+      const request = {
+        title: a.title,
+        prompt: a.prompt,
+        ...(a.after_seconds !== undefined ? { after_seconds: a.after_seconds } : {}),
+        ...(a.at !== undefined ? { at: a.at } : {}),
+        ...(a.every_seconds !== undefined ? { every_seconds: a.every_seconds } : {}),
+        ...(a.daily !== undefined ? { daily: a.daily } : {}),
+        ...(a.weekly !== undefined ? { weekly: a.weekly } : {}),
+        ...(a.cron !== undefined ? { cron: a.cron } : {}),
+      }
+      return schedule.create(a.sessionId, request, signal)
+    },
+    'schedule.update': async (a, signal) => {
+      if (!str(a.sessionId) || !str(a.id)) throw bad('sessionId and id required')
+      if (!a.expected || typeof a.expected !== 'object') throw bad('expected record required')
+      return schedule.update({
+        sessionId: a.sessionId,
+        id: a.id,
+        expected: a.expected,
+        ...(a.title !== undefined ? { title: a.title } : {}),
+        ...(a.prompt !== undefined ? { prompt: a.prompt } : {}),
+        ...(a.change !== undefined ? { change: a.change } : {}),
+      }, signal)
+    },
+    'schedule.delete': async (a, signal) => {
+      if (!str(a.sessionId) || !str(a.id)) throw bad('sessionId and id required')
+      return schedule.delete({ sessionId: a.sessionId, id: a.id }, signal)
+    },
+    'schedule.history': async (a) => {
+      if (!str(a.sessionId) || !str(a.id)) throw bad('sessionId and id required')
+      const limit = Number.isSafeInteger(a.limit) ? a.limit : 20
+      return schedule.history({
+        sessionId: a.sessionId,
+        id: a.id,
+        limit,
+        ...(str(a.before) ? { before: a.before } : {}),
+      })
+    },
+  }
+}
+
+/** Credential operations return only metadata; Host credential records stay private. */
+export function credentialsOps({ credentials }) {
+  if (!credentials) throw bad('credentials service required')
+
+  return {
+    'credentials.describe': async (a) => {
+      if (!str(a.ref)) throw bad('ref required')
+      return { ref: a.ref, ...projectCredentialInfo(await credentials.describe(a.ref)) }
+    },
+    'credentials.set': async (a) => {
+      if (!str(a.ref) || !str(a.value)) throw bad('ref and non-empty value required')
+      await credentials.set(a.ref, a.value)
+      return { ref: a.ref, ...projectCredentialInfo(await credentials.describe(a.ref)) }
+    },
+    'credentials.unset': async (a) => {
+      if (!str(a.ref)) throw bad('ref required')
+      await credentials.unset(a.ref)
+      return { ref: a.ref, ...projectCredentialInfo(await credentials.describe(a.ref)) }
+    },
+  }
+}

package/src/task-events.js

@@ -0,0 +1,77 @@
+/**
+ * Adapted from saya-ch/dsh-mobile (Apache-2.0)
+ * Host-side task-completion fan-out for phone notifications.
+ *
+ * Watches the public `session/event` bus for completed root turns and hands
+ * them to a sink (normally the pocket WS server). Phones render the text
+ * locally — only opaque session and turn ids cross this boundary.
+ */
+
+export const TASK_EVENT_DEBOUNCE_MS = 1_000
+
+function turnNumber(value) {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0
+}
+
+function turnData(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return { turn: 0, completed: false }
+  }
+  const reason = value.reason
+  const completed = typeof reason === 'string'
+    ? reason === 'completed'
+    : reason !== null && typeof reason === 'object' && reason.kind === 'completed'
+  return { turn: turnNumber(value.turn), completed }
+}
+
+/**
+ * Subscribe to completed root turns. Subagent turns are skipped so one task
+ * announces once, and rapid turn boundaries collapse into a single event.
+ * @returns {() => void} disposer that also drops pending debounces
+ */
+export function watchTaskCompletions(ctx, options) {
+  const debounceMs = options.debounceMs ?? TASK_EVENT_DEBOUNCE_MS
+  const pending = new Map()
+  const disposeListener = ctx.on('session/event', (session, event) => {
+    if (event?.type !== 'turn/end') return
+    const { turn, completed } = turnData(event.data)
+    if (!completed) return
+    if (session?.header?.parentSession !== undefined && session?.header?.parentSession !== null) return
+    const sessionId = String(session.id)
+    options.log?.('task-completed-observed', { sessionId, turn })
+    const previous = pending.get(sessionId)
+    if (previous !== undefined) clearTimeout(previous)
+    pending.set(sessionId, setTimeout(() => {
+      pending.delete(sessionId)
+      options.log?.('task-completed-announced', { sessionId, turn })
+      options.onTaskCompleted(Object.freeze({ sessionId, turn, kind: 'done' }))
+    }, debounceMs))
+  })
+  return () => {
+    disposeListener()
+    for (const timer of pending.values()) clearTimeout(timer)
+    pending.clear()
+  }
+}
+
+/** One subscription feeding every sink; normally a single pocket server. */
+export class TaskEventHub {
+  constructor() {
+    this.sinks = new Set()
+  }
+
+  add(sink) {
+    this.sinks.add(sink)
+    return () => { this.sinks.delete(sink) }
+  }
+
+  broadcast(event) {
+    for (const sink of [...this.sinks]) {
+      try { sink.broadcastTaskEvent(event) } catch { /* A failing sink must not break siblings. */ }
+    }
+  }
+
+  get size() {
+    return this.sinks.size
+  }
+}

package/src/task-fallback.js

@@ -0,0 +1,177 @@
+/**
+ * Adapted from saya-ch/dsh-mobile (Apache-2.0) task-notify fallbacks.
+ * Host-side completion inference when `session/event` turn/end is missing:
+ * 90s quiet after activity, or busy→idle with 10s grace.
+ */
+
+export const TASK_NOTIFY_QUIET_MS = 90_000
+export const TASK_NOTIFY_GRACE_MS = 10_000
+export const TASK_NOTIFY_MIN_BUSY_MS = 20_000
+export const TASK_NOTIFY_STALE_MS = 30 * 60_000
+
+/**
+ * Per-session fallback tracker driven by api-session status/activity.
+ * Emits the same minimal {sessionId, turn, kind:'done'} shape as turn/end.
+ */
+export class TaskFallbackTracker {
+  /**
+   * @param {{
+   *   quietMs?: number,
+   *   graceMs?: number,
+   *   minBusyMs?: number,
+   *   now?: () => number,
+   *   onTaskCompleted: (event: {sessionId: string, turn: number, kind: 'done'}) => void,
+   *   isRootSession?: (sessionId: string) => boolean,
+   *   hasPendingQuestion?: (sessionId: string) => boolean,
+   * }} options
+   */
+  constructor(options) {
+    this.quietMs = options.quietMs ?? TASK_NOTIFY_QUIET_MS
+    this.graceMs = options.graceMs ?? TASK_NOTIFY_GRACE_MS
+    this.minBusyMs = options.minBusyMs ?? TASK_NOTIFY_MIN_BUSY_MS
+    this.now = options.now ?? Date.now
+    this.onTaskCompleted = options.onTaskCompleted
+    this.isRootSession = options.isRootSession ?? (() => true)
+    this.hasPendingQuestion = options.hasPendingQuestion ?? (() => false)
+    /** @type {Map<string, {
+     *   lastActivityAt?: number,
+     *   notifiedDoneAt?: number,
+     *   wasBusy: boolean,
+     *   busySince?: number,
+     *   idleAnchoredAt?: number,
+     *   timer?: ReturnType<typeof setTimeout>,
+     * }>} */
+    this.states = new Map()
+  }
+
+  state(sessionId) {
+    let s = this.states.get(sessionId)
+    if (!s) {
+      s = { wasBusy: false }
+      this.states.set(sessionId, s)
+    }
+    return s
+  }
+
+  markActivity(sessionId, at = this.now()) {
+    if (!this.isRootSession(sessionId)) return
+    const s = this.state(sessionId)
+    s.lastActivityAt = at
+    if (s.notifiedDoneAt !== undefined && s.notifiedDoneAt <= at) s.notifiedDoneAt = undefined
+    this.schedule(sessionId)
+  }
+
+  /** Suppress fallback announce after an exact turn/end completion for the same session. */
+  markAnnounced(sessionId, at = this.now()) {
+    const s = this.state(sessionId)
+    s.notifiedDoneAt = at
+    s.idleAnchoredAt = undefined
+    if (s.timer !== undefined) {
+      clearTimeout(s.timer)
+      s.timer = undefined
+    }
+  }
+
+  onStatus(sessionId, running) {
+    if (!this.isRootSession(sessionId)) return
+    const s = this.state(sessionId)
+    const now = this.now()
+    if (!s.wasBusy && running) s.busySince = now
+    if (s.wasBusy && !running) {
+      const busyFor = s.busySince === undefined ? 0 : now - s.busySince
+      s.busySince = undefined
+      if (!this.hasPendingQuestion(sessionId) && busyFor >= this.minBusyMs) {
+        s.idleAnchoredAt = undefined
+        this.announce(sessionId, s, now)
+        s.wasBusy = false
+        return
+      }
+      s.idleAnchoredAt = now
+    }
+    s.wasBusy = running
+    if (running) s.idleAnchoredAt = undefined
+    this.schedule(sessionId)
+  }
+
+  /** Drop tracking when a session is removed. */
+  forget(sessionId) {
+    const s = this.states.get(sessionId)
+    if (!s) return
+    if (s.timer !== undefined) clearTimeout(s.timer)
+    this.states.delete(sessionId)
+  }
+
+  dispose() {
+    for (const s of this.states.values()) {
+      if (s.timer !== undefined) clearTimeout(s.timer)
+    }
+    this.states.clear()
+  }
+
+  schedule(sessionId) {
+    const s = this.state(sessionId)
+    if (s.timer !== undefined) {
+      clearTimeout(s.timer)
+      s.timer = undefined
+    }
+    const delay = this.nextDelayMs(sessionId)
+    if (delay === undefined) return
+    s.timer = setTimeout(() => {
+      s.timer = undefined
+      this.evaluate(sessionId)
+    }, delay)
+  }
+
+  nextDelayMs(sessionId) {
+    const s = this.states.get(sessionId)
+    if (!s || s.wasBusy || this.hasPendingQuestion(sessionId)) return undefined
+    const now = this.now()
+    const delays = []
+    if (s.idleAnchoredAt !== undefined) {
+      delays.push(Math.max(0, this.graceMs - (now - s.idleAnchoredAt)))
+    }
+    if (s.lastActivityAt !== undefined) {
+      const since = now - s.lastActivityAt
+      if (since > TASK_NOTIFY_STALE_MS) return undefined
+      if (s.notifiedDoneAt !== undefined && s.notifiedDoneAt >= s.lastActivityAt) {
+        /* already announced for this activity window */
+      } else {
+        delays.push(Math.max(0, this.quietMs - since))
+      }
+    }
+    if (delays.length === 0) return undefined
+    return Math.min(...delays)
+  }
+
+  evaluate(sessionId) {
+    if (!this.isRootSession(sessionId)) return
+    const s = this.state(sessionId)
+    const now = this.now()
+    if (s.wasBusy || this.hasPendingQuestion(sessionId)) return
+    if (s.idleAnchoredAt !== undefined) {
+      if (now - s.idleAnchoredAt < this.graceMs) {
+        this.schedule(sessionId)
+        return
+      }
+      s.idleAnchoredAt = undefined
+      this.announce(sessionId, s, now)
+      return
+    }
+    if (s.lastActivityAt === undefined) return
+    if (now - s.lastActivityAt < this.quietMs) {
+      this.schedule(sessionId)
+      return
+    }
+    if (now - s.lastActivityAt > TASK_NOTIFY_STALE_MS) {
+      s.lastActivityAt = undefined
+      return
+    }
+    if (s.notifiedDoneAt !== undefined && s.notifiedDoneAt >= s.lastActivityAt) return
+    this.announce(sessionId, s, now)
+  }
+
+  announce(sessionId, s, now) {
+    s.notifiedDoneAt = now
+    this.onTaskCompleted(Object.freeze({ sessionId, turn: 0, kind: 'done' }))
+  }
+}

package/src/token.js

@@ -0,0 +1,18 @@
+import { randomBytes } from 'node:crypto'
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Load the persistent bearer token, creating a 32-byte one on first run (0600). */
+export function loadOrCreateToken(dataDir, fixed) {
+  const path = join(dataDir, 'token')
+  if (typeof fixed === 'string' && fixed.length > 0) return { token: fixed, created: false, path: '(config)' }
+  if (existsSync(path)) {
+    const token = readFileSync(path, 'utf8').trim()
+    if (token.length >= 16) return { token, created: false, path }
+  }
+  mkdirSync(dataDir, { recursive: true, mode: 0o700 })
+  const token = randomBytes(32).toString('base64url')
+  writeFileSync(path, token + '\n', { mode: 0o600 })
+  chmodSync(path, 0o600)
+  return { token, created: true, path }
+}