super-dsh 0.3.0-c → 0.3.0-e

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/user/develop/basic/publish.md

@@ -1,183 +0,0 @@
-# Package and install a plugin
-
-English | [中文](publish.zh.md)
-
-The previous tutorials loaded a local plugin through a `--patch` overlay. This tutorial packages it as an installable **bundle**, installs it into a **profile** with `dsh plugin add`, and explains the layer order that determines the composed configuration. It assumes the `dsh` CLI is installed. Complete [plugin configuration](./config.md) first.
-
-To use a fresh source checkout instead, complete the [run-from-source section](../../../../README.md#run-from-source), keep this tutorial's `hello-plugin` directory at the repository root, and run the remaining `dsh ...` commands from there as `pnpm dsh ...`. See [source execution](../../../../apps/cli/reference/README.md#source-execution) for build and launcher behavior.
-
-## Two concepts, two manifests
-
-Installation is built on two concepts. Both are described by a `package.json`, but they carry different kinds of manifest under the `dsh` key, and they answer different questions:
-
-- A **bundle** is an npm package that ships a configuration layer. Its manifest declares `dsh.bundle`, answering "what does this package contribute?": a patch file that inserts or overrides plugin rows.
-- A **profile** is a directory under `$DSH_HOME/profiles/<name>` describing one runnable composition. Its manifest declares `dsh.profile`, answering "which bundles compose this setup, in what order?".
-
-A bundle is what you author and distribute; a profile is what a user boots with `dsh --profile <name>`. Nothing is both.
-
-### The bundle manifest
-
-Create the package directory:
-
-```sh
-mkdir -p hello-plugin
-```
-
-```
-hello-plugin/
-├── package.json       # declares dsh.bundle
-├── cordis.patch.yml   # the layer applied when a profile lists this bundle
-└── index.js           # plugin modules the patch rows reference
-```
-
-Create `hello-plugin/package.json`:
-
-```json
-{
-  "name": "dsh-hello-plugin",
-  "version": "0.1.0",
-  "type": "module",
-  "main": "index.js",
-  "files": ["index.js", "cordis.patch.yml"],
-  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
-}
-```
-
-Create `hello-plugin/index.js` with the plugin entry point:
-
-```js
-export const name = 'hello-plugin'
-
-export function apply() {
-  console.log('[hello-plugin] plugin loaded!')
-}
-```
-
-Create `hello-plugin/cordis.patch.yml`. The patch is a YAML array like the `--patch` overlays you wrote, except plugin rows reference the package by name instead of a relative source path so Node resolution finds the installed code:
-
-```yaml
-- insert:
-    - id: hello
-      name: dsh-hello-plugin
-```
-
-A package without the `dsh.bundle` declaration still installs, but only as a plain dependency: `dsh plugin` prints a warning and activates no layer. Use that package format for a library that plugin packages import rather than a plugin users enable.
-
-### The profile manifest
-
-A profile directory holds two files:
-
-- `package.json` — the profile's out-of-tree plugin dependencies (managed by pnpm) plus the `dsh.profile` manifest with its ordered `bundles` list.
-- `cordis.patch.yml` — the user's own patch layer, applied after every bundle layer.
-
-You never write a profile manifest by hand: `dsh plugin` creates and maintains it. The next section shows the result.
-
-## Install into a profile
-
-`dsh plugin --profile <name> <args...>` forwards to pnpm in the profile directory, so every pnpm verb works. From the directory that contains `hello-plugin`, install the package checkout:
-
-```sh
-dsh plugin --profile demo add ./hello-plugin
-```
-
-The first use initializes the profile (with `@deepseek-ai/dsh-base` as its first bundle), pnpm links the checkout, and `dsh` appends the bundle to `dsh.profile.bundles` because the package declares `dsh.bundle`:
-
-```json
-{
-  "name": "dsh-profile-demo",
-  "private": true,
-  "dependencies": {
-    "dsh-hello-plugin": "link:/path/to/hello-plugin"
-  },
-  "dsh": {
-    "profile": {
-      "bundles": [
-        "@deepseek-ai/dsh-base",
-        "dsh-hello-plugin"
-      ]
-    }
-  }
-}
-```
-
-Verify the layer without booting, then boot:
-
-```sh
-dsh --profile demo --dump-config   # shows a "# == dsh-hello-plugin" layer
-dsh --profile demo
-```
-
-`dsh plugin --profile demo remove dsh-hello-plugin` removes both the dependency and the layer.
-
-## The loading order
-
-The effective configuration composes over an empty root by applying, in order:
-
-1. Each bundle patch named in the profile's `dsh.profile.bundles` list, in list order — `@deepseek-ai/dsh-base` first, then each installed bundle in the order it was added.
-2. The profile's own `cordis.patch.yml`.
-3. The home-level `$DSH_HOME/cordis.patch.yml` — machine-local preferences shared by every profile.
-4. Each `--patch <path>` overlay, in argv order.
-
-App arguments are not another patch layer. A surface bundle can resolve them through an ordinary app-owned service, described below.
-
-Later layers win per row, and a patch replaces a row's entire `config` value rather than deep-merging keys. Two consequences for bundle authors:
-
-- Your patch can override rows from earlier layers by `id` — the same way [the `dsh-web-app` bundle](../../../../packages/bundle/web-app/cordis.patch.yml) overrides `dsh-base` rows — but must restate every key the row needs, not just the changed one.
-- Users can override your rows in their profile's `cordis.patch.yml` without touching your package, so prefer configuration defaults users are likely to keep and let the schema carry the rest.
-
-In-box bundle names always resolve from the dsh installation itself; pnpm manages only out-of-tree packages, so your bundle can rely on `@deepseek-ai/dsh-base` being present and current.
-
-## Give a surface bundle its own command line
-
-A bundle that defines a runnable app mounts an ordinary provider plugin:
-
-```yaml
-- id: hello-startup
-  name: 'dsh-hello-plugin/startup'
-```
-
-The plugin exports `inject = ['cmdlineArgs']`, calls `parseCmdline` from [`@deepseek-ai/dsh-cmdline`](../../../../packages/boot/cmdline/README.md) with its own commander program, and provides its app-owned service from the program's action. The launcher hands every plugin the same immutable arguments after launcher flags, so app-specific flags need no launcher change and multiple plugins may parse the snapshot. The Loader row needs no launcher marker or special kind.
-
-Rows configured by those arguments inject the provider's service and read it from their own `!!js` options, with the deployment value beside it as the fallback:
-
-```yaml
-- id: my-app
-  name: '@example/my-app'
-  inject: [myAppStartup]
-  config:
-    port: !!js ctx.myAppStartup.port ?? 8080
-```
-
-On `--help`, the provider publishes no service, so those rows never activate. Loader mounts the composition once, waits for each row's ordinary injections, and only then evaluates that row's `!!js` config against its injected context.
-
-## Installing from GitHub: the build-script catch
-
-Publishing to a registry is not required — users can install straight from a git host:
-
-```sh
-dsh plugin --profile demo add github:you/hello-plugin
-```
-
-But a git install fetches **sources, not built artifacts**: nothing runs your `build` script, so a TypeScript package arrives without its `lib/` output and fails to load. Two things must happen, one on each side:
-
-- **The author** ships a `prepare` script — pnpm runs it after a git install — that builds the published entry points from source, self-contained: it must not assume dev-only context such as a sibling monorepo checkout. [turtle-ui](https://github.com/deepseek-harness/turtle-ui) is a working example: its `prepare` runs a dedicated tsdown config that transpiles `src/` without project references or type checking.
-- **The user** allowlists the build. pnpm ≥10 refuses to run a git dependency's `prepare` script until it is explicitly allowed, so the first `add` fails; `dsh` points at the fix — copy the exact package key pnpm printed into the profile's `pnpm-workspace.yaml`:
-
-  ```yaml
-  allowBuilds:
-    dsh-hello-plugin: true
-  ```
-
-  and re-run the `add`.
-
-Treat that allowance as **permission to execute the package's code on your machine at install time**, outside any sandbox the agent runs under. Only allow packages whose source you trust, and pin a commit (`github:you/hello-plugin#<sha>`) so a later push cannot silently change what runs.
-
-If you would rather not ask users for the allowance, distribute built artifacts instead — neither form needs any build permission:
-
-- **Publish to npm** with `lib/` built at `pnpm publish` time; `dsh plugin add your-package` then installs prebuilt code.
-- **Ship a tarball** from `pnpm pack`; users run `dsh plugin add ./hello-plugin-0.1.0.tgz`.
-
-## Next steps
-
-- [Plugins and lifecycle](../framework/index.md) — the full plugin lifecycle
-- [CLI behavior reference](../../../../apps/cli/reference/README.md) — exact layer precedence, flags, and profile mechanics

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/user/develop/basic/publish.zh.md

@@ -1,183 +0,0 @@
-# 打包与安装插件
-
-[English](publish.md) | 中文
-
-前几篇教程通过 `--patch` overlay 加载本地插件。本教程把它打包成可安装的**组合包**（bundle），用 `dsh plugin add` 安装进一个 **profile**，并解释决定组合后配置的层顺序。本文假设 `dsh` CLI 已安装。请先完成[插件配置](./config.zh.md)。
-
-如果改用全新的源码 checkout，请先按照[从源码运行章节](../../../../README.zh.md#run-from-source)完成准备，将本教程的 `hello-plugin` 目录放在仓库根目录，并从该目录把下文的 `dsh ...` 命令改为 `pnpm dsh ...`。构建与启动器行为见[源码执行](../../../../apps/cli/reference/README.zh.md#source-execution)。
-
-## 两个概念，两种 manifest
-
-安装机制建立在两个概念之上。二者都由一份 `package.json` 描述，但它们在 `dsh` 键下携带的 manifest（元数据清单）种类不同，回答的问题也不同：
-
-- **组合包**是附带一个配置层的 npm 包。它的 manifest 声明 `dsh.bundle`，回答的是"这个包贡献什么？"：一个插入或覆盖插件行的 patch 文件。
-- **profile** 是位于 `$DSH_HOME/profiles/<name>` 下、描述一份可启动组合的目录。它的 manifest 声明 `dsh.profile`，回答的是"这套配置由哪些组合包按什么顺序组成？"。
-
-组合包是你编写并分发的东西；profile 是用户用 `dsh --profile <name>` 启动的东西。没有东西同时是两者。
-
-### 组合包 manifest
-
-创建包目录：
-
-```sh
-mkdir -p hello-plugin
-```
-
-```
-hello-plugin/
-├── package.json       # declares dsh.bundle
-├── cordis.patch.yml   # the layer applied when a profile lists this bundle
-└── index.js           # plugin modules the patch rows reference
-```
-
-创建 `hello-plugin/package.json`：
-
-```json
-{
-  "name": "dsh-hello-plugin",
-  "version": "0.1.0",
-  "type": "module",
-  "main": "index.js",
-  "files": ["index.js", "cordis.patch.yml"],
-  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
-}
-```
-
-创建 `hello-plugin/index.js`，写入插件入口：
-
-```js
-export const name = 'hello-plugin'
-
-export function apply() {
-  console.log('[hello-plugin] plugin loaded!')
-}
-```
-
-创建 `hello-plugin/cordis.patch.yml`。这个 patch 与你写过的 `--patch` overlay 一样，是一个 patch 条目的 YAML 数组；区别是插件行按包名而不是相对源码路径引用这个包，这样 Node 的模块解析才能找到已安装的代码：
-
-```yaml
-- insert:
-    - id: hello
-      name: dsh-hello-plugin
-```
-
-没有 `dsh.bundle` 声明的包仍然可以安装，但只作为普通依赖：`dsh plugin` 会打印警告，且不激活任何层。如果一个库供插件包 import，而不是供用户启用，就使用这种包格式。
-
-### profile manifest
-
-profile 目录包含两个文件：
-
-- `package.json` — profile 的树外插件依赖（由 pnpm 管理），加上 `dsh.profile` manifest 及其有序的 `bundles` 列表。
-- `cordis.patch.yml` — 用户自己的 patch 层，在每个组合包层之后应用。
-
-profile manifest 从不需要手写：`dsh plugin` 负责创建和维护它。下一节展示其结果。
-
-## 安装进 profile
-
-`dsh plugin --profile <name> <args...>` 在 profile 目录内转发给 pnpm，因此所有 pnpm 子命令都可用。在包含 `hello-plugin` 的目录中安装该包的 checkout：
-
-```sh
-dsh plugin --profile demo add ./hello-plugin
-```
-
-首次使用会初始化 profile（`@deepseek-ai/dsh-base` 作为它的第一个组合包），pnpm 链接该 checkout，而 `dsh` 因为这个包声明了 `dsh.bundle`，把它追加进 `dsh.profile.bundles`：
-
-```json
-{
-  "name": "dsh-profile-demo",
-  "private": true,
-  "dependencies": {
-    "dsh-hello-plugin": "link:/path/to/hello-plugin"
-  },
-  "dsh": {
-    "profile": {
-      "bundles": [
-        "@deepseek-ai/dsh-base",
-        "dsh-hello-plugin"
-      ]
-    }
-  }
-}
-```
-
-先不启动、只验证该层，再启动：
-
-```sh
-dsh --profile demo --dump-config   # shows a "# == dsh-hello-plugin" layer
-dsh --profile demo
-```
-
-`dsh plugin --profile demo remove dsh-hello-plugin` 会同时移除依赖和对应的层。
-
-## 加载顺序
-
-生效配置在空根之上按以下顺序逐层组合：
-
-1. profile 的 `dsh.profile.bundles` 列表所列的各个组合包 patch，按列表顺序——先是 `@deepseek-ai/dsh-base`，然后是每个已安装组合包，按其加入顺序。
-2. profile 自己的 `cordis.patch.yml`。
-3. home 级的 `$DSH_HOME/cordis.patch.yml`——各 profile 共享的机器本地偏好。
-4. 每个 `--patch <path>` overlay，按 argv 顺序。
-
-应用参数不是另一层 patch。表层组合包可以通过下文所述的普通应用自有服务解析它们。
-
-后应用的层按行胜出，且 patch 会替换目标行的整个 `config` 值，而不是深度合并各键。这给组合包作者带来两个推论：
-
-- 你的 patch 可以按 `id` 覆盖前面各层的行——就像 [`dsh-web-app` 组合包](../../../../packages/bundle/web-app/cordis.patch.yml)覆盖 `dsh-base` 的行那样——但必须重述该行需要的每一个键，而不是只写改动的那个。
-- 用户可以在自己 profile 的 `cordis.patch.yml` 中覆盖你的行，无需改动你的包，所以优先给出用户大概率会保留的配置默认值，其余交给 schema 承担。
-
-内置组合包名称始终从 dsh 安装目录本身解析；pnpm 只管理树外的包，所以你的组合包可以放心依赖 `@deepseek-ai/dsh-base` 存在且与安装保持一致。
-
-## 让表层组合包持有自己的命令行
-
-定义了可运行应用的组合包挂载一个普通提供方插件：
-
-```yaml
-- id: hello-startup
-  name: 'dsh-hello-plugin/startup'
-```
-
-该插件导出 `inject = ['cmdlineArgs']`，使用自己的 commander program 调用 [`@deepseek-ai/dsh-cmdline`](../../../../packages/boot/cmdline/README.zh.md) 中的 `parseCmdline`，再在 program 自己的 action 中把应用自有服务提供出去。启动器把自身 flag 之后的同一份不可变参数交给每个插件，因此添加应用专属 flag 无需修改启动器，多个插件也可以解析该快照。Loader 行不需要启动器标记或特殊类型。
-
-受这些参数配置的行会注入提供方服务，并在自己的 `!!js` 选项中读取它，同时把部署取值写在旁边作为回退：
-
-```yaml
-- id: my-app
-  name: '@example/my-app'
-  inject: [myAppStartup]
-  config:
-    port: !!js ctx.myAppStartup.port ?? 8080
-```
-
-遇到 `--help` 时，提供方不会发布该服务，所以这些行不会激活。Loader 只挂载一次组合，等待每一行的普通注入，再基于其已注入的上下文求值该行的 `!!js` 配置。
-
-## 从 GitHub 安装：构建脚本这道坎
-
-发布到注册表不是必须的——用户可以直接从 git 托管安装：
-
-```sh
-dsh plugin --profile demo add github:you/hello-plugin
-```
-
-但 git 安装拉取的是**源码，不是构建产物**：没有任何环节运行你的 `build` 脚本，因此 TypeScript 包到手时没有 `lib/` 输出，加载会失败。必须两边各做一件事：
-
-- **作者**提供一个 `prepare` 脚本——pnpm 在 git 安装后运行它——从源码构建出发布入口，且必须自包含：不能假设仅开发环境才有的上下文，例如旁边有一份 monorepo checkout。[turtle-ui](https://github.com/deepseek-harness/turtle-ui) 是一个可用的例子：它的 `prepare` 运行一份专用的 tsdown 配置，直接转译 `src/`，不用项目引用，也不做类型检查。
-- **用户**为构建授权。pnpm ≥10 在得到显式允许之前拒绝运行 git 依赖的 `prepare` 脚本，所以第一次 `add` 会失败；`dsh` 会指出修法——把 pnpm 打印的确切包键复制进该 profile 的 `pnpm-workspace.yaml`：
-
-  ```yaml
-  allowBuilds:
-    dsh-hello-plugin: true
-  ```
-
-  然后重新执行 `add`。
-
-请把这项授权视为**允许该包的代码在安装时于你的机器上执行**，且不在 agent 运行的任何沙箱之内。只对源码可信的包授权，并锁定 commit（`github:you/hello-plugin#<sha>`），让后续推送无法悄悄改变实际运行的内容。
-
-如果不想让用户做这项授权，就改为分发构建产物——以下两种形式都不需要任何构建权限：
-
-- **发布到 npm**，在 `pnpm publish` 时构建好 `lib/`；`dsh plugin add your-package` 安装的就是预构建代码。
-- **交付 tarball**：用 `pnpm pack` 打包；用户执行 `dsh plugin add ./hello-plugin-0.1.0.tgz`。
-
-## 下一步
-
-- [插件与生命周期](../framework/index.zh.md) — 插件的完整生命周期
-- [CLI（命令行界面）行为参考](../../../../apps/cli/reference/README.zh.md) — 确切的层优先级、flag 与 profile 机制

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/user/develop/basic/tool.md

@@ -1,52 +0,0 @@
-# Build a tool
-
-English | [中文](tool.zh.md)
-
-This tutorial adds a `greet` tool to the Web UI. Complete [Your first plugin](./index.md) first and keep its `scratch-plugin` directory.
-
-## Create the tool plugin
-
-Replace `scratch-plugin/src/my-plugin.ts` with:
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import { defineTool } from '@deepseek-ai/dsh-tools'
-
-export const name = 'greet-tool'
-export const inject = ['tools']
-
-export function apply(ctx: Context) {
-  ctx.tools.register(defineTool({
-    name: 'greet',
-    description: 'Greet someone by name.',
-    parameters: {
-      name: { type: 'string', required: true, description: 'The name to greet' },
-    },
-    output: {
-      schema: { type: 'string' },
-      render: (_args, value) => [{ type: 'text', text: value }],
-    },
-    async execute(args) {
-      return `Hello, ${args.name}!`
-    },
-  }))
-}
-```
-
-`inject` makes Cordis wait for the tool registry. `defineTool` infers and validates `args` from `parameters`; `execute` returns the canonical value declared by `output.schema`, and `output.render` converts that value to model-facing content.
-
-## Run and call the tool
-
-Restart the development command if it is not running:
-
-```sh
-pnpm dsh web --patch ./scratch-plugin/cordis.yml
-```
-
-Open `http://127.0.0.1:3080` and ask: `Use the greet tool to greet Ada.` The model can call `greet` and receives `Hello, Ada!` as the tool result.
-
-## Next steps
-
-- [Plugin configuration](./config.md) — make the greeting configurable.
-- [Tool authoring reference](../../../cookbook/adding-a-tool.md) — look up nested schemas, canonical values, background work, policy hooks, PTC mode, and UI cards.
-- [Capability layering](../practice/index.md) — split a replaceable capability into Service Definition, Service Provider, and Consumer packages.

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/user/develop/basic/tool.zh.md

@@ -1,52 +0,0 @@
-# 开发一个工具
-
-[English](tool.md) | 中文
-
-本教程会在 Web UI 中添加一个 `greet` 工具。请先完成[第一个插件](./index.zh.md)，并保留其中的 `scratch-plugin` 目录。
-
-## 创建工具插件
-
-将 `scratch-plugin/src/my-plugin.ts` 替换为：
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import { defineTool } from '@deepseek-ai/dsh-tools'
-
-export const name = 'greet-tool'
-export const inject = ['tools']
-
-export function apply(ctx: Context) {
-  ctx.tools.register(defineTool({
-    name: 'greet',
-    description: 'Greet someone by name.',
-    parameters: {
-      name: { type: 'string', required: true, description: 'The name to greet' },
-    },
-    output: {
-      schema: { type: 'string' },
-      render: (_args, value) => [{ type: 'text', text: value }],
-    },
-    async execute(args) {
-      return `Hello, ${args.name}!`
-    },
-  }))
-}
-```
-
-`inject` 让 Cordis 等待工具注册表就绪。`defineTool` 根据 `parameters` 推导并校验 `args`；`execute` 返回 `output.schema` 声明的规范值，`output.render` 再将该值转换为面向模型的内容。
-
-## 运行并调用工具
-
-如果开发命令未在运行，请重新启动：
-
-```sh
-pnpm dsh web --patch ./scratch-plugin/cordis.yml
-```
-
-打开 `http://127.0.0.1:3080`，然后输入：`Use the greet tool to greet Ada.` 模型可以调用 `greet`，并收到 `Hello, Ada!` 这一工具结果。
-
-## 下一步
-
-- [插件配置](./config.zh.md) — 让问候语可配置。
-- [工具编写参考](../../../cookbook/adding-a-tool.zh.md) — 查阅嵌套 schema、规范值、后台工作、策略钩子、PTC mode 和 UI 卡片。
-- [能力分层](../practice/index.zh.md) — 将可替换能力拆分为 Service Definition、Service Provider 和 Consumer 三类包。

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/user/develop/framework/events.md

@@ -1,143 +0,0 @@
-# Event system
-
-English | [中文](events.zh.md)
-
-Events are the core communication mechanism between Cordis plugins. Harness uses them extensively for loosely coupled extension points.
-
-## Basic use
-
-### Listen for an event
-
-```ts ignore-check
-ctx.on('event-name', (payload) => {
-  // Handle the event.
-})
-```
-
-### Emit an event
-
-```ts ignore-check
-ctx.emit('event-name', payload)
-```
-
-## Event modes
-
-Cordis provides several event modes for different interaction contracts.
-
-### emit — broadcast
-
-Every listener runs synchronously and return values are ignored:
-
-```ts ignore-check
-// Emit
-ctx.emit('my-plugin/ready', { id: 'worker-1' })
-
-// Listen
-ctx.on('my-plugin/ready', ({ id }) => {
-  console.log(`${id} is ready`)
-})
-```
-
-### bail — short circuit
-
-Listeners run in order; the first result other than `null`, `false`, or `undefined` becomes the final result:
-
-```ts ignore-check
-// Dispatch
-const result = ctx.bail('some-check', input)
-
-// Listen: a returned value stops later listeners.
-ctx.on('some-check', (input) => {
-  if (shouldBlock(input)) return 'blocked'
-  // Return null, false, or undefined to continue to the next listener.
-})
-```
-
-### serial — ordered execution
-
-Listeners run in registration order and asynchronous results are awaited. The first result other than `null`, `false`, or `undefined` stops further execution:
-
-```ts ignore-check
-await ctx.serial('setup-phase', context)
-```
-
-### waterfall — pipeline
-
-Each listener may wrap the downstream result to form a processing chain. A listener **must call `next()` to delegate downstream**; omitting the call short-circuits the pipeline:
-
-```ts ignore-check
-// Dispatch
-const output = await ctx.waterfall('my-plugin/transform', input, async () => input)
-
-// Listen: next() is mandatory.
-ctx.on('my-plugin/transform', async (_input, next) => {
-  const downstream = await next()
-  return downstream.trim()
-})
-```
-
-::: warning
-A waterfall listener **must call `next()`**. Omitting it short-circuits the pipeline by design, enabling interception and gateway behavior.
-:::
-
-## Typed events
-
-Harness uses TypeScript declaration merging for type-safe events:
-
-```ts
-import '@deepseek-ai/cordis'
-
-declare module '@deepseek-ai/cordis' {
-  interface Events {
-    'my-plugin/ready': (payload: { id: string }) => void
-    'my-plugin/check': (input: string) => boolean | undefined
-    'my-plugin/transform': (input: string, next: () => Promise<string>) => Promise<string>
-  }
-}
-
-// ctx.on('my-plugin/ready', ...) and ctx.emit('my-plugin/ready', ...)
-// are now inferred correctly.
-```
-
-## Cordis events and session records
-
-Harness Cordis events use `namespace/action` names, including `agent/pre-step`, `agent/request`, `agent/request-error`, `tools/result`, and `session/event`. The generated `cordis-surface` regions on the [subsystem pages](../../../subsystems/core.md) record complete signatures and modes.
-
-`turn/*`, `step/*`, `tool/call`, `tool/result`, and `compaction/*` are durable session-event types, not same-named Cordis events. To observe them, listen to `session/event` and inspect `event.type`.
-
-## Event listeners are effects
-
-A listener registered with `ctx.on()` is removed automatically when its plugin unloads:
-
-```ts ignore-check
-export function apply(ctx: Context) {
-  // This listener is removed when the plugin disposes.
-  ctx.on('tools/result', handler)
-}
-```
-
-## Example: logging plugin
-
-This plugin logs tool calls and results:
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import '@deepseek-ai/dsh-tools'
-
-export const name = 'tool-logger'
-
-export function apply(ctx: Context) {
-  ctx.on('tools/result', (exec, result) => {
-    console.log(`[tool] ${exec.name}(${JSON.stringify(exec.arguments)})`)
-    const text = result.content
-      .map(block => block.type === 'text' ? block.text : '')
-      .join('')
-    console.log(`[tool result] ${text.slice(0, 100)}`)
-  })
-}
-```
-
-## Next steps
-
-- [Capability layering](../practice/index.md) — understand events within capability interfaces
-- [LLM adapters](../practice/llm-adapter.md) — implement a complete LLM backend