dsh-plugin-dev-kb 1.0.0

package/kb/site/en/reference/subsystems/typert.md

@@ -0,0 +1,339 @@
+---
+editSource: "docs/subsystems/typert.md"
+outline: [2,3]
+---
+
+# Typert remote calls
+
+Types shared by generated Remote artifacts, the Host Gateway, and consumer API assemblies. The [Typert Gateway Agent Note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) owns the architecture and transport decisions; this page records the literal public contracts from [`dsh-typert-protocol`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/typert/protocol/src/types.ts) and [`dsh-api-gateway`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/api/gateway/src/types.ts).
+
+## Lookup and Context declarations
+
+Business-object packages extend two empty maps through declaration merging. A lookup associates one Host object type with its wire identity; a Context declaration associates one scoped Context kind with its wire identity. Generated descriptors name these keys, while runtime providers supply the live resolution behavior.
+
+```ts type-equiv
+/** Merge-extensible Host object lookup declarations. */
+interface TypertLookupMap {}
+```
+
+```ts type-equiv
+/** Merge-extensible scoped Context declarations. */
+interface TypertContextMap {}
+```
+
+The registry retains a lookup's wire declaration after its resolver unloads. SRC discovery therefore continues to classify the parameter as a lookup and fails unavailable instead of accepting the wire value as an ordinary business object.
+
+```ts type-equiv
+/** Stable wire declaration retained after a lookup provider unloads. */
+interface TypertLookupDefinition {
+  /** Merge-declared lookup key. */
+  readonly key: string
+  /** Source parameter name recognized by the SRC weak parser. */
+  readonly parameter: string
+  /** Wire field replacing the Host object parameter. */
+  readonly wire: string
+  /** Canonical Host type symbol used by strict generation. */
+  readonly hostTypeSymbol: string
+  /** Canonical wire type symbol used by strict generation. */
+  readonly wireTypeSymbol: string
+}
+```
+
+## Invocation descriptors
+
+An `InvocationDescriptor` is local reflection, not a wire message. Host and consumer builds generate corresponding descriptors; the request sends only the endpoint and named `args`. Strict codecs carry generated schemas, while SRC codecs enforce JSON-safe values without structural type recovery. Cancellation is an out-of-band carrier signal injected after business parameters and never enters `args`.
+
+```ts type-equiv
+/** Codec attached to one invocation parameter or result. */
+type TypertCodec =
+  | {
+    readonly mode: 'strict'
+    readonly typeSymbol: string
+    readonly schema: TypertSchema
+  }
+  | {
+    readonly mode: 'src-json'
+  }
+```
+
+```ts type-equiv
+/** One ordered business parameter in a Remote invocation. */
+interface InvocationParameterDescriptor {
+  /** Source-level parameter name. */
+  readonly name: string
+  /** Required key in the wire `args` object. */
+  readonly wire: string
+  /** Whether the value is JSON or requires a registered Host lookup. */
+  readonly source: 'json' | 'lookup'
+  /** Lookup key when `source` is `lookup`. */
+  readonly lookup?: string
+  /** Boundary codec for the wire representation. */
+  readonly codec: TypertCodec
+  /** Missing wire fields decode to `undefined` only for an explicitly declared `T | undefined`. */
+  readonly acceptsUndefined?: true
+}
+```
+
+```ts type-equiv
+/** Carrier-independent description of one exported method invocation. */
+interface InvocationDescriptor {
+  /** Globally stable generated identity. */
+  readonly id: string
+  /** Cordis service key owning the method. */
+  readonly service: string
+  /** Wire namespace, defaulting to the service key. */
+  readonly namespace: string
+  /** Public instance method name. */
+  readonly method: string
+  /** Service member invoked when the exported method name is an alias. */
+  readonly implementation?: string
+  /** Receiver selection mode. */
+  readonly invocation:
+    | { readonly kind: 'direct' }
+    | {
+      readonly kind: 'context'
+      readonly context: string
+      readonly wire: string
+      readonly codec: TypertCodec
+    }
+  /** Optional consuming-Context projection for one direct lookup parameter. */
+  readonly scope?: {
+    /** Context kind whose Client binder supplies the identity. */
+    readonly context: string
+    /** Lookup parameter wire field replaced by the Context identity. */
+    readonly wire: string
+  }
+  /** Ordered business parameters. */
+  readonly parameters: readonly InvocationParameterDescriptor[]
+  /** Transport cancellation injected after business parameters instead of entering wire args. */
+  readonly cancellation?: {
+    /** Reserved final Host method parameter. */
+    readonly parameter: 'signal'
+  }
+  /** Codec for the resolved method result. */
+  readonly result: TypertCodec
+  /** Source declaration used only for diagnostics. */
+  readonly sourceLocation?: InvocationSourceLocation
+}
+```
+
+## Typert registry
+
+`ctx.typert` separates current-environment descriptors, explicitly selected Remote contributions, lookup providers, and scoped Context providers. A lookup provider owns the stable wire declaration and default resolver; Host composition can configure an effect-scoped synchronous or asynchronous resolver for the same key, and unloading that configuration restores the default policy. Registrations are Cordis-owned effects and return awaitable disposers.
+
+```ts type-equiv
+/** Minimal Typert runtime consumed through dependency inversion. */
+interface TypertRegistryContract {
+  readonly local: TypertLocalRegistry
+  readonly remotes: TypertRemoteRegistry
+  readonly lookups: TypertLookupRegistry
+  readonly contexts: TypertContextRegistry
+}
+```
+
+Generated consumer declarations merge direct namespaces into the map inherited by `TypertClientRemote`.
+
+```ts type-equiv
+/** Merge-extensible direct namespace surface generated for Client Remote services. */
+interface TypertRemoteNamespaceMap {}
+```
+
+## Host Gateway
+
+Connection decodes its carrier envelope before calling `ctx.typertGateway`. The request carries exact named wire fields and the carrier's cancellation signal separately; infrastructure and boundary failures use the Gateway's in-process error taxonomy, ordinary exceptions are folded by the RPC adapter into the transport's `internal` error code, and existing RPC errors carried by lookup policy through `TypertLookupFailure` are returned unchanged.
+
+```ts type-equiv
+/** One Remote method request after a carrier has decoded its envelope. */
+interface InvokeRemoteRequest {
+  /** Remote namespace selected by the generated descriptor. */
+  readonly namespace: string
+  /** Exported Service method name. */
+  readonly method: string
+  /** Named wire values; fields must exactly match the descriptor. */
+  readonly args: Readonly<Record<string, unknown>>
+  /** Carrier or direct-caller cancellation injected only into cancellation-aware methods. */
+  readonly signal?: AbortSignal
+}
+```
+
+```ts type-equiv
+/** Stable infrastructure and boundary failures emitted before or after business execution. */
+type TypertGatewayErrorCode =
+  | 'ambiguous-endpoint'
+  | 'arguments-invalid'
+  | 'binding-invalid'
+  | 'context-failed'
+  | 'context-not-found'
+  | 'context-unavailable'
+  | 'definition-unavailable'
+  | 'input-invalid'
+  | 'invocation-unavailable'
+  | 'lookup-failed'
+  | 'lookup-not-found'
+  | 'lookup-unavailable'
+  | 'method-unavailable'
+  | 'provider-mismatch'
+  | 'result-invalid'
+  | 'service-unavailable'
+  | 'signature-invalid'
+```
+
+```ts type-equiv
+/** Host dispatcher consumed by Connection adapters. */
+interface TypertGateway {
+  /**
+   * Invoke one live Remote method without assuming a carrier or response envelope.
+   * @param request - decoded endpoint and named wire arguments.
+   * @returns the validated business result.
+   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
+   */
+  invoke(request: InvokeRemoteRequest): Promise<unknown>
+}
+```
+
+## Consumer Remote
+
+`ctx.remote` exposes only namespaces contributed by imported `/remote` artifacts. `$mount()` installs generated descriptors and concrete methods as one fiber-owned operation. Each namespace is a traced `remote.<namespace>` Cordis child Service whose lifetime spans its mounted methods; no JavaScript Proxy or Host business Service type enters the consumer.
+
+```ts type-equiv
+/** Client Remote capability implemented by the Gateway and consumed by Remote assemblies. */
+interface TypertClientRemote extends TypertRemoteNamespaceMap {
+  /**
+   * Mount one generated Host-for-Client contribution in the caller's fiber.
+   * @param contribution - explicitly selected Remote package artifact.
+   * @returns disposer after namespace services and concrete methods are ready.
+   */
+  $mount(contribution: TypertRemoteContribution): Promise<TypertDisposer>
+  /**
+   * Subscribe to one forwarded Host event; delivery is one-way, in registration
+   * order, and isolates a throwing listener from the rest.
+   * @template Event - forwarded event name selected by the Host assembly.
+   * @param event - forwarded Host event name, unchanged on the wire.
+   * @param listener - receives the Host's argument list as declared by Cordis `Events`.
+   * @returns disposer owned by the calling fiber.
+   */
+  $on<Event extends TypertRemoteEvent>(event: Event, listener: Events[Event]): () => void
+  /**
+   * Hand one decoded forwarded frame to the subscription table. The carrier
+   * owning the Host frame sink calls this; a consumer subscribes with
+   * {@link TypertClientRemote.$on} and never calls it.
+   *
+   * `event` is a plain string because this is the wire boundary: the name is
+   * whatever the Host assembly's allowlist selected, and one nobody subscribed
+   * to is dropped silently.
+   * @param event - forwarded Host event name, exactly as the Host emitted it.
+   * @param args - the Host argument list, already JSON-decoded.
+   */
+  $dispatch(event: string, args: readonly unknown[]): void
+}
+```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis API
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxapiproxy--apiproxy"></a>
+
+### `ctx.apiProxy` — `ApiProxy`
+
+Root interface of the unified API. New client-request domain = one new file pair + one field here + one map row.
+
+```ts cordis-catalog
+/**
+ * Response entry for server requests; not a domain method.
+ * @param message - Client response carrying the server request's rpcId.
+ * @returns Transport receipt for the response delivery.
+ */
+respond(message: ClientResponse): Promise<RpcReceipt>
+```
+
+Source: [`packages/host/apiproxy/src/api/index.ts:22`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/host/apiproxy/src/api/index.ts)
+
+<a id="ctxtypert--typertregistry"></a>
+
+### `ctx.typert` — `TypertRegistry`
+
+Registry of generated schemas, package reflection, invocations, and Remote dependency providers.
+
+```ts cordis-catalog
+/**
+ * Register one generated contribution atomically for the calling fiber.
+ * Duplicate package-face identities, schemas, invocation ids, or endpoints
+ * reject the whole batch.
+ * @param contribution - generated schemas, reflection, and Host invocations.
+ * @returns the exact effect disposer that removes this contribution.
+ */
+register(contribution: TypertContribution): TypertDisposer
+
+/**
+ * Look up one schema by `<package>#<name>`.
+ * @param key - global schema key.
+ * @returns the live schema record, or `undefined` when absent.
+ */
+get(key: string): TypertSchemaRecord | undefined
+
+/**
+ * Resolve one required schema.
+ * @param key - global schema key.
+ * @returns the live schema record.
+ * @throws when the key is malformed, the package face is absent, or the schema is not contributed.
+ */
+resolve(key: string): TypertSchemaRecord
+
+/**
+ * Enumerate live schemas in registration order.
+ * @param filter - optional package and face restriction.
+ * @returns matching schema records.
+ */
+list(filter: TypertSchemaFilter = {}): TypertSchemaRecord[]
+
+/**
+ * Look up generated reflection for one package face.
+ * @param packageName - exact npm package name.
+ * @param face - face to query; defaults to the host runtime.
+ * @returns the live package record, or `undefined` when absent.
+ */
+getPackage(packageName: string, face: TypertFace = 'host'): TypertPackageRecord | undefined
+
+/**
+ * Enumerate generated package reflection in registration order.
+ * @param filter - optional package and face restriction.
+ * @returns matching package records.
+ */
+listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[]
+
+/**
+ * Project a live Zod schema to JSON Schema without caching the result.
+ * @param key - global schema key.
+ * @param params - Zod projection parameters.
+ * @returns a fresh JSON Schema document.
+ */
+toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema
+```
+
+Types: [TypertContribution](./invariants.md) · [TypertFace](./invariants.md) · [TypertPackageFilter](./invariants.md) · [TypertPackageRecord](./invariants.md) · [TypertSchemaFilter](./invariants.md) · [TypertSchemaRecord](./invariants.md)
+
+Source: [`packages/typert/registry/src/service.ts:446`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/typert/registry/src/service.ts)
+
+<a id="ctxtypertgateway--typertgatewayservice"></a>
+
+### `ctx.typertGateway` — `TypertGatewayService`
+
+Resolve strict generated definitions or conservative SRC markers against current Cordis Services and Typert providers.
+
+```ts cordis-catalog
+/**
+ * Invoke one live Remote method through strict generated reflection or SRC markers.
+ * @param request - decoded endpoint and exact named wire arguments.
+ * @returns the validated business result.
+ * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
+ */
+async invoke(request: InvokeRemoteRequest): Promise<unknown>
+```
+
+Source: [`packages/api/gateway/src/index.ts:90`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/api/gateway/src/index.ts)
+<!-- END GENERATED cordis-surface -->

package/kb/site/en/reference/subsystems/user-questions.md

@@ -0,0 +1,181 @@
+---
+editSource: "docs/subsystems/user-questions.md"
+outline: [2,3]
+---
+
+# User Interaction
+
+The user-questions seam of [dsh-user-questions](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/interaction/user-questions). It is the provider-neutral vocabulary a tool or permission plugin uses when it needs the human to answer before the agent can continue. UI surfaces provide the active `UserQuestionProvider`; the host runtime relays requests to its connected client.
+
+Source: [`packages/interaction/user-questions/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/interaction/user-questions/src/index.ts)
+
+## Question options
+
+`AskUserQuestionOption` contains one selectable choice. `label` is the user-facing option text and also the model-facing selected value; `description` is optional UI help text.
+
+```ts type-equiv
+/** One selectable answer offered to the user. */
+interface AskUserQuestionOption {
+  /** User-facing label. */
+  label: string
+  /** Optional extra context rendered by capable UIs. */
+  description?: string
+}
+```
+
+## Presentation intent
+
+`AskUserQuestionIntent` optionally declares a known decision kind. It is tagged on `kind` so intents can be added; a UI that does not recognise a tag renders the generic option list. An intent changes presentation only — a UI honouring it answers with the same option labels a generic UI would send, so the caller reads the same answer fields either way. `approve` names the affirmative option instead of relying on option order. `ask()` rejects the two assertions no type can carry: an `approve` naming none of its own question's options, and an intent on a question with no `detail`.
+
+```ts type-equiv
+/**
+ * A caller-declared presentation intent: the question IS this kind of
+ * decision, so a UI that recognises the tag may present it as such instead of as a
+ * generic option list. Tagged so further intents can be added; a UI that does
+ * not know a tag renders the generic flow, and the answer encoding is identical
+ * either way — an intent changes presentation only, never the protocol.
+ */
+type AskUserQuestionIntent = {
+  /** A plan submitted for review: `detail` is the plan markdown `ask()` requires, and the decision approves or declines it. */
+  kind: 'plan-review'
+  /**
+   * The option label that approves the plan; every other option declines it.
+   * Named rather than positional so no UI infers the verdict from option order.
+   * An `approve` naming no option of its own question is rejected at `ask()`.
+   */
+  approve: string
+}
+```
+
+## Question item
+
+`AskUserQuestionItem` is one question in a request. The caller supplies a stable `id`, which is echoed back with the answer so batched questions remain routable. Optional `detail` carries supporting text that providers render with the question but keep out of selectable option labels.
+
+```ts type-equiv
+/** One question in a user-questions request. */
+interface AskUserQuestionItem {
+  /** Stable caller-provided question id, echoed in the answer. */
+  id: string
+  /** The question to display. */
+  question: string
+  /** Optional supporting detail rendered with the question but kept out of option labels. */
+  detail?: string
+  /** Optional short heading/group label. */
+  header?: string
+  /** Optional choices the UI can render as a menu. */
+  options?: AskUserQuestionOption[]
+  /** Whether more than one option may be selected. Defaults to single-select. */
+  multiSelect?: boolean
+  /** Optional presentation intent for capable UIs; absent asks for the generic option list. */
+  intent?: AskUserQuestionIntent
+}
+```
+
+## Ask request
+
+`AskUserQuestionRequest` is the cross-package request. `questions` is an array so a UI can present related prompts in one flow while preserving a stable id per answer. When present, `agent` is the exact live caller; the interaction seam admits it only while the live registry identifies that instance as a runtime root.
+
+```ts type-equiv
+/** Request for a human answer. */
+interface AskUserQuestionRequest {
+  /** Questions to display. */
+  questions: AskUserQuestionItem[]
+  /** Exact live calling agent, when the request came from an agent tool call. */
+  agent?: Agent
+  /** Abort signal for the owning tool/step. */
+  signal?: AbortSignal
+}
+```
+
+## Answer
+
+Providers return one answer item per question id. `selected` contains selected option labels, and `custom` carries a free-form "Other" answer when the user typed one. For a single-select question, `custom` overrides the selected choice and `selected` is empty. For a multi-select question, `custom` may supplement the labels in `selected`. A UI may also use an item with empty `selected` and no `custom` to preserve a skipped question in an otherwise completed batch.
+
+```ts type-equiv
+/** Answer to one question. */
+interface AskUserQuestionAnswerItem {
+  /** The answered question id. */
+  id: string
+  /** Selected option labels. May accompany custom text for a multi-select question. */
+  selected: string[]
+  /** Optional free-text "Other" answer. */
+  custom?: string
+}
+```
+
+```ts type-equiv
+/** The human's answer. */
+interface AskUserQuestionAnswer {
+  /** Structured answers keyed by question id. */
+  answers: AskUserQuestionAnswerItem[]
+}
+```
+
+## Provider
+
+Only one provider may be active in a context. Provider registration is effect-bound so HMR/disposal removes the active UI.
+
+```ts type-equiv
+/** UI-side provider for user questions. */
+interface UserQuestionProvider {
+  ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
+}
+```
+
+## Errors
+
+`UserQuestionError` extends `HarnessError`, so `ctx.tools.execute()` preserves `{ name, code }` for model-facing tool failures such as `EMPTY_QUESTIONS`, `NO_PROVIDER`, `ASK_ABORTED`, or UI-side cancellation.
+
+```ts type-equiv
+/** Stable error taxonomy for user-questions failures. */
+class UserQuestionError extends HarnessError {
+  constructor(message: string, code: string, options?: ErrorOptions) {
+    super(message, code, options)
+    this.name = 'UserQuestionError'
+  }
+}
+```
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis API
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxuserquestions--userquestionservice"></a>
+
+### `ctx.userQuestions` — `UserQuestionService`
+
+`ctx.userQuestions`: one active UI provider plus an `ask()` API.
+
+```ts cordis-catalog
+/**
+ * Register the UI provider. Only one provider may be active in a context.
+ *
+ * @param provider UI-side implementation that collects answers.
+ * @returns Disposer that unregisters this provider.
+ */
+registerProvider(provider: UserQuestionProvider): () => void
+
+/**
+ * Ask the active UI provider and wait for the user's answer.
+ *
+ * When a caller supplies an agent, human interaction is valid only for the
+ * exact live runtime root. Runtime ownership, not durable session lineage,
+ * decides this boundary: an owned child has no human answerer and would
+ * block forever, while a lineage-bearing session resumed as a new runtime
+ * root may ask normally.
+ *
+ * @param request Questions, owner agent, and abort signal.
+ * @returns The answer chosen or typed by the human.
+ * @throws {UserQuestionError} code `CALLER_NOT_LIVE` when a supplied
+ *   agent is not the registry's exact live instance, or `DELEGATED_CALLER`
+ *   when that live agent is owned by another agent.
+ */
+async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
+```
+
+Source: [`packages/interaction/user-questions/src/index.ts:51`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/interaction/user-questions/src/index.ts)
+<!-- END GENERATED cordis-surface -->

package/kb/site/en/reference/subsystems/web-server.md

@@ -0,0 +1,111 @@
+---
+editSource: "docs/subsystems/web-server.md"
+outline: [2,3]
+---
+
+# HTTP Server
+
+[dsh-host-webserver](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/host/webserver) is the browser HTTP carrier for the GUI host: a single `node:http` plugin providing `ctx.webServer`, a named-route registry, index.html transform callbacks, and one fallback handler that a plugin may claim. It is not part of the agent loop and not a capability seam; it knows no harness concepts, and another plugin registers every feature route, including the `/api` bridge, plugin bundles, and the HMR event stream ([layering note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)). It serves browsers only: Electron loads the built files over `file://` and sends fetch requests through an IPC bridge instead of this server.
+
+Source: [`packages/host/webserver/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/host/webserver/src/index.ts)
+
+## Routes
+
+```ts type-equiv
+/** Route match kind: 'exact' matches the pathname verbatim; 'prefix' p matches p and p/<anything>. */
+type WebRouteKind = 'exact' | 'prefix'
+```
+
+```ts type-equiv
+/** One named route registration. */
+interface WebRoute {
+  kind: WebRouteKind
+  /** Absolute pathname, no trailing slash. */
+  path: string
+  /** Owns the full response lifecycle (may hold the response open, e.g. SSE). */
+  handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+}
+```
+
+Match order is fixed: exact table first, then longest matching prefix, then the registered fallback. Registration order carries no request-facing semantics — named routes are composed to be disjoint, and the fallback seat answers anything no named route claims; one owner only, a second registration throws. The shipped Web composition claims the seat with [`dsh-host-frontend-static`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/host/frontend-static/src/index.ts), the SPA dist server with locked semantics: non-GET/HEAD is 405, traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), and unknown extensions ship as octet-stream.
+
+## Config
+
+```ts type-equiv
+/** Gateway config: the listen address. */
+interface Config {
+  /** Listen host; the two supported values are loopback and all-interfaces. */
+  host: '127.0.0.1' | '0.0.0.0'
+  /** Listen port; zero requests an OS-assigned port. */
+  port: number
+}
+```
+
+`host` accepts only `127.0.0.1` (default posture) and `0.0.0.0` (deliberate network exposure); there is no TLS, auth, or origin policy, so a non-loopback bind exposes the server to that network. The dist location is an assembly fact of the frontend plugin that claims the seat.
+
+## The service
+
+`WebServer` (`ctx.webServer`) listens immediately on activation; a listen failure (EADDRINUSE…) rejects initialization, and the boot process reports the failed fiber. `register(route)` adds one named route and returns its disposer; a duplicate `(kind, path)` throws because route patterns are a composition-level contract and a collision is a misconfiguration. `tapIndex(transform)` adds a pure html-to-html transform applied to every index response — `/` and each SPA fallback — in registration order; [dsh-client-modules](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/client/modules) uses it to inject the boot manifest. `port` reads the listening port, including the port assigned by the OS when `config.port` is 0.
+
+A request whose handling throws (a malformed %-escape hitting `decodeURIComponent`, a client dropping mid-body) is logged as a warning and answered 400 — or the socket destroyed when headers are already out — never a process exit. Disposal pairs `close()` with `closeAllConnections()` because a handler may hold its response open (SSE) and such connections never end on their own; without the force-close, teardown would hang. The package never prints: the URL line belongs to the shell. Per-package operational detail, including the dev-mode bundle watch pipeline, stays in the [README](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/host/webserver/README.md).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis API
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxwebserver--webserver"></a>
+
+### `ctx.webServer` — `WebServer`
+
+The browser HTTP carrier service. Activation listens immediately. Route registration order does not affect requests because configured named routes must be distinct, and the fallback handler answers anything not yet claimed during startup with 404 until its owner registers. A listen failure rejects initialization, and the boot process reports the failed fiber.
+
+```ts cordis-catalog
+/**
+ * Register a named route. Duplicate (kind, path) throws — route patterns are
+ * a composition-level contract, so a collision is a misconfiguration.
+ * @param route - kind, path, and the owning handler.
+ * @returns the disposer removing the route.
+ */
+register(route: WebRoute): () => void
+
+/**
+ * Register an exact-path HTTP upgrade route. Duplicate paths throw because
+ * one socket can have only one protocol owner.
+ * @param route - pathname and handler owning negotiation plus socket use.
+ * @returns the disposer removing the route.
+ */
+registerUpgrade(route: WebUpgradeRoute): () => void
+
+/**
+ * Claim the fallback seat: the handler answering every request no named
+ * route matches (the SPA dist server in the shipped Web composition). One
+ * owner only — a second registration throws, because two fallbacks cannot
+ * compose.
+ * @param handler - owns the full response lifecycle of unmatched requests.
+ * @returns the disposer releasing the seat.
+ */
+registerFallback(handler: WebRoute['handler']): () => void
+
+/**
+ * Register an index.html transform, applied by the fallback owner to every
+ * index response ({@link applyIndexTaps}) in registration order.
+ * @param transform - pure html-to-html function.
+ * @returns the disposer removing the transform.
+ */
+tapIndex(transform: (html: string) => string): () => void
+
+/**
+ * Run an index.html body through the registered taps in registration order
+ * — called by the fallback owner on every index response it renders.
+ * @param html - the raw index.html body.
+ * @returns the transformed body.
+ */
+applyIndexTaps(html: string): string
+```
+
+Source: [`packages/host/webserver/src/index.ts:59`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/host/webserver/src/index.ts)
+<!-- END GENERATED cordis-surface -->