@shendeguize/dsh-agent-sidecar 0.1.1 → 0.2.0

package/src/client/locales/en.ts

@@ -170,9 +170,79 @@ export const en = {
   'inject.errParse': 'The server response could not be parsed.',
   'inject.errGeneric': 'Request failed ({code}).',
 
-  // ── board tab chrome: main-view switcher ───────────────────────────────
+  // ── board tab chrome + session board ──────────────────────────────────
   'board.viewBoard': 'Session board',
   'board.viewProjects': 'Projects',
+  'board.status.working': 'Working',
+  'board.status.waiting': 'Waiting',
+  'board.status.idle': 'Idle',
+  'board.status.dead': 'Finished',
+  'board.status.unknown': 'Unknown',
+  'board.attention.gap': 'Event gap',
+  'board.daemon.probe': 'Probing',
+  'board.daemon.adopted': 'Connected · adopted',
+  'board.daemon.defer': 'Waiting for the system service',
+  'board.daemon.reprobe': 'Re-probing',
+  'board.daemon.hosting': 'Starting',
+  'board.daemon.hosted': 'Connected · hosted',
+  'board.daemon.backoff': 'Restart backoff',
+  'board.daemon.failed': 'Offline',
+  'board.stream.ok': 'Live stream healthy',
+  'board.stream.degraded': 'Live stream reconnecting',
+  'board.stream.unknown': 'Live stream not connected',
+  'board.banner.daemonFailed':
+    'sidecar is offline: the board shows the last snapshot and will not update',
+  'board.banner.streamDegraded': 'The live stream is reconnecting; data may be stale',
+  'board.empty.daemonFailedTitle': 'sidecar is offline',
+  'board.empty.daemonFailedHint':
+    'Repeated daemon start failures tripped the circuit breaker. Retry from Settings, or run agent-sidecar daemon start and wait for automatic adoption.',
+  'board.empty.daemonDeferTitle': 'Waiting for the system service to start the daemon',
+  'board.empty.daemonDeferHint':
+    'A LaunchAgent manages the daemon, so the plugin will not start it. The board populates automatically once the service starts it.',
+  'board.empty.filteredTitle': 'No sessions match these filters',
+  'board.empty.filteredHint':
+    'Try a wider time window, clear the status filter, or enable "Show finished".',
+  'board.empty.noSessionsTitle': 'No observed sessions yet',
+  'board.empty.noSessionsHint':
+    'Local agents (claude / codex / cursor / dsh …) appear here automatically once they start working.',
+  'board.topbar.title': 'Sidecar multi-agent board',
+  'board.topbar.refresh': 'Refresh',
+  'board.topbar.refreshing': 'Refreshing…',
+  'board.topbar.refreshTitle': 'Fetch the latest snapshot',
+  'board.topbar.refreshFailed': 'Refresh failed; the board is still showing the previous snapshot',
+  'board.topbar.dismiss': 'Dismiss',
+  'board.topbar.showDead': 'Show finished',
+  'board.topbar.timeWindow': 'Time window',
+  'board.topbar.countWorking': '{n} working',
+  'board.topbar.countWaiting': '{n} waiting',
+  'board.topbar.countTotal': '{n} sessions total',
+  'board.topbar.filterByStatusTitle': 'Show only sessions marked "{label}"',
+  'board.topbar.clearStatusFilterTitle': 'Clear the status filter and show all sessions',
+  'board.group.collapseTitle': 'Collapse this group',
+  'board.group.expandTitle': 'Expand this group',
+  'board.group.showAll': 'Show all {n} sessions',
+  'board.group.showLess': 'Show first {n} only',
+  'board.card.noEvent': 'No events yet',
+  'board.card.untitled': '(untitled)',
+  'board.card.observedDisclaimer':
+    'Status is an observed value inferred from persisted data and may lag',
+  'board.card.observedValue': 'Observed value: {status}',
+  'board.card.lastReconcile': 'Last reconciled: {time}',
+  'board.card.neverReconciled': 'Not reconciled yet',
+  'board.card.copyId': 'Click to copy the full session ID',
+  'board.card.copied': 'Copied',
+  'board.time.justNow': 'just now',
+  'board.time.minutesAgo': '{n} min ago',
+  'board.time.hoursAgo': '{n} h ago',
+  'board.timeWindow.hours': '{n} hours',
+  'board.timeWindow.days': '{n} days',
+  'board.groupCount': '{n} sessions',
+  'board.unknownProject': 'Unknown project',
+  'board.widget.label': 'Sidecar',
+  'board.widget.connection.ok': 'Connected',
+  'board.widget.connection.degraded': 'Connection unstable',
+  'board.widget.connection.off': 'Offline',
+  'board.widget.working': '{n} sessions working',
 
   // ── session detail ───────────────────────────────────────────────────
   'detail.header.close': 'Back to board',
@@ -388,7 +458,9 @@ export const en = {
   'command.time.hoursAgo': '{n} h ago',
   'command.time.daysAgo': '{n} d ago',
 
-  // ── better-sidebar mini tab (T6.3) ─────────────────────────────────────
+  // ── sidebar navigation (plain DOM + optional better-sidebar) ───────────
+  'sidebar.centerEntryLabel': 'Agent Center',
+  'sidebar.centerEntryAria': 'Open Agent Center',
   'sidebar.tabTitle': 'Sidecar',
   'sidebar.countsRow': '{working} working · {waiting} waiting',
   'sidebar.recentTitle': 'Recently active',

package/src/client/locales/host.ts

@@ -0,0 +1,131 @@
+/**
+ * Capability-based bridge to the optional dsh locale service.
+ *
+ * API evidence:
+ * `.local/reference/deepseek-harness/packages/client/locale/src/client/index.ts`
+ * exposes `getLocale().active`, `register(ns, locale, dict)`, and the
+ * context event `locale/change`. This module mirrors only those shapes; it
+ * deliberately imports no unpublished host runtime value.
+ */
+
+/** Locale ids shipped by Agent Sidecar. */
+export type HostMappedLocale = 'zh' | 'en'
+
+/** Flat namespace dictionary accepted by the host registry. */
+export type HostLocaleDictionary = Readonly<Record<string, string>>
+
+/** Locale-like values accepted from getters and change events. */
+export interface HostLocaleSnapshot {
+  active?: string
+  locale?: string
+  preference?: string
+  value?: { preference?: string }
+}
+
+export type HostLocaleValue = string | HostLocaleSnapshot | null | undefined
+export type HostLocaleDisposer = () => void
+
+/** Optional locale service capabilities used by the bridge. */
+export interface HostLocaleService {
+  getLocale?: () => HostLocaleValue
+  register?: (
+    namespace: string,
+    locale: string,
+    dictionary: HostLocaleDictionary,
+  ) => void | HostLocaleDisposer
+}
+
+/** Optional host-context capabilities used by the bridge. */
+export interface HostLocalePort {
+  locale?: HostLocaleService
+  on?: (
+    event: 'locale/change',
+    listener: (value?: HostLocaleValue) => void,
+  ) => void | HostLocaleDisposer
+}
+
+/** Injected policy and data; keeps the adapter independent of locale state. */
+export interface HostLocaleBridgeOptions {
+  namespace: string
+  dictionaries: Readonly<Record<HostMappedLocale, HostLocaleDictionary>>
+  onLocale: (locale: HostMappedLocale) => void
+}
+
+function localeTag(value: HostLocaleValue): string | undefined {
+  if (typeof value === 'string') return value
+  if (value === null || value === undefined) return undefined
+  return value.active
+    ?? value.preference
+    ?? value.locale
+    ?? value.value?.preference
+}
+
+/** Map every Chinese locale variant to zh; all other values use en. */
+export function mapHostLocale(value: HostLocaleValue): HostMappedLocale {
+  return localeTag(value)?.trim().toLowerCase().startsWith('zh') === true ? 'zh' : 'en'
+}
+
+/**
+ * Register dictionaries, adopt the current Host locale, and follow changes.
+ * Every capability is optional and isolated: absent or throwing Host methods
+ * leave the module-owned locale fallback intact.
+ */
+export function bridgeHostLocale(
+  host: HostLocalePort | null | undefined,
+  options: HostLocaleBridgeOptions,
+): HostLocaleDisposer {
+  const disposers: HostLocaleDisposer[] = []
+  const service = host?.locale
+
+  for (const locale of ['zh', 'en'] as const) {
+    try {
+      const dispose = service?.register?.(
+        options.namespace,
+        locale,
+        options.dictionaries[locale],
+      )
+      if (typeof dispose === 'function') disposers.push(dispose)
+    } catch {
+      // Optional/duplicate registry seats must not block the local fallback.
+    }
+  }
+
+  const read = (): HostLocaleValue => {
+    try {
+      return service?.getLocale?.()
+    } catch {
+      return undefined
+    }
+  }
+  const apply = (value: HostLocaleValue): void => {
+    if (localeTag(value) === undefined) return
+    try {
+      options.onLocale(mapHostLocale(value))
+    } catch {
+      // A consumer failure must not escape a Host event callback.
+    }
+  }
+
+  try {
+    const dispose = host?.on?.('locale/change', (value) => {
+      apply(value === undefined ? read() : value)
+    })
+    if (typeof dispose === 'function') disposers.push(dispose)
+  } catch {
+    // Event capability is optional.
+  }
+  apply(read())
+
+  let disposed = false
+  return () => {
+    if (disposed) return
+    disposed = true
+    for (const dispose of disposers.reverse()) {
+      try {
+        dispose()
+      } catch {
+        // Teardown remains best-effort across independently owned services.
+      }
+    }
+  }
+}

package/src/client/locales/index.ts

@@ -14,29 +14,47 @@
  * visible, never blank — same posture as the ecosystem LocaleRuntime,
  * which falls back to en; ours falls back to zh per this plugin's spec).
  *
- * BRIDGE PATH (for the wiring task): each dictionary is a flat
- * `Record<string, string>` — exactly the shape the ecosystem locale
- * service's untyped overload `ctx.locale.register(ns, locale, dict)`
- * accepts — so when the runtime composition provides `ctx.locale`, the
- * wiring half can feed `dictionaries.zh` / `dictionaries.en` straight into
- * it and hand the slot-injected `t` seat to the components instead of the
- * module-local {@link t}. Template params use the same `{name}` syntax as
+ * The optional Host bridge in ./host.ts registers these flat dictionaries
+ * through the ecosystem locale service's untyped
+ * `register(ns, locale, dict)` overload and mirrors `locale/change` into
+ * this module's active locale. The local table remains the fallback whenever
+ * that service is absent. Template params use the same `{name}` syntax as
  * the ecosystem translate.
  */
 
 import { zh } from './zh.ts'
 import { en } from './en.ts'
+import {
+  bridgeHostLocale as bridgeHostLocalePort,
+  type HostLocalePort as HostLocalePortFace,
+  type HostLocaleService as HostLocaleServiceFace,
+  type HostMappedLocale as HostMappedLocaleId,
+} from './host.ts'
 import type { SidecarLocaleDomain, SidecarLocaleKey } from './zh.ts'
 
 export { zh, en }
 export type { SidecarLocaleDomain, SidecarLocaleKey }
+export { bridgeHostLocale, mapHostLocale } from './host.ts'
+export type {
+  HostLocaleBridgeOptions,
+  HostLocaleDictionary,
+  HostLocaleDisposer,
+  HostLocalePort,
+  HostLocaleService,
+  HostLocaleSnapshot,
+  HostLocaleValue,
+  HostMappedLocale,
+} from './host.ts'
 
 /** Shipped locales. */
-export type SidecarLocale = 'zh' | 'en'
+export type SidecarLocale = HostMappedLocaleId
 
 /** Default locale AND the final dictionary consulted before echoing the key. */
 export const BASE_LOCALE: SidecarLocale = 'zh'
 
+/** Host namespace owned by Agent Sidecar dictionaries. */
+export const SIDECAR_LOCALE_NAMESPACE = 'agent-sidecar'
+
 /** One flat dictionary (the `ctx.locale.register(ns, locale, dict)` currency). */
 export type SidecarDict = Readonly<Record<string, string>>
 
@@ -111,6 +129,176 @@ export function subscribeLocale(fn: () => void): () => void {
   return () => { localeListeners.delete(fn) }
 }
 
+interface HostLocaleOwner {
+  host: HostLocalePortFace
+  service: HostLocaleServiceFace
+  onLocale: (locale: SidecarLocale) => void
+}
+
+interface HostLocaleLease {
+  owners: Set<HostLocaleOwner>
+  detachDictionaries: () => void
+}
+
+interface HostLocaleLeaseRegistry {
+  get(service: HostLocaleServiceFace): HostLocaleLease | undefined
+  set(service: HostLocaleServiceFace, lease: HostLocaleLease): unknown
+  delete(service: HostLocaleServiceFace): boolean
+}
+
+interface HostLocaleOwnerSet {
+  readonly size: number
+  add(owner: HostLocaleOwner): unknown
+  delete(owner: HostLocaleOwner): boolean
+  [Symbol.iterator](): IterableIterator<HostLocaleOwner>
+}
+
+interface HostLocaleArbiter {
+  leases: HostLocaleLeaseRegistry
+  owners: HostLocaleOwnerSet
+  activeOwner: HostLocaleOwner | null
+  detachEvents: () => void
+}
+
+const HOST_LOCALE_LEASES_SYMBOL = Symbol.for(
+  '@shendeguize/dsh-agent-sidecar/host-locale-leases',
+)
+const globalSymbols = globalThis as typeof globalThis & { [key: symbol]: unknown }
+
+function hasMethod<K extends PropertyKey>(
+  value: unknown,
+  key: K,
+): value is Record<K, (...args: never[]) => unknown> {
+  return typeof value === 'object'
+    && value !== null
+    && typeof (value as Record<K, unknown>)[key] === 'function'
+}
+
+function isLeaseRegistry(value: unknown): value is HostLocaleLeaseRegistry {
+  return hasMethod(value, 'get') && hasMethod(value, 'set') && hasMethod(value, 'delete')
+}
+
+function isOwnerSet(value: unknown): value is HostLocaleOwnerSet {
+  return hasMethod(value, 'add')
+    && hasMethod(value, 'delete')
+    && hasMethod(value, Symbol.iterator)
+    && typeof (value as { size?: unknown }).size === 'number'
+}
+
+function isHostLocaleArbiter(value: unknown): value is HostLocaleArbiter {
+  if (typeof value !== 'object' || value === null) return false
+  const candidate = value as Partial<HostLocaleArbiter>
+  return isLeaseRegistry(candidate.leases)
+    && isOwnerSet(candidate.owners)
+    && (candidate.activeOwner === null || typeof candidate.activeOwner === 'object')
+    && typeof candidate.detachEvents === 'function'
+}
+
+const sharedLocaleState = globalSymbols[HOST_LOCALE_LEASES_SYMBOL]
+const hostLocaleArbiter: HostLocaleArbiter = isHostLocaleArbiter(sharedLocaleState)
+  ? sharedLocaleState
+  : {
+      // Preserve a pre-arbiter WeakMap-like registry across an HMR upgrade.
+      leases: isLeaseRegistry(sharedLocaleState)
+        ? sharedLocaleState
+        : new WeakMap<HostLocaleServiceFace, HostLocaleLease>(),
+      owners: new Set<HostLocaleOwner>(),
+      activeOwner: null,
+      detachEvents: () => {},
+    }
+globalSymbols[HOST_LOCALE_LEASES_SYMBOL] = hostLocaleArbiter
+
+function bridge(
+  host: HostLocalePortFace,
+  onLocale: (locale: SidecarLocale) => void,
+): () => void {
+  return bridgeHostLocalePort(host, {
+    namespace: SIDECAR_LOCALE_NAMESPACE,
+    dictionaries,
+    onLocale,
+  })
+}
+
+function followOwner(owner: HostLocaleOwner): () => void {
+  return bridge({
+    locale: { getLocale: () => owner.service.getLocale?.() },
+    on: (event, listener) => owner.host.on?.(event, listener),
+  }, locale => {
+    if (hostLocaleArbiter.activeOwner === owner) owner.onLocale(locale)
+  })
+}
+
+function latestOwner(owners: HostLocaleOwnerSet): HostLocaleOwner {
+  let latest: HostLocaleOwner | undefined
+  for (const owner of owners) latest = owner
+  return latest as HostLocaleOwner
+}
+
+function detachActiveFollower(): void {
+  const detach = hostLocaleArbiter.detachEvents
+  hostLocaleArbiter.detachEvents = () => {}
+  try {
+    detach()
+  } catch {
+    // Cross-bundle optional Host teardown remains best-effort.
+  }
+}
+
+function activateOwner(owner: HostLocaleOwner): void {
+  detachActiveFollower()
+  hostLocaleArbiter.activeOwner = owner
+  hostLocaleArbiter.detachEvents = followOwner(owner)
+}
+
+/**
+ * Lease the shipped dictionaries and locale following for one Host service.
+ * Dictionary ownership is keyed by service identity. Event ownership is
+ * global across services and bundles so only the latest attached owner can
+ * drive its module-local locale.
+ */
+export function attachHostLocale(host: HostLocalePortFace | null | undefined): () => void {
+  if (host?.locale === undefined) return () => {}
+  const service = host.locale
+
+  const owner: HostLocaleOwner = { host, service, onLocale: setLocale }
+  let lease = hostLocaleArbiter.leases.get(service)
+  if (lease === undefined) {
+    lease = {
+      owners: new Set<HostLocaleOwner>(),
+      // Registration must never choose this module's active locale.
+      detachDictionaries: bridge({ locale: service }, () => {}),
+    }
+    hostLocaleArbiter.leases.set(service, lease)
+  }
+  lease.owners.add(owner)
+  hostLocaleArbiter.owners.add(owner)
+  activateOwner(owner)
+
+  let disposed = false
+  return () => {
+    if (disposed) return
+    disposed = true
+    const wasActive = hostLocaleArbiter.activeOwner === owner
+    lease.owners.delete(owner)
+    hostLocaleArbiter.owners.delete(owner)
+    if (wasActive) {
+      detachActiveFollower()
+      hostLocaleArbiter.activeOwner = null
+    }
+    if (lease.owners.size === 0) {
+      lease.detachDictionaries()
+      hostLocaleArbiter.leases.delete(service)
+    }
+    if (!wasActive) return
+
+    if (hostLocaleArbiter.owners.size > 0) {
+      activateOwner(latestOwner(hostLocaleArbiter.owners))
+      return
+    }
+    owner.onLocale(BASE_LOCALE)
+  }
+}
+
 /**
  * Translate a typed key in the active locale. Missing entries fall back to
  * zh, then to the key itself (see module doc for why the chain ends visible).

package/src/client/locales/react.ts

@@ -0,0 +1,10 @@
+import { useSyncExternalStore } from 'react'
+import { getLocale, subscribeLocale, type SidecarLocale } from './index.ts'
+
+/**
+ * Subscribe the calling React root to the module-owned active locale.
+ * Reading translations remains late-bound through `t` and locale facades.
+ */
+export function useActiveLocale(): SidecarLocale {
+  return useSyncExternalStore(subscribeLocale, getLocale, getLocale)
+}

package/src/client/locales/view.ts

@@ -0,0 +1,38 @@
+import { t, type SidecarLocaleKey } from './index.ts'
+
+/**
+ * A nested map from view-facing names to keys in the shipped locale table.
+ * Leaves are deliberately parameterless; callers format translated templates.
+ */
+export type LocaleViewDescriptor = Readonly<{
+  [name: string]: SidecarLocaleKey | LocaleViewDescriptor
+}>
+
+/** Preserve a descriptor's readonly shape while translating every leaf. */
+export type LocaleView<D extends LocaleViewDescriptor> = {
+  readonly [K in keyof D]:
+    D[K] extends SidecarLocaleKey ? string
+      : D[K] extends LocaleViewDescriptor ? LocaleView<D[K]>
+        : never
+}
+
+function buildNode(descriptor: LocaleViewDescriptor): Record<string, unknown> {
+  const view: Record<string, unknown> = {}
+  for (const [name, value] of Object.entries(descriptor)) {
+    const property: PropertyDescriptor = typeof value === 'string'
+      ? { enumerable: true, get: () => t(value) }
+      : { enumerable: true, value: buildNode(value) }
+    Object.defineProperty(view, name, property)
+  }
+  return view
+}
+
+/**
+ * Build one stable, enumerable locale facade. Leaf getters call {@link t} at
+ * read time, so the same facade follows subsequent active-locale changes.
+ */
+export function createLocaleView<const D extends LocaleViewDescriptor>(
+  descriptor: D,
+): LocaleView<D> {
+  return buildNode(descriptor) as LocaleView<D>
+}