Merge remote-tracking branch 'origin/master' into xtr/sidebar-workspace-controls

packages/client/runtime/src/client/contract/settings-scope.ts

@@ -0,0 +1,63 @@
+/**
+ * The settings-namespace scope contract. The type lives here, in the common
+ * dependency of every feature that owns a preference, while the implementation
+ * and its Host transport live with the Settings surface
+ * (`dsh-client-ui-settings`): a feature service accepts a scope through
+ * `attachSettings` without depending on the surface that binds it, which would
+ * otherwise close a reference cycle.
+ */
+
+/** Client-side sync state of one settings namespace. */
+export interface SettingsScopeSnapshot<T> {
+  /**
+   * `loading` until the first accepted section, `ready` while one stands, and
+   * `unavailable` when the namespace is not exposed to this client or the
+   * connection keeps preferences process-local (memory mode).
+   */
+  status: 'loading' | 'ready' | 'unavailable'
+  /** Last accepted schema-resolved section; undefined before the first acceptance. */
+  value: T | undefined
+  /** Namespace revision fencing the next write; undefined before the first Host view. */
+  revision: number | undefined
+  /** Whether the Host document accepts writes; memory mode never does. */
+  writable: boolean
+  /** `host` syncs with the Host document; `memory` keeps a remote browser process-local. */
+  mode: 'host' | 'memory'
+}
+
+/** Domain-owned description of one settings namespace consumed by a browser plugin. */
+export interface SettingsScopeSpec<T> {
+  /** Settings namespace registered by the owning Host plugin. */
+  namespace: string
+  /**
+   * Narrow one wire section; undefined keeps the last accepted value. The
+   * default validates the section against the namespace's own serialized wire
+   * schema, so domains add a decoder only to narrow beyond that schema.
+   */
+  decode?: (section: unknown) => T | undefined
+}
+
+/**
+ * Reactive owner handle over one namespace's durable section — the browser
+ * mirror of the Host-side `SettingsScope` owner seam. Domain services read
+ * and observe the snapshot and route explicit user choices through `set`.
+ */
+export interface SettingsScope<T> {
+  /** @returns the current sync snapshot (stable reference until the next change). */
+  getSnapshot(): SettingsScopeSnapshot<T>
+  /**
+   * Observe snapshot replacements.
+   * @param listener - invoked after each snapshot change.
+   * @returns the disposer removing this listener.
+   */
+  subscribe(listener: () => void): () => void
+  /**
+   * Queue one field write. Rapid writes preserve mutation order, each carries
+   * the latest known namespace revision, and only the latest settlement may
+   * publish; a rejected or failed latest write reloads Host state instead.
+   * @param field - scalar field inside the namespace section.
+   * @param value - JSON-shaped value selected by the user.
+   * @returns settlement after the write and any latest-write recovery read.
+   */
+  set(field: string, value: unknown): Promise<void>
+}

packages/client/runtime/src/client/index.ts

@@ -1,6 +1,10 @@
 /** Browser runtime services for slots, sessions, workspaces, and connection-stream delivery. */
 import type { Context } from '@deepseek-ai/cordis'
 import type { ConnectionHandle, SessionId } from '@deepseek-ai/dsh-client-connection/client'
+// Type-only: the ctx.remote merge. Deliberately the gateway's Client half rather
+// than api-remotes': that face imports a Host-tsdown-generated artifact, and this
+// project sits in the Host build graph.
+import type {} from '@deepseek-ai/dsh-api-gateway/client'
 import type { TypeRTContext } from '@deepseek-ai/dsh-type-meta'
 import type { MaybeSnapshotSelectorHook, SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotsService } from './slots.ts'
@@ -42,9 +46,12 @@ export type { SessionProvideChannelHost } from './sessions/provide.ts'
 export { createScope } from './agents/scope.ts'
 export type { AgentScopeHandle } from './agents/scope.ts'
 export { DirectoryBrowseError, WorkspaceCreateError, WorkspacesService } from './workspaces/service.ts'
-export { bindSettingsScope, SettingsScopeController } from './settings-scope.ts'
-export type { SettingsScope, SettingsScopeSnapshot, SettingsScopeSpec } from './settings-scope.ts'
 export { resolveWorkspacePath } from './workspaces/path.ts'
+// Contract only: the scope implementation and its Host transport belong to
+// dsh-client-ui-settings (see that package's settings-scope.ts).
+export type {
+  SettingsScope, SettingsScopeSnapshot, SettingsScopeSpec,
+} from './contract/settings-scope.ts'
 export type { Session } from './sessions/session.ts'
 export type { ISession, ProjectionsFace, SessionFace } from './contract/session.ts'
 export type { AgentContext, ISessions } from './contract/sessions.ts'
@@ -150,47 +157,6 @@ declare module '@deepseek-ai/cordis' {
      * @param key - the mutated SlotMap key.
      */
     'slots/changed'(key: string): void
-    /**
-     * The host command registry changed (host/commands-changed passthrough).
-     * Pure invalidation signal: subscribers refetch `command.list` in the
-     * background rather than diffing.
-     * @mode emit
-     */
-    'commands/changed'(): void
-    /**
-     * One settings namespace's resolved value changed on the host
-     * (host/settings-changed passthrough). Subscribers refetch
-     * `settings.describe`; the frame carries no values.
-     * @mode emit
-     * @param ns - the namespace whose resolved value changed.
-     */
-    'settings/changed'(ns: string): void
-    /**
-     * One credential reference's state changed on the host
-     * (host/credentials-changed passthrough). The ref is an
-     * environment-variable NAME — never a value.
-     * @mode emit
-     * @param ref - the reference whose configured state changed.
-     */
-    'credentials/changed'(ref: string): void
-    /**
-     * The host provider topology changed (host/models-changed passthrough).
-     * Subscribers refetch `llm.providers`/`llm.models`/`session.models`.
-     * @mode emit
-     */
-    'models/changed'(): void
-    /**
-     * One session's agent preset changed (host/session-preset-changed
-     * passthrough), so everything its composition decides — the command
-     * catalog, the skill catalog — is stale for that session and no other.
-     * Every connected client observes it, not only the one that issued the
-     * switch. Subscribers refetch their own session-keyed caches; the frame
-     * carries no catalog.
-     * @mode emit
-     * @param sessionId - the session whose composition changed.
-     * @param agentPreset - the preset it now runs.
-     */
-    'session/preset-changed'(sessionId: SessionId, agentPreset: string): void
     /**
      * A connection generation was (re-)established. Wire-derived caches must
      * treat their state as stale and repull (commands directory; the queue
@@ -213,7 +179,7 @@ declare module '@deepseek-ai/cordis' {
 }
 
 /** Required services: the wire handle and Client TypeRT registry. */
-export const inject = ['connection', 'typert']
+export const inject = ['connection', 'typert', 'remote']
 
 /** Mounts the browser runtime services and connection stream.
  * @param ctx - Client Cordis context.
@@ -241,17 +207,12 @@ export function apply(ctx: Context): void {
     onHostEnvelope: (envelope) => {
       sessions.handleHostEnvelope(envelope)
       workspaces.handleHostEnvelope(envelope)
-      // Typed-event bridge: the session layer ignores registry frames (no
-      // session routing); consumers (command directory caches, the settings
-      // and model services) subscribe on ctx.
+      // Forwarded-event bridge: the session layer ignores registry frames (no
+      // session routing). This plugin owns the frame sink, so it hands the
+      // decoded frame straight to the Remote service, which fans it out to
+      // `ctx.remote.$on` subscribers; no consumer reads a frame.
       const frame = envelope.payload
-      if (frame.type === 'host/commands-changed') ctx.emit('commands/changed')
-      else if (frame.type === 'host/session-preset-changed') {
-        ctx.emit('session/preset-changed', frame.sessionId, frame.agentPreset)
-      }
-      else if (frame.type === 'host/settings-changed') ctx.emit('settings/changed', frame.ns)
-      else if (frame.type === 'host/credentials-changed') ctx.emit('credentials/changed', frame.ref)
-      else if (frame.type === 'host/models-changed') ctx.emit('models/changed')
+      if (frame.type === 'host/remote-event') ctx.remote.$dispatch(frame.event, frame.args)
     },
     onConnected: () => {
       sessions.handleConnected()

packages/client/runtime/src/client/sessions/manager.ts

@@ -811,14 +811,6 @@ export class SessionManager {
         }
         return
       }
-      case 'host/session-preset-changed': {
-        // Every connected client observes the switch here; only the tab that
-        // issued it also gets the RPC echo. The merge keeps the row's own
-        // updatedAt and lowers `blank` only, so re-applying the switching
-        // tab's own frame is a no-op.
-        this.noteAgentPreset(frame.sessionId, frame.agentPreset)
-        return
-      }
       case 'host/session-removed': {
         const summary = this.summaries.find(candidate => candidate.sessionId === frame.sessionId)
         const durableSubagent = summary?.origin === 'subagent' || this.addresses.has(frame.sessionId)

packages/client/runtime/src/client/settings-scope.ts

@@ -1,261 +0,0 @@
-/** Host-backed settings-namespace synchronization for browser plugins. */
-
-import type { Context } from '@deepseek-ai/cordis'
-import type {
-  ConnectionHandle, IApiClient, SettingsNamespaceView,
-} from '@deepseek-ai/dsh-client-connection/client'
-import { rehydrateSchema, validateDraft } from '@deepseek-ai/dsh-client-schema-form'
-import { createSnapshotStore, type SnapshotStore } from './contract/store.ts'
-
-/** Client-side sync state of one settings namespace. */
-export interface SettingsScopeSnapshot<T> {
-  /**
-   * `loading` until the first accepted section, `ready` while one stands, and
-   * `unavailable` when the namespace is not exposed to this client or the
-   * connection keeps preferences process-local (memory mode).
-   */
-  status: 'loading' | 'ready' | 'unavailable'
-  /** Last accepted schema-resolved section; undefined before the first acceptance. */
-  value: T | undefined
-  /** Namespace revision fencing the next write; undefined before the first Host view. */
-  revision: number | undefined
-  /** Whether the Host document accepts writes; memory mode never does. */
-  writable: boolean
-  /** `host` syncs with the Host document; `memory` keeps a remote browser process-local. */
-  mode: 'host' | 'memory'
-}
-
-/** Domain-owned description of one settings namespace consumed by a browser plugin. */
-export interface SettingsScopeSpec<T> {
-  /** Settings namespace registered by the owning Host plugin. */
-  namespace: string
-  /**
-   * Narrow one wire section; undefined keeps the last accepted value. The
-   * default validates the section against the namespace's own serialized wire
-   * schema, so domains add a decoder only to narrow beyond that schema.
-   */
-  decode?: (section: unknown) => T | undefined
-}
-
-/**
- * Reactive owner handle over one namespace's durable section — the browser
- * mirror of the Host-side `SettingsScope` owner seam. Domain services read
- * and observe the snapshot and route explicit user choices through `set`.
- */
-export interface SettingsScope<T> {
-  /** @returns the current sync snapshot (stable reference until the next change). */
-  getSnapshot(): SettingsScopeSnapshot<T>
-  /**
-   * Observe snapshot replacements.
-   * @param listener - invoked after each snapshot change.
-   * @returns the disposer removing this listener.
-   */
-  subscribe(listener: () => void): () => void
-  /**
-   * Queue one field write. Rapid writes preserve mutation order, each carries
-   * the latest known namespace revision, and only the latest settlement may
-   * publish; a rejected or failed latest write reloads Host state instead.
-   * @param field - scalar field inside the namespace section.
-   * @param value - JSON-shaped value selected by the user.
-   * @returns settlement after the write and any latest-write recovery read.
-   */
-  set(field: string, value: unknown): Promise<void>
-}
-
-type SettingsFace = Pick<IApiClient, 'settings'>
-
-/**
- * Serializes one namespace's Host reads and writes behind a snapshot store.
- * Reads never block plugin activation; writes carry the latest known
- * namespace revision and teardown waits for the operation already crossing
- * the wire.
- */
-export class SettingsScopeController<T> implements SettingsScope<T> {
-  private readonly store: SnapshotStore<SettingsScopeSnapshot<T>>
-  private tail: Promise<void> = Promise.resolve()
-  private readGeneration = 0
-  private writeGeneration = 0
-  private disposed = false
-
-  /**
-   * @param api - settings wire face.
-   * @param spec - namespace identity and optional narrowing decoder.
-   * @param persistence - remote browsers remain process-local because settings RPCs are loopback-only.
-   */
-  constructor(
-    private readonly api: SettingsFace,
-    private readonly spec: SettingsScopeSpec<T>,
-    private readonly persistence: 'host' | 'memory' = 'host',
-  ) {
-    this.store = createSnapshotStore<SettingsScopeSnapshot<T>>({
-      status: persistence === 'host' ? 'loading' : 'unavailable',
-      value: undefined,
-      revision: undefined,
-      writable: false,
-      mode: persistence,
-    })
-  }
-
-  /** @returns the current sync snapshot (stable reference until the next change). */
-  getSnapshot(): SettingsScopeSnapshot<T> {
-    return this.store.getSnapshot()
-  }
-
-  /**
-   * Observe snapshot replacements.
-   * @param listener - invoked after each snapshot change.
-   * @returns the disposer removing this listener.
-   */
-  subscribe(listener: () => void): () => void {
-    return this.store.subscribe(listener)
-  }
-
-  /**
-   * Queue a Host refresh; a newer read or user write suppresses stale publication.
-   * @returns settlement after the queued read completes or is skipped.
-   */
-  load(): Promise<void> {
-    const generation = ++this.readGeneration
-    return this.enqueue(() => this.read(generation))
-  }
-
-  /**
-   * Queue one field write; see {@link SettingsScope.set} for the ordering,
-   * revision, and recovery contract.
-   * @param field - scalar field inside the namespace section.
-   * @param value - JSON-shaped value selected by the user.
-   * @returns settlement after the write and any latest-write recovery read.
-   */
-  set(field: string, value: unknown): Promise<void> {
-    this.readGeneration += 1
-    const generation = ++this.writeGeneration
-    return this.enqueue(async () => {
-      const revision = this.getSnapshot().revision
-      let response: Awaited<ReturnType<SettingsFace['settings']['mutate']>>
-      try {
-        response = await this.api.settings.mutate({
-          ns: this.spec.namespace,
-          ops: [{ op: 'set', path: [field], value }],
-          ...(revision === undefined ? {} : { expectedRevision: revision }),
-        })
-      } catch (_settingsWriteFailure) {
-        if (!this.disposed && generation === this.writeGeneration) await this.read(++this.readGeneration)
-        return
-      }
-      if (!response.result.ok) {
-        if (!this.disposed && generation === this.writeGeneration) await this.read(++this.readGeneration)
-        return
-      }
-      this.accept(response.result.value, generation === this.writeGeneration)
-    })
-  }
-
-  /**
-   * Stop queued operations and wait for the current wire call to settle.
-   * @returns settlement after the controller reaches quiescence.
-   */
-  async dispose(): Promise<void> {
-    this.disposed = true
-    this.readGeneration += 1
-    this.writeGeneration += 1
-    await this.tail
-  }
-
-  private enqueue(operation: () => Promise<void>): Promise<void> {
-    if (this.persistence === 'memory' || this.disposed) return Promise.resolve()
-    const task = this.tail.then(async () => {
-      if (this.disposed) return
-      await operation()
-    })
-    // The returned task carries its own settlement to the caller; the queue
-    // tail is kept fulfilled so one failed subscriber cannot strand later operations.
-    this.tail = task.catch(() => {})
-    return task
-  }
-
-  private async read(generation: number): Promise<void> {
-    let response: Awaited<ReturnType<SettingsFace['settings']['describe']>>
-    try {
-      response = await this.api.settings.describe({})
-    } catch (_settingsReadFailure) {
-      return
-    }
-    if (!response.result.ok || this.disposed) return
-    const { namespaces, writable } = response.result.value
-    const view = namespaces.find(candidate => candidate.ns === this.spec.namespace)
-    const publish = generation === this.readGeneration
-    if (view === undefined) {
-      if (publish) {
-        this.store.update((draft) => {
-          draft.status = 'unavailable'
-          draft.writable = writable
-        })
-      }
-      return
-    }
-    this.accept(view, publish, writable)
-  }
-
-  private accept(view: SettingsNamespaceView, publish: boolean, writable?: boolean): void {
-    const decoded = publish ? this.decode(view) : undefined
-    this.store.update((draft) => {
-      draft.revision = view.revision
-      if (writable !== undefined) draft.writable = writable
-      if (decoded === undefined) return
-      draft.status = 'ready'
-      draft.value = decoded
-    })
-  }
-
-  private decode(view: SettingsNamespaceView): T | undefined {
-    if (this.spec.decode !== undefined) return this.spec.decode(view.value)
-    // Sections are plain objects by construction; schemastery alone would
-    // resolve null or an array through object defaults instead of refusing.
-    if (typeof view.value !== 'object' || view.value === null || Array.isArray(view.value)) return undefined
-    let failure: string | undefined
-    try {
-      failure = validateDraft(rehydrateSchema(view.schema), view.value)
-    } catch (_malformedSchemaEnvelope) {
-      // A schema envelope this client cannot rehydrate vouches for no section;
-      // the value is treated exactly like a schema-invalid one.
-      return undefined
-    }
-    return failure === undefined ? view.value as T : undefined
-  }
-}
-
-/**
- * Bind one namespace scope to settings and connection invalidations on the
- * caller's plugin lifecycle. Listeners exist before the initial background
- * read starts, so activation never blocks on the settings transport.
- * @param ctx - owning browser plugin context.
- * @param spec - domain-owned namespace contract.
- * @returns the bound scope consumed by the domain's services and rows.
- */
-export function bindSettingsScope<T>(
-  ctx: Context,
-  spec: SettingsScopeSpec<T>,
-): SettingsScope<T> {
-  const connection = ctx.get('connection') as ConnectionHandle
-  const controller = new SettingsScopeController<T>(
-    connection.api,
-    spec,
-    connection.isLoopback ? 'host' : 'memory',
-  )
-  ctx.effect(() => {
-    const refresh = (namespace?: string): void => {
-      if (namespace !== undefined && namespace !== spec.namespace) return
-      void controller.load()
-    }
-    const disposers = [
-      ctx.on('settings/changed', refresh),
-      ctx.on('connection/reset', () => { refresh() }),
-    ]
-    void controller.load()
-    return async () => {
-      for (const dispose of disposers) dispose()
-      await controller.dispose()
-    }
-  }, `runtime: ${spec.namespace} settings scope`)
-  return controller
-}