scripts/gen-website-api.ts renders website/zh-CN/api/{cordis,harness}/* and the
api-sidebar.json fragment the VitePress config imports, so pages and navigation
can never drift from the code: signatures, @param/@returns prose, dispatch
modes, and GitHub source links are extracted, never transcribed, and the
generator hard-errors on any rendered member missing docs. verify-website-api
(doc-sync + run-gates) is the freshness gate.
Replaces the hand-written zh api pages (7 pages covering 7 of 15 services,
with phantom APIs: Context.current/Context.events, agent/post-step, tool/call,
compact/*, llm/pre-request none of which exist) with generated English
references: 5 cordis pages, 15 per-service pages, and a 35-event catalog
grouped by scope. The hand-written hub api/index.md stays and now indexes the
full surface; zh for these pages arrives with the unified translation flow.
New doc-sync gate verify-website-yaml: each ```yaml block under
website/zh-CN (api/ excluded — generator-owned) must parse with the loader's
real schema (JSON_SCHEMA + !!js), use only EntryOptions keys, name only real
workspace packages, and pass only config keys the plugin's declared Config
type / schemastery schema accepts (collectConfigCatalog drives the key sets).
```yaml ignore-check opts out a deliberate-placeholder block (the
capability-trio tutorial keeps its fictional package names).
Comment-only enrichment across cordis/src/*.ts — Context, EventsService (+ the
ctx merges), Fiber, RegistryService, ReflectService, Service, logger — so the
website API generator can render a complete reference and hard-error on any
future undocumented member (vendor sync included). Logged as local
modification 6 in vendor/README.md; retire it when upstreamed to the fork.
INHERITED_SERVICES/EVENTS source pointers refreshed for the shifted lines;
cordis catalogs regenerated.
- website joins the pnpm workspace; root scripts website:dev/website:build;
run-gates gains a website-build gate (ci-primary + ci-static) — the
VitePress build doubles as the site's dead-link check; AGENTS.md documents
the commands.
- doc-typecheck + verify-type-equiv now scan website/zh-CN/**/*.md; every
```typescript fence converted to ```ts and made standalone-compilable
(55 compiled, 1 ignore-check). Phantom APIs the compiler caught are fixed:
invented event names (agent/turn-end, tool/call, llm/pre-request, ready,
dispose) replaced with real catalog events or per-plugin declare-module
merges; presentCall/inject/Config claims corrected to the real shapes.
- guide/config.md entry-fields table completed against loader EntryOptions;
its coding-agent example brought in line with examples/coding-agent.
Lifecycle and safety fixes from the external review:
- Observe abort while awaiting the initialize handshake, so a server that never
replies can't defeat the tool-timeout signal.
- On an aborted request the server won't cancel, tear the instance down after a
bounded grace instead of releasing the serialized queue with work still live
(prevents overlapping document lifecycles).
- Re-check provider disposal after the canonicalize/read awaits so a query can't
spawn an unowned server after disposeAll().
- Read the source through one open handle (stat + read on the same fd) to close
the realpath-vs-read TOCTOU; decode with a fatal UTF-8 decoder so a legitimate
U+FFFD is not misclassified as invalid.
- Validate and read the source BEFORE spawning a server (pre-start rejection).
- Require an explicit openClose for option-form textDocumentSync.
- Reject nonpositive teardown budgets and non-executable absolute commands at
load; surface unsupported operations as structured LSP_UNSUPPORTED_OPERATION.
- Retain the stderr tail (fatal diagnostics land at exit), not the prefix.
- Catalog the seam vocabulary in docs/core-data-structures/lsp.md.
Implements the LSP capability seam RFC as three packages: dsh-lsp (the
ctx.lsp interface — provider registry by branded id + exclusive extension
mapping, per-query order-independent selection, closed request/result
vocabulary, LspError taxonomy), dsh-lsp-local (a generic stdio language-server
provider — Content-Length JSON-RPC framing, per-(provider, workspace) process
single-flight, transient didOpen/query/didClose, an abortable per-instance
queue, UTF-16 negotiation, host-namespace source reads outside ctx.fs, and
bounded shutdown/kill teardown), and dsh-tool-lsp (the model-facing lsp tool —
four operations, one-based UTF-16 cursor conversion, workspace-grouped location
rendering, hover capping, a required session workspace, and a timeout budget).
Why: an agent had text search and file reads but no way to identify a program
symbol — follow an alias, connect an interface to implementations, or read an
inferred type — before changing code. Splitting model contract, seam, and local
subprocess behavior keeps the four semantic queries stable across future remote
or sandbox-native providers without leaking a JSON-RPC escape hatch.
The public kill result used the awkward phrase already-terminal. Rename it to already-finished and keep the model-facing response aligned; not-alive would be inaccurate because a force-failed registry record can still correspond to orphaned producer work.
Task kinds were open strings even though producer namespaces are an extension point. Add the merge-extensible TaskKindMap and derived TaskKind, cover consumer declarations in task and bundle tests, and retain the runtime non-empty check for untyped callers.
With exactOptionalPropertyTypes, owner?: Agent | undefined allowed an explicit undefined value that no caller needs. Tighten the property to owner?: Agent so unowned work is expressed by omitting it.
Record the requested task-service/backend split as a follow-up, using a systemd-backed runtime as a concrete candidate without guessing its durability and ownership contract in this PR. Regenerate the type and Cordis catalogs so public docs match the declarations.
Refresh the background-task branch onto the latest repository baseline before applying review feedback. This preserves merge ancestry, incorporates the current CI and package-structure changes, and ensures the review fixes are validated against the code that will actually receive the PR.
