dsh-device-fleet 0.1.0-dev.2 → 0.1.0-dev.20

package/src/host/room-service.js

@@ -0,0 +1,429 @@
+// Room logic layer (ADR-0002/0005/0006/0011/0021), with local participants for
+// simulation inside one DSH. The Host session log carries the authoritative
+// room events; participant agents are real local DSH sessions woken with an
+// addressed message, so addressing/wake/visibility and board handoff can be
+// exercised before the remote transport and the client UI exist.
+import { randomUUID } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+const MAX_MESSAGE_CHARS = 20_000
+const STATE_VERSION = 1
+
+const DEFAULT_POLICY = Object.freeze({
+  invite: 'members',
+  join: 'auto',
+  maxMembers: 8,
+  boardWrite: 'members',
+  remove: 'members',
+})
+
+function hostMemberId(sessionId) {
+  return `host:${sessionId}`
+}
+
+function localMemberId(sessionId) {
+  return `local:${sessionId}`
+}
+
+export class RoomService {
+  /**
+   * @param {object} options
+   * @param {object} options.sessionController ctx.sessionController
+   * @param {(input: object) => object} [options.createUserMessage] dsh-llm helper
+   * @param {(now?: number) => number} [options.now]
+   * @param {string} [options.stateFile] JSON file used to rehydrate rooms after a reload
+   */
+  constructor({ sessionController, createUserMessage = null, now = Date.now, stateFile = null } = {}) {
+    this.sessionController = sessionController
+    this.createUserMessage = createUserMessage
+    this.now = now
+    this.stateFile = stateFile
+    /** @type {Map<string, any>} */
+    this.rooms = new Map()
+    if (stateFile) this.load()
+  }
+
+  /** Rehydrate active rooms from the persisted snapshot (agents resolve lazily). */
+  load() {
+    if (!this.stateFile || !existsSync(this.stateFile)) return
+    try {
+      const data = JSON.parse(readFileSync(this.stateFile, 'utf8'))
+      if (!data || data.version !== STATE_VERSION || !Array.isArray(data.rooms)) return
+      for (const stored of data.rooms) {
+        if (!stored || typeof stored.roomId !== 'string' || !Array.isArray(stored.members)) continue
+        const members = new Map()
+        for (const member of stored.members) {
+          if (!member || typeof member.memberId !== 'string') continue
+          members.set(member.memberId, { ...member, agent: undefined })
+        }
+        if (!members.has(hostMemberId(stored.roomId))) continue
+        this.rooms.set(stored.roomId, {
+          roomId: stored.roomId,
+          createdAt: Number.isFinite(stored.createdAt) ? stored.createdAt : this.now(),
+          hostSessionId: typeof stored.hostSessionId === 'string' ? stored.hostSessionId : stored.roomId,
+          policy: { ...DEFAULT_POLICY, ...(stored.policy ?? {}) },
+          members,
+          messages: Array.isArray(stored.messages) ? stored.messages : [],
+          tasks: new Map((Array.isArray(stored.tasks) ? stored.tasks : []).map((task) => [task.id, task])),
+          closed: false,
+        })
+      }
+    } catch {
+      /* a corrupt snapshot is ignored; the host session log stays authoritative */
+    }
+  }
+
+  persist() {
+    if (!this.stateFile) return
+    try {
+      const snapshot = {
+        version: STATE_VERSION,
+        savedAt: this.now(),
+        rooms: [...this.rooms.values()].map((room) => ({
+          roomId: room.roomId,
+          createdAt: room.createdAt,
+          hostSessionId: room.hostSessionId,
+          policy: room.policy,
+          members: [...room.members.values()].map(({ agent, ...rest }) => rest),
+          messages: room.messages,
+          tasks: [...room.tasks.values()],
+        })),
+      }
+      mkdirSync(dirname(this.stateFile), { recursive: true })
+      const temporary = `${this.stateFile}.tmp`
+      writeFileSync(temporary, JSON.stringify(snapshot, null, 2), 'utf8')
+      renameSync(temporary, this.stateFile)
+    } catch {
+      /* persistence is best effort; the session log remains authoritative */
+    }
+  }
+
+  /** Resolve a live agent for a persisted member on demand. */
+  async ensureAgent(member) {
+    if (member?.agent) return true
+    if (!member?.sessionId || !this.sessionController?.resolveAgent) return false
+    try {
+      const resolved = await this.sessionController.resolveAgent(member.sessionId)
+      if (!resolved?.agent) return false
+      member.agent = resolved.agent
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  async upgradeHost({ agent, policy = {} } = {}) {
+    if (!agent?.session?.id) throw Object.assign(new Error('room upgrade needs the calling agent session'), { code: 'bad-request' })
+    const sessionId = agent.session.id
+    const existing = this.rooms.get(sessionId)
+    if (existing) return this.summary(existing)
+    const memberId = hostMemberId(sessionId)
+    const room = {
+      roomId: sessionId,
+      createdAt: this.now(),
+      hostSessionId: sessionId,
+      policy: { ...DEFAULT_POLICY, ...policy },
+      members: new Map(),
+      messages: [],
+      tasks: new Map(),
+      closed: false,
+    }
+    room.members.set(memberId, {
+      memberId,
+      role: 'host',
+      kind: 'local',
+      sessionId,
+      name: agent.session.header?.title ?? 'host',
+      agent,
+    })
+    this.rooms.set(sessionId, room)
+    await this.append(room, 'room/created', { roomId: room.roomId, policy: room.policy, hostMemberId: memberId })
+    return this.summary(room)
+  }
+
+  async addLocalParticipant({ roomId, name = 'worker', agentPreset, cwd } = {}) {
+    const room = this.requireRoom(roomId)
+    if (room.members.size >= room.policy.maxMembers) {
+      throw Object.assign(new Error(`room member limit reached (${room.policy.maxMembers})`), { code: 'room-full' })
+    }
+    if (!this.sessionController?.create) {
+      throw Object.assign(new Error('participant sessions are unavailable'), { code: 'unsupported' })
+    }
+    const created = await this.sessionController.create({
+      ...(cwd ? { cwd } : {}),
+      ...(agentPreset ? { agentPreset } : {}),
+    })
+    const sessionId = created?.sessionId
+    if (!sessionId) throw Object.assign(new Error('could not create the participant session'), { code: 'room-participant-failed' })
+    const resolved = await this.sessionController.resolveAgent(sessionId)
+    if (!resolved?.agent) throw Object.assign(new Error('participant agent could not be resolved'), { code: 'room-participant-failed' })
+    const memberId = localMemberId(sessionId)
+    const member = { memberId, role: 'participant', kind: 'local', sessionId, name, agent: resolved.agent }
+    room.members.set(memberId, member)
+    await this.append(room, 'room/member', {
+      roomId: room.roomId,
+      action: 'added',
+      memberId,
+      role: 'participant',
+      name,
+      sessionId,
+    })
+    return this.memberSummary(member)
+  }
+
+  async removeMember({ roomId, memberId, reason = 'removed' } = {}) {
+    const room = this.requireRoom(roomId)
+    const member = room.members.get(memberId)
+    if (!member) throw Object.assign(new Error(`unknown member: ${String(memberId)}`), { code: 'unknown-member' })
+    if (member.role === 'host') throw Object.assign(new Error('the host cannot be removed; close the room instead'), { code: 'forbidden' })
+    room.members.delete(memberId)
+    await this.append(room, 'room/member', { roomId: room.roomId, action: 'removed', memberId, reason })
+    return { roomId: room.roomId, memberId }
+  }
+
+  /**
+   * Send one addressed message. The Host appends it to the canonical log and
+   * wakes only the addressed local members (never the sender).
+   */
+  async send({ roomId, from, to, text } = {}) {
+    const room = this.requireRoom(roomId)
+    const body = typeof text === 'string' ? text.trim() : ''
+    if (body === '') throw Object.assign(new Error('room message needs text'), { code: 'bad-request' })
+    if (body.length > MAX_MESSAGE_CHARS) throw Object.assign(new Error('room message is too long'), { code: 'bad-request' })
+    const recipients = Array.isArray(to) ? to.filter((id) => typeof id === 'string') : []
+    if (recipients.length === 0) throw Object.assign(new Error('room message needs at least one recipient'), { code: 'bad-request' })
+    for (const memberId of recipients) {
+      if (!room.members.has(memberId)) throw Object.assign(new Error(`unknown member: ${memberId}`), { code: 'unknown-member' })
+    }
+    const sender = this.resolveSender(room, from)
+    const message = {
+      id: randomUUID(),
+      roomId: room.roomId,
+      from: sender,
+      to: recipients,
+      text: body,
+      createdAt: this.now(),
+    }
+    room.messages.push(message)
+    await this.append(room, 'room/message', {
+      roomId: room.roomId,
+      messageId: message.id,
+      from: sender,
+      to: recipients,
+      text: body,
+    })
+    const woken = []
+    for (const memberId of recipients) {
+      if (sender.memberId === memberId) continue
+      const member = room.members.get(memberId)
+      if (await this.wake(room, member, message)) woken.push(memberId)
+    }
+    return { messageId: message.id, to: recipients, woken }
+  }
+
+  resolveSender(room, from) {
+    if (from && typeof from === 'object') {
+      if (typeof from.memberId === 'string') {
+        const member = room.members.get(from.memberId)
+        if (!member) throw Object.assign(new Error(`unknown sender member: ${from.memberId}`), { code: 'unknown-member' })
+        return { kind: 'agent', memberId: member.memberId, name: member.name ?? 'agent' }
+      }
+      if (typeof from.sessionId === 'string') {
+        for (const member of room.members.values()) {
+          if (member.sessionId === from.sessionId) {
+            return { kind: 'agent', memberId: member.memberId, name: member.name ?? 'agent' }
+          }
+        }
+        throw Object.assign(new Error(`sender session is not a room member: ${from.sessionId}`), { code: 'unknown-member' })
+      }
+      if (from.kind === 'user') return { kind: 'user', name: 'user' }
+    }
+    return { kind: 'user', name: 'user' }
+  }
+
+  /** Wake one local participant by injecting the addressed message. */
+  async wake(room, member, message) {
+    if (!member || typeof this.createUserMessage !== 'function') return false
+    if (!(await this.ensureAgent(member))) return false
+    if (typeof member.agent?.followup !== 'function') return false
+    const senderLabel = message.from.kind === 'user' ? 'user' : (message.from.name ?? 'agent')
+    // The host is the user's own session: deliver a plain attributed line into
+    // the normal Chat stream instead of an agent-to-agent reply instruction.
+    const text =
+      member.role === 'host'
+        ? `[Room] ${senderLabel}: ${message.text}`
+        : [
+            `[Fleet Room ${room.roomId}] ${senderLabel} → you:`,
+            message.text,
+            '',
+            `Reply with room_send (roomId="${room.roomId}", to=["${message.from.memberId ?? 'host'}"]) when you have an answer.`,
+          ].join('\n')
+    const userMessage = this.createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } })
+    try {
+      member.agent.followup(userMessage)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  async append(room, type, data) {
+    const host = room.members.get(hostMemberId(room.hostSessionId))
+    const session = host?.agent?.session
+    if (session?.append) {
+      try {
+        await session.append(type, data)
+      } catch {
+        /* the snapshot below still records the room state */
+      }
+    }
+    this.persist()
+  }
+
+  // --------------------------------------------------------------- room tasks
+
+  async addTask({ roomId, title, owner, dependsOn = [], description = '' } = {}) {
+    const room = this.requireRoom(roomId)
+    if (typeof title !== 'string' || title.trim() === '') throw Object.assign(new Error('task needs a title'), { code: 'bad-request' })
+    const ownerMember = room.members.get(owner)
+    if (!ownerMember) throw Object.assign(new Error(`unknown task owner: ${String(owner)}`), { code: 'unknown-member' })
+    const id = randomUUID()
+    const task = {
+      id,
+      roomId: room.roomId,
+      title: title.trim(),
+      description,
+      owner,
+      status: 'pending',
+      dependsOn: Array.isArray(dependsOn) ? dependsOn : [],
+      readyNotified: false,
+      createdAt: this.now(),
+      updatedAt: this.now(),
+    }
+    room.tasks.set(id, task)
+    await this.append(room, 'room/task', { roomId: room.roomId, action: 'added', task })
+    return task
+  }
+
+  async updateTask({ roomId, id, status, note } = {}) {
+    const room = this.requireRoom(roomId)
+    const task = room.tasks.get(id)
+    if (!task) throw Object.assign(new Error(`unknown task: ${String(id)}`), { code: 'unknown-task' })
+    const allowed = ['pending', 'running', 'done', 'blocked']
+    if (status !== undefined && !allowed.includes(status)) {
+      throw Object.assign(new Error(`invalid task status: ${String(status)}`), { code: 'bad-request' })
+    }
+    if (status !== undefined) task.status = status
+    if (typeof note === 'string' && note !== '') task.note = note
+    task.updatedAt = this.now()
+    await this.append(room, 'room/task', { roomId: room.roomId, action: 'updated', task })
+    let handedOff = []
+    if (status === 'done') handedOff = await this.handOffReady(room)
+    return { task, handedOff }
+  }
+
+  /** Wake owners of pending tasks whose dependencies all completed. */
+  async handOffReady(room) {
+    const ready = []
+    for (const task of room.tasks.values()) {
+      if (task.status !== 'pending' || task.readyNotified) continue
+      if (task.dependsOn.length === 0) continue
+      const depsDone = task.dependsOn.every((dep) => room.tasks.get(dep)?.status === 'done')
+      if (!depsDone) continue
+      task.readyNotified = true
+      task.updatedAt = this.now()
+      const owner = room.members.get(task.owner)
+      const message = {
+        id: randomUUID(),
+        roomId: room.roomId,
+        from: { kind: 'user', name: 'room' },
+        to: [task.owner],
+        text: `任务 "${task.title}" 的前置任务已完成，现在可以开始。`,
+        createdAt: this.now(),
+      }
+      room.messages.push(message)
+      await this.append(room, 'room/message', { roomId: room.roomId, messageId: message.id, from: message.from, to: message.to, text: message.text })
+      const woken = owner ? await this.wake(room, owner, message) : false
+      ready.push({ taskId: task.id, owner: task.owner, woken })
+    }
+    return ready
+  }
+
+  listTasks(roomId) {
+    const room = this.requireRoom(roomId)
+    return [...room.tasks.values()].sort((a, b) => a.createdAt - b.createdAt)
+  }
+
+  // ------------------------------------------------------------------- reads
+
+  messages({ roomId, limit = 50 } = {}) {
+    const room = this.requireRoom(roomId)
+    const items = room.messages.slice(-Math.max(1, Math.min(limit, 200)))
+    return items.map((message) => ({
+      ...message,
+      fromLabel: message.from.kind === 'user' ? 'user' : `${message.from.name ?? 'agent'} (${message.from.memberId ?? '?'})`,
+    }))
+  }
+
+  summary(room) {
+    return {
+      roomId: room.roomId,
+      createdAt: room.createdAt,
+      closed: room.closed,
+      policy: { ...room.policy },
+      members: [...room.members.values()].map((member) => this.memberSummary(member)),
+      messageCount: room.messages.length,
+      tasks: this.listTasks(room.roomId).length,
+    }
+  }
+
+  memberSummary(member) {
+    return {
+      memberId: member.memberId,
+      role: member.role,
+      kind: member.kind,
+      sessionId: member.sessionId,
+      name: member.name,
+    }
+  }
+
+  status(roomId) {
+    return this.summary(this.requireRoom(roomId))
+  }
+
+  /** All active rooms (UI list). */
+  list() {
+    return [...this.rooms.values()].map((room) => this.summary(room))
+  }
+
+  /** One room plus its transcript and board (UI detail). */
+  detail(roomId, { limit = 100 } = {}) {
+    const room = this.requireRoom(roomId)
+    return {
+      ...this.summary(room),
+      messages: this.messages({ roomId, limit }),
+      tasks: this.listTasks(roomId),
+    }
+  }
+
+  /** All open rooms (for cleanup and diagnostics). */
+  openRooms() {
+    return [...this.rooms.keys()]
+  }
+
+  async close({ roomId, reason = 'closed by host' } = {}) {
+    const room = this.requireRoom(roomId)
+    room.closed = true
+    await this.append(room, 'room/closed', { roomId: room.roomId, reason, closedAt: this.now() })
+    this.rooms.delete(room.roomId)
+    this.persist()
+    return { roomId: room.roomId, closed: true, reason }
+  }
+
+  requireRoom(roomId) {
+    const room = this.rooms.get(roomId)
+    if (!room) throw Object.assign(new Error(`unknown or closed room: ${String(roomId)}`), { code: 'unknown-room' })
+    return room
+  }
+}

package/src/host/runtime-config.js

@@ -0,0 +1,192 @@
+// Runtime configuration (ADR-0025): the profile patch stays the base layer,
+// while `$DSH_HOME/device-fleet/config-overrides.json` holds UI edits. Applying
+// a patch merges it, persists it and runs the registered live-apply handlers so
+// no plugin/DSH restart is required.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+const READONLY_FIELDS = ['dataDir']
+const CAPABILITY_MODES = ['auto', 'ask', 'deny']
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function deepMerge(base, patch) {
+  if (!isPlainObject(patch)) return patch
+  const result = isPlainObject(base) ? { ...base } : {}
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) continue
+    if (Array.isArray(value)) result[key] = value.map((item) => (isPlainObject(item) ? deepMerge({}, item) : item))
+    else if (isPlainObject(value)) result[key] = deepMerge(result[key], value)
+    else result[key] = value
+  }
+  return result
+}
+
+function readJson(file) {
+  if (!file || !existsSync(file)) return null
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function requirePositiveInteger(value, name, { min = 1, max = Number.MAX_SAFE_INTEGER } = {}) {
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw Object.assign(new Error(`${name} must be an integer between ${min} and ${max}`), { code: 'bad-request' })
+  }
+  return value
+}
+
+function stringList(value, name) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+    throw Object.assign(new Error(`${name} must be an array of strings`), { code: 'bad-request' })
+  }
+  return value.map((item) => item.trim()).filter((item) => item !== '')
+}
+
+function optionalString(value, name) {
+  if (value === undefined || value === null) return ''
+  if (typeof value !== 'string') throw Object.assign(new Error(`${name} must be a string`), { code: 'bad-request' })
+  return value.trim()
+}
+
+/**
+ * Validate and clean a UI patch. Only known fields survive; unknown keys are
+ * dropped instead of leaking arbitrary objects into the effective config.
+ */
+export function sanitizeConfigPatch(patch) {
+  if (!isPlainObject(patch)) throw Object.assign(new Error('config patch must be an object'), { code: 'bad-request' })
+  const clean = {}
+  if (patch.deviceName !== undefined) {
+    const name = optionalString(patch.deviceName, 'deviceName')
+    if (name !== '') clean.deviceName = name.slice(0, 80)
+  }
+  if (patch.promptSection !== undefined) clean.promptSection = patch.promptSection === true
+  if (patch.autoApproveAsk !== undefined) clean.autoApproveAsk = patch.autoApproveAsk === true
+  if (patch.discovery !== undefined) clean.discovery = patch.discovery === true
+  if (patch.dataDir !== undefined) {
+    throw Object.assign(new Error('dataDir cannot be changed at runtime'), { code: 'readonly' })
+  }
+  if (patch.direct !== undefined) {
+    if (!isPlainObject(patch.direct)) throw Object.assign(new Error('direct must be an object'), { code: 'bad-request' })
+    clean.direct = {
+      host: optionalString(patch.direct.host, 'direct.host') || '0.0.0.0',
+      port: requirePositiveInteger(Number(patch.direct.port ?? 0), 'direct.port', { min: 0, max: 65535 }),
+    }
+  }
+  if (patch.relay !== undefined) {
+    if (patch.relay === null) clean.relay = null
+    else if (isPlainObject(patch.relay)) {
+      clean.relay = {
+        host: optionalString(patch.relay.host, 'relay.host'),
+        port: requirePositiveInteger(Number(patch.relay.port ?? 0), 'relay.port', { min: 0, max: 65535 }),
+        dataPort: requirePositiveInteger(Number(patch.relay.dataPort ?? 0), 'relay.dataPort', { min: 0, max: 65535 }),
+        reconnect: patch.relay.reconnect !== false,
+      }
+      if (clean.relay.host === '' || clean.relay.port === 0) clean.relay = null
+    } else {
+      throw Object.assign(new Error('relay must be an object or null'), { code: 'bad-request' })
+    }
+  }
+  if (patch.execution !== undefined) {
+    if (!isPlainObject(patch.execution)) throw Object.assign(new Error('execution must be an object'), { code: 'bad-request' })
+    const execution = {}
+    if (patch.execution.cwd !== undefined) execution.cwd = optionalString(patch.execution.cwd, 'execution.cwd')
+    if (patch.execution.agentPreset !== undefined) execution.agentPreset = optionalString(patch.execution.agentPreset, 'execution.agentPreset')
+    if (patch.execution.shellTool !== undefined) execution.shellTool = optionalString(patch.execution.shellTool, 'execution.shellTool')
+    if (patch.execution.subagentProvider !== undefined) execution.subagentProvider = optionalString(patch.execution.subagentProvider, 'execution.subagentProvider')
+    if (patch.execution.approvalTimeoutMs !== undefined) {
+      execution.approvalTimeoutMs = requirePositiveInteger(Number(patch.execution.approvalTimeoutMs), 'execution.approvalTimeoutMs', { min: 1000 })
+    }
+    if (patch.execution.delegateTimeoutMs !== undefined) {
+      execution.delegateTimeoutMs = requirePositiveInteger(Number(patch.execution.delegateTimeoutMs), 'execution.delegateTimeoutMs', { min: 1000 })
+    }
+    clean.execution = execution
+  }
+  if (patch.policy !== undefined) {
+    if (!isPlainObject(patch.policy)) throw Object.assign(new Error('policy must be an object'), { code: 'bad-request' })
+    const policy = {}
+    if (patch.policy.allowedRoots !== undefined) policy.allowedRoots = stringList(patch.policy.allowedRoots, 'policy.allowedRoots')
+    if (patch.policy.allowedTools !== undefined) policy.allowedTools = stringList(patch.policy.allowedTools, 'policy.allowedTools')
+    if (patch.policy.approvalTtlMs !== undefined) {
+      policy.approvalTtlMs = requirePositiveInteger(Number(patch.policy.approvalTtlMs), 'policy.approvalTtlMs', { min: 1000 })
+    }
+    if (patch.policy.capabilities !== undefined) {
+      if (!isPlainObject(patch.policy.capabilities)) throw Object.assign(new Error('policy.capabilities must be an object'), { code: 'bad-request' })
+      const capabilities = {}
+      for (const [key, value] of Object.entries(patch.policy.capabilities)) {
+        if (!CAPABILITY_MODES.includes(value)) {
+          throw Object.assign(new Error(`policy.capabilities.${key} must be auto|ask|deny`), { code: 'bad-request' })
+        }
+        capabilities[key] = value
+      }
+      policy.capabilities = capabilities
+    }
+    clean.policy = policy
+  }
+  if (patch.approvals !== undefined) {
+    if (!isPlainObject(patch.approvals)) throw Object.assign(new Error('approvals must be an object'), { code: 'bad-request' })
+    const approvals = {}
+    if (patch.approvals.ttlMs !== undefined) approvals.ttlMs = requirePositiveInteger(Number(patch.approvals.ttlMs), 'approvals.ttlMs', { min: 1000 })
+    if (patch.approvals.maxPending !== undefined) approvals.maxPending = requirePositiveInteger(Number(patch.approvals.maxPending), 'approvals.maxPending', { min: 1 })
+    if (patch.approvals.simulation !== undefined) approvals.simulation = patch.approvals.simulation === true
+    clean.approvals = approvals
+  }
+  return clean
+}
+
+export class RuntimeConfig {
+  /**
+   * @param {object} options
+   * @param {object} options.base profile (Cordis) config
+   * @param {string} [options.overridesFile] JSON file edited from the UI
+   */
+  constructor({ base = {}, overridesFile = null } = {}) {
+    this.base = base
+    this.overridesFile = overridesFile
+    this.overrides = readJson(overridesFile) ?? {}
+    this.current = deepMerge(this.base, this.overrides)
+    this.applyHandlers = []
+    this.updating = Promise.resolve()
+  }
+
+  onChange(handler) {
+    this.applyHandlers.push(handler)
+  }
+
+  persist() {
+    if (!this.overridesFile) return
+    try {
+      mkdirSync(dirname(this.overridesFile), { recursive: true })
+      const temporary = `${this.overridesFile}.tmp`
+      writeFileSync(temporary, JSON.stringify(this.overrides, null, 2), 'utf8')
+      renameSync(temporary, this.overridesFile)
+    } catch {
+      /* overrides are best effort; the in-memory config is still applied */
+    }
+  }
+
+  /** Merge, persist and live-apply one patch. Returns the effective config. */
+  update(patch) {
+    const clean = sanitizeConfigPatch(patch)
+    return this.updating.then(async () => {
+      const previous = this.current
+      this.overrides = deepMerge(this.overrides, clean)
+      this.current = deepMerge(this.base, this.overrides)
+      this.persist()
+      for (const handler of this.applyHandlers) await handler(this.current, previous)
+      return this.current
+    })
+  }
+
+  snapshot() {
+    return {
+      config: this.current,
+      overrides: this.overrides,
+      readonly: READONLY_FIELDS,
+    }
+  }
+}

package/src/host/store.js

@@ -50,6 +50,7 @@ export function loadState({ dshHome, dataDir, name = 'device' } = {}) {
 
   const roster = readJson(path.join(dir, 'roster.json'), [])
   const config = readJson(path.join(dir, 'config.json'), {})
+  const peerHints = readJson(path.join(dir, 'peer-hints.json'), [])
   let enrollment = readJson(path.join(dir, 'enrollment.json'), null)
   let pendingEnrollment = readJson(path.join(dir, 'enrollment.pending.json'), null)
 
@@ -64,6 +65,7 @@ export function loadState({ dshHome, dataDir, name = 'device' } = {}) {
         joinedAt: Date.now(),
         accountFingerprint: decoded.accountFingerprint ?? null,
         relay: decoded.relay ?? null,
+        endpoints: decoded.endpoints ?? [],
       }
       writeJsonAtomic(path.join(dir, 'fleet.json'), fleet)
       writeJsonAtomic(path.join(dir, 'enrollment.json'), enrollment)
@@ -74,7 +76,32 @@ export function loadState({ dshHome, dataDir, name = 'device' } = {}) {
     }
   }
 
-  return { dataDir: dir, identity, fleet, roster: Array.isArray(roster) ? roster : [], config, enrollment, pendingEnrollment, createdFleet }
+  return {
+    dataDir: dir,
+    identity,
+    fleet,
+    roster: Array.isArray(roster) ? roster : [],
+    config,
+    enrollment,
+    pendingEnrollment,
+    peerHints: Array.isArray(peerHints) ? peerHints : [],
+    createdFleet,
+  }
+}
+
+/** Persist one manually supplied peer address (from fleet_connect) for reconnects. */
+export function savePeerHint(state, hint) {
+  if (!hint || typeof hint.host !== 'string' || !Number.isInteger(hint.port) || hint.port <= 0) return
+  const entry = {
+    host: hint.host,
+    port: hint.port,
+    ...(typeof hint.deviceId === 'string' ? { deviceId: hint.deviceId } : {}),
+  }
+  const hints = Array.isArray(state.peerHints) ? state.peerHints : []
+  const exists = hints.some((item) => item.host === entry.host && item.port === entry.port && item.deviceId === entry.deviceId)
+  if (!exists) hints.push(entry)
+  state.peerHints = hints
+  writeJsonAtomic(path.join(state.dataDir, 'peer-hints.json'), hints)
 }
 
 /** Queue an invite for the next plugin load (the running node keeps its fleet). */
@@ -102,8 +129,8 @@ export function saveConfig(state, config) {
 }
 
 /** Create an invite for this device's fleet. */
-export function createInvite(state, { accountFingerprint = null, relay = null } = {}) {
-  return encodeInvite({ fleet: state.fleet, accountFingerprint, relay })
+export function createInvite(state, { accountFingerprint = null, relay = null, endpoints = [] } = {}) {
+  return encodeInvite({ fleet: state.fleet, accountFingerprint, relay, endpoints })
 }
 
 /** Join a fleet from an invite code (overwrites fleet/enrollment, keeps identity). */
@@ -114,6 +141,7 @@ export function enrollFromInvite(state, code) {
     joinedAt: Date.now(),
     accountFingerprint: decoded.accountFingerprint ?? null,
     relay: decoded.relay ?? null,
+    endpoints: decoded.endpoints ?? [],
   }
   saveFleet(state)
   writeJsonAtomic(path.join(state.dataDir, 'enrollment.json'), state.enrollment)