dsh-git-ui 0.1.0 → 0.1.2

package/src/adapters/dsh/types/cordis.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Type shim for `@deepseek-ai/cordis`.
+ *
+ * The npm ecosystem does not carry the full dsh package chain (`@deepseek-ai/cordis`
+ * depends on unpublished packages), so this package cannot install cordis as a
+ * dev dependency. At runtime the host dsh installation provides the real cordis
+ * through peer dependency resolution; this file only supplies the compile-time
+ * surface used by dsh-git-ui (shapes copied from the deepseek-harness vendor
+ * tree, 0.1.0-rc.x). Keep this file in sync with the subset actually used.
+ */
+declare module '@deepseek-ai/cordis' {
+  /** Minimal Context surface used by host/client halves. */
+  export interface Context {
+    readonly root: Context
+    /** Service registry reflection (service list for gateway SRC discovery). */
+    readonly reflect: {
+      readonly props: Record<string, { type?: string; [key: string]: unknown }>
+      provide(name: string, value: unknown, check?: unknown): void
+    }
+    /** Look up an optional service by key (undefined when not provided). */
+    get<T = unknown>(key: string): T | undefined
+    /** Declare services this plugin needs before activation. */
+    inject(keys: readonly string[], callback: (ctx: Context) => void): void
+    /** Register a side effect with auto-cleanup on fiber dispose. */
+    effect(callback: () => void | (() => void | Promise<void>), label?: string): void
+    /** Subscribe to an application event; returns an unsubscribe function. */
+    on<K extends string>(event: K, listener: (...args: never[]) => void): (() => void) | void
+    /** Start a plugin fiber in the current context. */
+    plugin(plugin: unknown, config?: unknown): Promise<unknown> & { dispose(): Promise<void> }
+    [key: string]: unknown
+  }
+
+  /** Base class for services that expose a named API on `ctx`. */
+  export abstract class Service<out T = never> {
+    static readonly init: unique symbol
+    static readonly check: unique symbol
+    static readonly config: unique symbol
+    static readonly invoke: unique symbol
+    static readonly extend: unique symbol
+    static readonly tracker: unique symbol
+    static readonly resolveConfig: unique symbol
+    /** The service name this instance is registered under. */
+    public name!: string
+    /** Owning context (registered via `super(ctx, name)`). */
+    readonly ctx: Context
+    constructor(ctx: Context, name: string)
+  }
+}

package/src/adapters/dsh/types/typert-protocol.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Type shim for `@deepseek-ai/dsh-typert-protocol`.
+ *
+ * Same rationale as `cordis.d.ts`: the runtime implementation is provided by the
+ * host dsh installation (peer dependency); this file supplies the compile-time
+ * surface used by dsh-git-ui (shapes copied from the deepseek-harness
+ * `packages/typert/protocol` source, 0.1.0-rc.x).
+ */
+declare module '@deepseek-ai/dsh-typert-protocol' {
+  import type { Context, Service } from '@deepseek-ai/cordis'
+
+  /** Visible declaration that one Service participates in Typert Gateway export. */
+  export interface TypertGatewayBinding<ServiceT extends object = object> {
+    readonly service: ServiceT
+    readonly serviceKey: string
+    readonly namespace: string
+  }
+
+  /** Cordis Service base that exposes its registered name through Typert Gateway. */
+  export abstract class TypertRemoteService<out T = never> extends Service<T> {
+    /** Visible binding consumed by the Gateway's source-mode discovery. */
+    readonly typertRemote: TypertGatewayBinding<this>
+    protected constructor(ctx: Context, serviceKey: string, options?: { namespace?: string })
+  }
+
+  /** Standard method decorator marking a Remote endpoint. */
+  export type RemoteMethodDecorator = <This extends object, Args extends unknown[], Result>(
+    method: (this: This, ...args: Args) => Result,
+    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>,
+  ) => void
+
+  /** Mark one public instance method as a direct Remote invocation. */
+  export function Remote(exportName: string): RemoteMethodDecorator
+
+  /** Read Remote markers attached to a live Service by decorator initializers. */
+  export function remoteMethods(service: object): readonly {
+    readonly method: string
+    readonly exportName?: string
+    readonly invocation: { readonly kind: 'direct' } | { readonly kind: 'context'; readonly context: string }
+  }[]
+
+  /** One codec for a Remote parameter/result (strict = zod-validated). */
+  export interface TypertCodec {
+    readonly mode: 'strict'
+    readonly typeSymbol: string
+    readonly schema: { parse(value: unknown): unknown }
+  }
+
+  /** One Remote method descriptor inside a contribution. */
+  export interface InvocationDescriptor {
+    readonly id: string
+    readonly service: string
+    readonly namespace: string
+    readonly method: string
+    readonly invocation: { readonly kind: 'direct' } | { readonly kind: 'context'; readonly context: string; readonly wire: string }
+    readonly parameters: readonly {
+      readonly name: string
+      readonly wire: string
+      readonly source: 'json'
+      readonly codec: TypertCodec
+    }[]
+    /**
+     * Optional caller-supplied cancellation slot: the descriptor carries an
+     * AbortSignal in the trailing business position, propagated over the
+     * carrier so an aborted call also aborts the host-side work.
+     */
+    readonly cancellation?: { readonly parameter: 'signal' }
+    readonly result: TypertCodec
+  }
+
+  /** Client-side contribution mounted via `ctx.remote.$mount`. */
+  export interface TypertRemoteContribution {
+    readonly package: string
+    readonly descriptors: readonly InvocationDescriptor[]
+  }
+
+  /** The `remote` service face mounted by the api-gateway client half. */
+  export interface TypertClientRemote {
+    $mount(contribution: TypertRemoteContribution): Promise<() => Promise<void>>
+  }
+}

package/src/adapters/dsh/types/ui-primitives.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Type shim for `@deepseek-ai/dsh-client-ui-primitives`.
+ *
+ * Platform module (externalized in the client bundle, provided by the host
+ * loader table); this package only needs the `Modal` dialog, the `Button`
+ * atom and the transient `Toast` banner, so the surface is declared here by
+ * hand (mirrored from the ui-primitives source, 0.1.0-rc.x).
+ */
+declare module '@deepseek-ai/dsh-client-ui-primitives' {
+  import type { ButtonHTMLAttributes, ReactNode } from 'react'
+
+  /** Controlled full-viewport dialog over a blurred mask (Escape/mask close). */
+  export function Modal(props: {
+    open: boolean
+    onClose: () => void
+    title: string
+    closeLabel?: string
+    description?: string
+    children?: ReactNode
+    footer?: ReactNode
+    className?: string
+    contentClassName?: string
+    headless?: boolean
+  }): ReactNode
+
+  /** Token-styled button atom (native button attributes pass through). */
+  export function Button(props: {
+    variant?: 'primary' | 'ghost' | 'outline' | 'toolbar'
+    size?: 'md' | 'sm'
+    icon?: ReactNode
+    className?: string | undefined
+    children?: ReactNode
+  } & ButtonHTMLAttributes<HTMLButtonElement>): ReactNode
+
+  /**
+   * Transient top-center banner: slides in, holds ~3s, fades out, then calls
+   * `onDone` so the owner can unmount it.
+   */
+  export function Toast(props: {
+    text: string
+    icon?: ReactNode
+    anchor?: HTMLElement | null
+    onDone: () => void
+  }): ReactNode
+}

package/src/adapters/dsh/ui-primitives.ts

@@ -0,0 +1,16 @@
+/**
+ * dsh UI 基础组件适配：将 `@deepseek-ai/dsh-client-ui-primitives` 的
+ * Modal / Button / Toast 包装为我们的 `UIPrimitives` 接口。
+ *
+ * 本文件是 client 端**唯一** import `@deepseek-ai/dsh-client-ui-primitives`
+ * 的地方。dsh 升级导致组件 API 变更时，只需修改此文件。
+ */
+import { Modal as DshModal, Button as DshButton, Toast as DshToast } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { UIPrimitives } from '../../contracts/ui-primitives.ts'
+
+/** dsh 宿主提供的 UI 基础组件实现。 */
+export const dshUIPrimitives: UIPrimitives = {
+  Modal: DshModal,
+  Button: DshButton,
+  Toast: DshToast,
+}

package/src/client/GitCenter.tsx

@@ -16,7 +16,7 @@
  */
 import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import type { CSSProperties, JSX, MouseEvent as ReactMouseEvent } from 'react'
-import { Button, Modal, Toast } from '@deepseek-ai/dsh-client-ui-primitives'
+import { useUI } from '../contracts/ui-context.tsx'
 import type {
   GitAction, GitActionResult, GitBranch, GitChange, GitFileStat,
   GitQueryRequest, GitSnapshot,
@@ -78,6 +78,7 @@ function timeAgo(iso: string, now: number, t: (key: GitKey) => string): string {
 export function GitCenter({
   open, onClose, snapshot, run, query, t, openRequest = null,
 }: GitCenterProps): JSX.Element | null {
+  const { Modal, Button, Toast } = useUI()
   const [tab, setTab] = useState<TabKey>('changes')
   const [busy, setBusy] = useState(false)
   const [feedback, setFeedback] = useState<Feedback>(null)
@@ -192,6 +193,7 @@ function ChangesTab({
   t: (key: GitKey) => string
   openRequest: { path: string; base: 'worktree' | 'staged' } | null
 }): JSX.Element {
+  const { Button } = useUI()
   const [selected, setSelected] = useState<ReadonlySet<string>>(new Set())
   const [message, setMessage] = useState('')
   const [armed, setArmed] = useState<string | 'all' | null>(null)

package/src/client/GitPill.tsx

@@ -15,8 +15,9 @@ import { useEffect, useLayoutEffect, useRef, useState } from 'react'
 import { createPortal } from 'react-dom'
 import type { JSX } from 'react'
 import { completedTurnCount, type TurnSignalSnapshot } from './turn-signal.ts'
-import { Button } from '@deepseek-ai/dsh-client-ui-primitives'
+import { useUI } from '../contracts/ui-context.tsx'
 import type { GitObservable, GitQueryOutcome, GitView } from './controller.ts'
+import type { GitInjected } from '../contracts/client-platform.ts'
 import { GitCenter } from './GitCenter.tsx'
 import { fileIconForPath, FolderIcon, AlertIcon, CloseIcon, RollbackIcon, StageIcon, UnstageIcon } from './icons.tsx'
 import type { GitAction, GitActionResult, GitBranch, GitOperationErrorCode, GitQueryRequest } from '../host/types.ts'
@@ -31,20 +32,8 @@ import * as css from './styles.ts'
 // Inject the plugin's interaction styles once (idempotent, browser-only).
 css.ensureGlobalCss()
 
-/** Injected business face of the header utility entry. */
-export interface GitInjected {
-  hooks: {
-    /** The owning Session's git view source. The slot runtime binds this
-     * observable into the `useGit` selector hook the component consumes. */
-    git: GitObservable<GitView>
-  }
-  /** Force an immediate re-check (same path as polling). */
-  refresh: () => Promise<void>
-  /** Execute one management action (host returns a fresh snapshot). */
-  run: (action: GitAction) => Promise<GitActionResult>
-  /** Run one read-only query (history / diff / show / branches). */
-  query: (query: GitQueryRequest['query']) => Promise<GitQueryOutcome>
-}
+// Re-export for backward compatibility
+export type { GitInjected } from '../contracts/client-platform.ts'
 
 /** Selector hook shape the slot runtime binds from `hooks.git`. */
 export type UseGit = <S = GitView>(
@@ -139,6 +128,7 @@ function GitPopupBody({
   query: (query: GitQueryRequest['query']) => Promise<GitQueryOutcome>
   t: (key: GitKey) => string
 }): JSX.Element {
+  const { Button } = useUI()
   const now = Date.now()
   const s = view.snapshot
   const branchLabel = s.branch === null ? `(${t('pill.detached')})` : s.branch

package/src/client/controller.ts

@@ -5,44 +5,12 @@
  * connection reset, `dispose()` on slot teardown (clears the timer and
  * rejects nothing — in-flight work settles into a withdrawn view).
  */
-import type { GitActionResult, GitActionRequest, GitQueryRequest, GitQueryResponse, GitSnapshot, GitSnapshotFailure, GitSnapshotRequest, GitSnapshotResult } from '../host/types.ts'
+import type { GitActionResult, GitActionRequest, GitQueryRequest, GitQueryResponse, GitSnapshot, GitSnapshotRequest, GitSnapshotResult } from '../host/types.ts'
+import type { GitObservable, GitView, GitRemoteLike, GitQueryOutcome, RemoteEnvelope } from '../contracts/client-platform.ts'
 
-/** The observable view contract components consume (useSyncExternalStore shape). */
-export interface GitObservable<V> {
-  subscribe(listener: () => void): () => void
-  getSnapshot(): V
-}
-
-export type GitView =
-  | { readonly state: 'no-cwd' }
-  | { readonly state: 'cold' }
-  | { readonly state: 'loading' }
-  | { readonly state: 'ready'; readonly snapshot: GitSnapshot }
-  | { readonly state: 'error'; readonly error: GitSnapshotFailure }
-
-/**
- * RPC envelope returned by every mounted Remote method (see the api-gateway
- * client's `invoke`): `ok` reflects the transport/gateway outcome, and the
- * business return value of the host method rides inside `value`. For
- * `gitInfo/snapshot` that business value is a `GitSnapshotResult` — so a
- * successful call resolves to `{ ok: true, value: { ok: true, value:
- * GitSnapshot } }`.
- */
-export type GitRemoteEnvelope<T> =
-  | { readonly ok: true; readonly value: T }
-  | { readonly ok: false; readonly error: { readonly code?: string; readonly message?: string; readonly details?: unknown } }
-
-/** Structural face of the mounted gitInfo Remote namespace. */
-export interface GitRemoteLike {
-  snapshot(request: GitSnapshotRequest): Promise<GitRemoteEnvelope<GitSnapshotResult>>
-  run(request: GitActionRequest): Promise<GitRemoteEnvelope<GitActionResult>>
-  query(request: GitQueryRequest): Promise<GitRemoteEnvelope<GitQueryResponse>>
-}
-
-/** Simplified query outcome for the UI (envelope + business errors unwrapped). */
-export type GitQueryOutcome =
-  | { readonly ok: true; readonly value: Extract<GitQueryResponse, { ok: true }>['value'] }
-  | { readonly ok: false; readonly message: string }
+// Re-export for backward compatibility — 其他模块仍可从 controller 导入这些类型
+export type { GitObservable, GitView, GitRemoteLike, GitQueryOutcome } from '../contracts/client-platform.ts'
+export type { RemoteEnvelope as GitRemoteEnvelope } from '../contracts/client-platform.ts'
 
 /** Failure codes that mean "no working directory to watch" — degrade to a
  * low-frequency probe instead of a normal poll. */

package/src/client/index.ts

@@ -1,151 +1,54 @@
 /**
- * Git status widget — client half entry.
+ * dsh-git-ui client 入口：Cordis 约定字段 + 委托。
  *
- * The bundle is a ModuleLoader closure: `factory(require)` returns the plugin
- * shape `{ name, inject, apply }`; the framework activates it once the listed
- * services exist.
- *
- * Service-access contract (verified against cordis 0.1.0-rc.x): the gitInfo
- * namespace service is provided by OUR OWN `ctx.remote.$mount(gitInfoRemote)`
- * inside apply, so the main fiber can never declare `remote.gitInfo` in its
- * `inject` — cordis would wait for the service before running apply, and the
- * service only appears once apply runs (deadlock). Conversely, accessing
- * `ctx.remote.gitInfo` without the inject declaration throws cordis's
- * "cannot get property ... without inject". The consumer therefore lives in a
- * CHILD fiber created after the mount: its inject declares `remote.gitInfo`,
- * and by the time it activates the service already exists — no wait, no
- * access violation. (In-repo plugins like ui-message-feedback can inject
- * their namespace directly because a separate assembly package mounts it; a
- * standalone plugin mounts its own.)
+ * 导出 Cordis 插件约定字段（`inject` / `name` / `apply`）；`apply` 内部
+ * 将 Cordis Context 适配为 `ClientPlatform` 接口后委托给纯业务函数。
+ * dsh 适配逻辑在 `adapters/dsh/client-adapter.ts`。
  */
-import type { TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol'
-import { GitController, type GitRemoteLike } from './controller.ts'
+import { createElement, type ReactNode } from 'react'
+import { GitPill, type GitPillProps } from './GitPill.tsx'
+import { UIPrimitivesProvider } from '../contracts/ui-context.tsx'
+import { dshUIPrimitives } from '../adapters/dsh/ui-primitives.ts'
+import { adaptDshClientContext, type DshClientContext } from '../adapters/dsh/client-adapter.ts'
+import { activatePlugin, type PluginDependencies } from '../contracts/plugin-activation.ts'
+import { GitController } from './controller.ts'
 import { gitInfoRemote } from './remote.ts'
-import { GitPill, type GitInjected } from './GitPill.tsx'
 import { en, zh } from './locales.ts'
 
-/** Structural face of the browser plugin context (host-provided). */
-interface ClientContext {
-  get<T = unknown>(key: string): T | undefined
-  /** Subscribe to an application event (auto-cleaned on fiber dispose). */
-  on(event: string, listener: (...args: never[]) => void): (() => void) | void
-  /** Register a side effect with auto-cleanup on fiber dispose. */
-  effect(callback: () => void | (() => void | Promise<void>), label?: string): void
-  /** Register a nested cordis plugin (fiber) under this context. */
-  plugin(definition: {
-    readonly name: string
-    readonly inject: readonly string[]
-    apply: (ctx: ClientContext) => void | Promise<void>
-  }): Promise<unknown>
-  /** The typed Client Remote mount + mounted namespaces. */
-  remote: {
-    $mount(contribution: TypertRemoteContribution): Promise<() => Promise<void>>
-    gitInfo: GitRemoteLike
-  }
-  /** The slot registry (ui-slots). */
-  slots: {
-    inject(slotName: string, provider: () => (() => void) | void): void
-    register(
-      options: {
-        readonly name: string
-        readonly id: string
-        readonly order?: number
-        readonly locale?: string
-        readonly inject: (sessionId: string) => GitInjected
-      },
-      component: unknown,
-    ): () => void
-  }
-  /** The locale service (ui-locale). */
-  locale: {
-    register(namespace: string, dictionaries: { readonly zh: Record<string, string>; readonly en: Record<string, string> }): void
-  }
-  [key: string]: unknown
-}
-
 /**
- * Required services: slot registry, Remote base (gateway client), and copy.
+ * Cordis 插件约定：声明需要的服务。
  *
- * `remote.gitInfo` is deliberately NOT listed here — see the module comment:
- * the namespace is mounted by our own apply, so injecting it would deadlock.
- * The child fiber that consumes it declares it instead (after the mount).
+ * `remote.gitInfo` 不在此列出——它由我们自己的 apply 挂载，
+ * 若在 inject 中声明会导致死锁（服务在 apply 执行后才存在）。
  */
 export const inject = ['slots', 'remote', 'locale'] as const
 
-/** Plugin identity: the factory handoff returns this plus the exports above. */
+/** 插件标识。 */
 export const name = 'dsh-git-ui'
 
-/**
- * Plugin body: register copy, mount the gitInfo Remote, then host the header
- * utility in a child fiber that may legitimately access `remote.gitInfo`.
- */
-export async function apply(ctx: ClientContext): Promise<void> {
-  ctx.effect(() => ctx.locale.register('git', { zh, en }), 'dsh-git-ui: dictionaries')
-
-  // Mount first — the namespace service only exists after this resolves.
-  await ctx.remote.$mount(gitInfoRemote)
-
-  const controllers = new Map<string, GitController>()
-  const faces = new Map<string, GitInjected>()
+/** 插件入口使用的 UI 基础组件实现（dsh 宿主提供）。 */
+const uiPrimitives = dshUIPrimitives
 
-  // Consumer fiber: `remote.gitInfo` is declared in ITS inject list, so the
-  // access inside the controller factory is legal; the service is already
-  // provided by the mount above, so activation does not wait (no deadlock).
-  const child = ctx.plugin({
-    name: 'dsh-git-ui:git',
-    inject: ['slots', 'remote.gitInfo'],
-    apply: (sub) => {
-      const controllerFor = (sessionId: string): GitController => {
-        let controller = controllers.get(sessionId)
-        if (controller === undefined) {
-          controller = new GitController(sub.remote.gitInfo, sessionId)
-          controllers.set(sessionId, controller)
-        }
-        return controller
-      }
-
-      sub.slots.inject('conversation.session.header.utilities', () => {
-        const dispose = sub.slots.register({
-          name: 'conversation.session.header.utilities',
-          id: 'git',
-          order: 10,
-          locale: 'git',
-          inject: (sessionId): GitInjected => {
-            // Per-session stable face: the slot runtime may re-invoke the
-            // inject factory on every render, and components depend on the
-            // `refresh` reference staying stable (a fresh arrow function per
-            // call would re-run mount effects and loop: refresh → view
-            // change → re-render → new refresh → refresh …). Cache the face
-            // so the same controller (and its bound refresh/run) is always
-            // handed out per session.
-            let face = faces.get(sessionId)
-            if (face === undefined) {
-              const controller = controllerFor(sessionId)
-              face = {
-                hooks: { git: controller as GitInjected['hooks']['git'] },
-                refresh: () => controller.refresh(),
-                run: (action) => controller.run(action),
-                query: (query) => controller.query(query),
-              }
-              faces.set(sessionId, face)
-            }
-            return face
-          },
-        }, GitPill)
-        return () => {
-          dispose()
-          for (const controller of controllers.values()) controller.dispose()
-          controllers.clear()
-          faces.clear()
-        }
-      })
-    },
-  })
-  await child
+/** 包裹 GitPill，注入 UI 基础组件上下文。 */
+function GitPillWithUI(props: GitPillProps): ReactNode {
+  return createElement(UIPrimitivesProvider, { value: uiPrimitives }, createElement(GitPill, props))
+}
 
-  // A reconnect can only invalidate what was already read; a cold Session
-  // stays cold until something asks for it.
-  ctx.on('connection/reset', () => {
-    for (const controller of controllers.values()) controller.resync()
-  })
+/**
+ * Cordis 插件入口：适配 Context 后委托给纯业务函数。
+ *
+ * dsh 升级导致插件 API 变更时，只需更新 `adapters/dsh/client-adapter.ts`
+ * 中的 `DshClientContext` 接口和 `adaptDshClientContext` 实现。
+ */
+export async function apply(ctx: DshClientContext): Promise<void> {
+  const platform = adaptDshClientContext(ctx)
+  
+  // 提供插件依赖
+  const deps: PluginDependencies = {
+    remoteContribution: gitInfoRemote,
+    locales: { zh, en },
+    createController: (remote, sessionId) => new GitController(remote, sessionId),
+  }
+  
+  await activatePlugin(platform, deps, GitPillWithUI)
 }

package/src/client/remote.ts

@@ -8,7 +8,7 @@
  * sync by parsing host-typed samples through these schemas.
  */
 import { z } from 'zod'
-import type { TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol'
+import type { RemoteContribution } from '../contracts/client-platform.ts'
 
 export const gitCommitSchema = z.object({
   hash: z.string(),
@@ -152,7 +152,7 @@ export const gitQueryRequestSchema = z.object({
 })
 
 /** The contribution mounted into `ctx.remote` by the client plugin body. */
-export const gitInfoRemote: TypertRemoteContribution = {
+export const gitInfoRemote: RemoteContribution = {
   package: 'dsh-git-ui',
   descriptors: [
     {

package/src/contracts/client-platform.ts

@@ -0,0 +1,147 @@
+/**
+ * Client 插件平台契约：业务层定义「我需要宿主做什么」，适配层实现「宿主怎么做」。
+ *
+ * 当 dsh 升级导致 Cordis / typert / slot API 变更时，只需更新
+ * `adapters/dsh/client-adapter.ts`，本文件及业务代码零改动。
+ */
+import type { GitAction, GitActionResult, GitActionRequest, GitQueryRequest, GitQueryResponse, GitSnapshotRequest, GitSnapshotResult } from '../host/types.ts'
+
+/** 国际化字典：中英双语。 */
+export interface LocaleDicts {
+  readonly zh: Record<string, string>
+  readonly en: Record<string, string>
+}
+
+/** RPC 信封：传输层结果（ok/error）包裹业务返回值。 */
+export type RemoteEnvelope<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: { readonly code?: string; readonly message?: string; readonly details?: unknown } }
+
+/** Git Remote 服务接口：客户端通过此接口与宿主 RPC 通信。 */
+export interface GitRemoteLike {
+  snapshot(request: GitSnapshotRequest): Promise<RemoteEnvelope<GitSnapshotResult>>
+  run(request: GitActionRequest): Promise<RemoteEnvelope<GitActionResult>>
+  query(request: GitQueryRequest): Promise<RemoteEnvelope<GitQueryResponse>>
+}
+
+/** 简化的查询结果：解包 RPC 信封和业务错误。 */
+export type GitQueryOutcome =
+  | { readonly ok: true; readonly value: Extract<GitQueryResponse, { ok: true }>['value'] }
+  | { readonly ok: false; readonly message: string }
+
+/** Git 视图状态：客户端组件消费的可观察快照。 */
+export type GitView =
+  | { readonly state: 'no-cwd' }
+  | { readonly state: 'cold' }
+  | { readonly state: 'loading' }
+  | { readonly state: 'ready'; readonly snapshot: import('../host/types.ts').GitSnapshot }
+  | { readonly state: 'error'; readonly error: import('../host/types.ts').GitSnapshotFailure }
+
+/** 可观察对象：useSyncExternalStore 形状。 */
+export interface GitObservable<V> {
+  subscribe(listener: () => void): () => void
+  getSnapshot(): V
+}
+
+/** Slot 注入接口：组件通过此接口与控制器交互。 */
+export interface GitInjected {
+  hooks: {
+    /** 会话的 Git 视图源。Slot 运行时将其绑定为 useGit 选择器钩子。 */
+    git: GitObservable<GitView>
+  }
+  /** 强制立即刷新（与轮询相同路径）。 */
+  refresh: () => Promise<void>
+  /** 执行一条管理操作（宿主返回新快照）。 */
+  run: (action: GitAction) => Promise<GitActionResult>
+  /** 执行一条只读查询（历史/差异/分支等）。 */
+  query: (query: GitQueryRequest['query']) => Promise<GitQueryOutcome>
+}
+
+/** Slot 条目描述符：注册到宿主 slot 系统的一条记录。 */
+export interface SlotEntryDescriptor {
+  /** Slot 名称（如 'conversation.session.header.utilities'）。 */
+  readonly name: string
+  /** 条目 ID（同一 slot 内唯一）。 */
+  readonly id: string
+  /** 渲染顺序（升序）。 */
+  readonly order?: number
+  /** 国际化命名空间。 */
+  readonly locale?: string
+  /** 注入工厂：每次渲染调用，返回该条目的业务接口。 */
+  readonly inject: (sessionId: string) => GitInjected
+}
+
+/**
+ * Client 平台能力：业务层需要的全部宿主服务。
+ *
+ * 设计原则：
+ *   - 只声明「做什么」，不暴露「怎么做」
+ *   - 方法签名取业务层实际使用的最小集
+ *   - 返回类型为业务层需要的接口，非宿主原始类型
+ */
+export interface ClientPlatform {
+  /** 注册国际化字典。 */
+  registerLocale(namespace: string, dicts: LocaleDicts): void
+
+  /**
+   * 挂载 Remote 贡献并返回命名空间服务对象。
+   *
+   * 挂载完成后，返回的对象可用于创建业务控制器。适配层负责处理
+   * 宿主的挂载机制（如 Cordis 的 child fiber + inject 模式）。
+   */
+  mountRemoteAndGetService(contribution: RemoteContribution, namespace: string): Promise<GitRemoteLike>
+
+  /**
+   * 注册一个 slot 条目。
+   *
+   * 宿主负责在合适的时机渲染该条目。返回释放函数，调用后注销条目。
+   */
+  registerSlotEntry(options: SlotEntryDescriptor, component: unknown): () => void
+
+  /** 订阅应用事件。返回取消订阅函数（若宿主支持）。 */
+  onEvent(event: string, listener: (...args: unknown[]) => void): (() => void) | void
+
+  /**
+   * 注册副作用。回调可返回清理函数，在插件卸载时调用。
+   * 用于管理定时器等需要生命周期管理的资源。
+   */
+  effect(callback: () => void | (() => void | Promise<void>), label?: string): void
+}
+
+/**
+ * Remote 贡献声明：描述一个命名空间下的全部 RPC 方法。
+ *
+ * 本接口是业务层对 RPC 声明的最小需求。适配层负责将其转换为宿主
+ * 的具体格式（如 TypertRemoteContribution）。
+ */
+export interface RemoteContribution {
+  readonly package: string
+  readonly descriptors: readonly RemoteMethodDescriptor[]
+}
+
+/** 单条 RPC 方法描述。 */
+export interface RemoteMethodDescriptor {
+  readonly id: string
+  readonly service: string
+  readonly namespace: string
+  readonly method: string
+  readonly invocation: { readonly kind: 'direct' } | { readonly kind: 'context'; readonly context: string; readonly wire: string }
+  readonly cancellation?: { readonly parameter: 'signal' }
+  readonly parameters: readonly RemoteParameterDescriptor[]
+  readonly result: RemoteCodecDescriptor
+}
+
+/** RPC 参数描述。 */
+export interface RemoteParameterDescriptor {
+  readonly name: string
+  readonly wire: string
+  readonly source: 'json'
+  readonly codec: RemoteCodecDescriptor
+}
+
+/** RPC 编解码器描述。 */
+export interface RemoteCodecDescriptor {
+  readonly mode: 'strict'
+  readonly typeSymbol: string
+  readonly schema: { parse(value: unknown): unknown }
+}