super-dsh 0.3.0-c → 0.3.0-e

package/node_modules/better-dsh/dsh-docs/tool-execution-pipeline.md

@@ -1,62 +0,0 @@
-<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
-     Run `pnpm run gen-doc-graphs` to regenerate. -->
-
-# Tool Execution Pipeline
-
-This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering run without changing the loop. The `tools/pre-execute` waterfall runs first, monotonic guards run next, and the `tools/execute` and `tools/post-execute` waterfalls follow; the three waterfalls may transform a call. Definition-owned `finalizeContent` and `tools/result` run afterward.
-
-```mermaid
-flowchart TD
-  model["Assistant message contains tool-call block"]
-  toolCall["Session event: <code>tool/call</code><br/>logged before execution"]
-  presentCall["UI pending card<br/>presentCall(args)"]
-  pre["<code>tools/pre-execute</code> waterfall<br/>hooks, permission, sandbox"]
-  guards["Registered monotonic guards<br/>deny or abstain; identity protected"]
-  denied["denied or approval refused<br/>tool body skipped"]
-  approval["<code>ctx.approval</code> one-shot prompt<br/>absent or unanswerable: deny"]
-  around["<code>tools/execute</code> waterfall<br/>timeout, retry, metrics (around dispatch)"]
-  toolBody["Registered tool execute() body"]
-  fsGate["<code>fs/write-intent</code> or <code>fs/edit-intent</code><br/>tool-fs mutations only"]
-  owned["Tool-owned session events<br/><code>todo/write</code>, <code>fs/observed</code>, <code>hook/invoked</code>, <code>hook/result</code>, <code>tool/code-dispatch</code>"]
-  post["<code>tools/post-execute</code> waterfall<br/>accept, block, replace, add context"]
-  normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"]
-  finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"]
-  final["<code>tools/result</code> synchronous notification<br/>frozen authoritative outcome"]
-  context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"]
-  toolResult["Session event: <code>tool/result</code><br/>single model-facing outcome"]
-  allResults["Tool batch settled<br/>recorded tool/result events complete"]
-  presentResult["UI completed card<br/>presentResult(args, result)"]
-  model --> toolCall
-  toolCall --> presentCall
-  toolCall --> pre
-  pre -->|allow| guards
-  guards -->|allow| around
-  guards -->|deny| denied
-  guards -.->|throw| normalized
-  around --> toolBody
-  pre -->|deny| denied
-  pre -->|ask| approval
-  approval -->|allowed-once| guards
-  approval -->|rejected, cancelled, unavailable| denied
-  approval -.->|throw| normalized
-  denied --> post
-  pre -.->|throw| normalized
-  toolBody --> fsGate
-  fsGate --> toolBody
-  toolBody --> owned
-  toolBody --> around
-  around --> post
-  around -.->|wrapper throws| normalized
-  post -.->|throw| normalized
-  post --> finalize
-  normalized --> finalize
-  finalize --> final
-  final --> toolResult
-  toolResult --> presentResult
-  toolResult --> allResults
-  allResults --> context
-```
-
-Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`. The registry losslessly snapshots the candidate result and normalizes a snapshot failure before the visible definition's snapshotted `finalizeContent` callback enforces its synchronous content-only invariant. `tools/result` then observes the immutable, lossless-JSON outcome. This lets hooks span tool families without coupling the tools to one policy service. PTC mode sends both the reserved `run_code` transport and its serialized sub-calls through the pipeline; sub-calls carry the parent token, log `tool/code-dispatch`, return denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.
-
-Maintenance mode: curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs.

package/node_modules/better-dsh/dsh-docs/tool-execution-pipeline.zh.md

@@ -1,64 +0,0 @@
-<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
-     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/tool-execution-pipeline.md` 重新记录配对。 -->
-
-# 工具执行流水线
-
-[English](tool-execution-pipeline.md) | 中文
-
-此图展示策略、钩子、沙箱、文件系统守卫、结果重写、最终结果观察和 UI 渲染在不改变循环的情况下何时运行。`tools/pre-execute` waterfall（瀑布式事件）首先运行，随后是单调守卫，然后运行 `tools/execute` 和 `tools/post-execute` waterfall；这三个 waterfall 可以改写一次调用。由定义自身控制的 `finalizeContent` 和 `tools/result` 在此之后运行。
-
-```mermaid
-flowchart TD
-  model["Assistant message contains tool-call block"]
-  toolCall["Session event: <code>tool/call</code><br/>logged before execution"]
-  presentCall["UI pending card<br/>presentCall(args)"]
-  pre["<code>tools/pre-execute</code> waterfall<br/>hooks, permission, sandbox"]
-  guards["Registered monotonic guards<br/>deny or abstain; identity protected"]
-  denied["denied or approval refused<br/>tool body skipped"]
-  approval["<code>ctx.approval</code> one-shot prompt<br/>absent or unanswerable: deny"]
-  around["<code>tools/execute</code> waterfall<br/>timeout, retry, metrics (around dispatch)"]
-  toolBody["Registered tool execute() body"]
-  fsGate["<code>fs/write-intent</code> or <code>fs/edit-intent</code><br/>tool-fs mutations only"]
-  owned["Tool-owned session events<br/><code>todo/write</code>, <code>fs/observed</code>, <code>hook/invoked</code>, <code>hook/result</code>, <code>tool/code-dispatch</code>"]
-  post["<code>tools/post-execute</code> waterfall<br/>accept, block, replace, add context"]
-  normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"]
-  finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"]
-  final["<code>tools/result</code> synchronous notification<br/>frozen authoritative outcome"]
-  context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"]
-  toolResult["Session event: <code>tool/result</code><br/>single model-facing outcome"]
-  allResults["Tool batch settled<br/>recorded tool/result events complete"]
-  presentResult["UI completed card<br/>presentResult(args, result)"]
-  model --> toolCall
-  toolCall --> presentCall
-  toolCall --> pre
-  pre -->|allow| guards
-  guards -->|allow| around
-  guards -->|deny| denied
-  guards -.->|throw| normalized
-  around --> toolBody
-  pre -->|deny| denied
-  pre -->|ask| approval
-  approval -->|allowed-once| guards
-  approval -->|rejected, cancelled, unavailable| denied
-  approval -.->|throw| normalized
-  denied --> post
-  pre -.->|throw| normalized
-  toolBody --> fsGate
-  fsGate --> toolBody
-  toolBody --> owned
-  toolBody --> around
-  around --> post
-  around -.->|wrapper throws| normalized
-  post -.->|throw| normalized
-  post --> finalize
-  normalized --> finalize
-  finalize --> final
-  final --> toolResult
-  toolResult --> presentResult
-  toolResult --> allResults
-  allResults --> context
-```
-
-文件系统的先读后编辑检查位于 `tool-fs` 之下，通过 `fs/*` 事件实现。通用的前置／后置 waterfall 承载钩子与审批策略；`ctx.approval` 在单调守卫之前处理询问，而不得重新排序的所有者策略仍作为已注册的守卫。超时等环绕分发关注点对 `tools/execute` 进行包装。注册表会对候选结果进行无损快照；如果快照失败，则会先将失败规范化，之后再由可见定义中已随快照固定的 `finalizeContent` 回调强制执行其同步且仅限内容的不变式。随后，`tools/result` 会观察不可变、可由 JSON 无损表示的结果。这样一来，钩子便可跨越不同工具系列，而无需让工具与某个策略服务耦合。PTC mode 会将保留的 `run_code` 传输及其序列化子调用都送入流水线；子调用携带父级 token、记录 `tool/code-dispatch`、将拒绝呈现为具有约束力的驳回，并省略 `additionalContexts`，以保持调用与结果相邻。
-
-维护模式：英文源文件包含人工维护的 Mermaid 流程图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的工具 schema 与事件签名位于生成的目录中。

package/node_modules/better-dsh/dsh-docs/user/develop/basic/config.md

@@ -1,106 +0,0 @@
-# Plugin configuration
-
-English | [中文](config.zh.md)
-
-Accept configuration supplied through `cordis.yml`.
-
-## Define the Config type
-
-Export a `Config` type and a same-named Schemastery schema. Put defaults directly on the schema fields:
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import Schema from '@deepseek-ai/schemastery'
-
-export const name = 'my-plugin'
-
-export interface Config {
-  greeting: string
-  maxRetries: number
-  verbose?: boolean
-}
-
-export const Config: Schema<Config> = Schema.object({
-  greeting: Schema.string().default('Hello'),
-  maxRetries: Schema.number().default(3),
-  verbose: Schema.boolean().default(false),
-})
-
-export function apply(ctx: Context, config: Config) {
-  console.log(config.greeting)  // User value or schema default.
-}
-```
-
-Add the configuration to the inserted local plugin row in `scratch-plugin/cordis.yml`:
-
-```yaml
-- insert:
-    - id: hello
-      name: './src/my-plugin.ts'
-      config:
-        greeting: 'Hi there'
-        maxRetries: 5
-```
-
-When loading the plugin, Cordis uses the exported schema to validate configuration and fill defaults. Do not export a plain object as `Config`; it does not implement the Standard Schema interface required by Cordis.
-
-## Schema validation
-
-Use Schemastery to express stricter validation:
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import Schema from '@deepseek-ai/schemastery'
-
-export const name = 'validated-plugin'
-
-export interface Config {
-  apiKey: string
-  timeout: number
-  mode: 'fast' | 'accurate'
-}
-
-export const Config = Schema.object({
-  apiKey: Schema.string().required(),
-  timeout: Schema.number().default(30000),
-  mode: Schema.union(['fast', 'accurate']).default('fast'),
-})
-
-export function apply(ctx: Context, config: Config) {
-  // config is validated and type-safe.
-}
-```
-
-The schema runs while the plugin loads. Invalid configuration fails the load with an actionable error.
-
-## Design principles
-
-### Do not hardcode tunable values
-
-Harness requires **anything that two deployments may want to set differently to be a configuration field**.
-
-```ts
-// Wrong: hardcoded timeout.
-const TIMEOUT = 30000
-
-// Correct: configurable.
-export interface Config {
-  timeoutMs: number  // Defaults to 30000.
-}
-```
-
-The test is whether `cordis.yml` can change the value without a code edit.
-
-### Fail loudly on invalid configuration
-
-Express self-contained constraints in the schema so invalid configuration fails while the plugin loads. References to services or registered resources require dependency injection; the [services tutorial](../framework/service.md) introduces that contract.
-
-## Work with HMR
-
-A configuration edit hot-replaces the plugin: the framework unloads the old instance and loads a new one. Because registrations are effects and clean themselves up, replacement does not retain the old instance's registrations.
-
-## Next steps
-
-- [Package and install a plugin](./publish.md) — ship the plugin as an installable package
-- [Plugins and lifecycle](../framework/index.md) — understand the full plugin lifecycle
-- [Services and dependencies](../framework/service.md) — provide a service to other plugins

package/node_modules/better-dsh/dsh-docs/user/develop/basic/config.zh.md

@@ -1,106 +0,0 @@
-# 插件配置
-
-[English](config.md) | 中文
-
-让你的插件接受用户在 `cordis.yml` 中传入的配置。
-
-## 定义 Config 类型
-
-在插件中导出一个 `Config` 类型和同名的 Schemastery schema；默认值直接写在 schema 中：
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import Schema from '@deepseek-ai/schemastery'
-
-export const name = 'my-plugin'
-
-export interface Config {
-  greeting: string
-  maxRetries: number
-  verbose?: boolean
-}
-
-export const Config: Schema<Config> = Schema.object({
-  greeting: Schema.string().default('Hello'),
-  maxRetries: Schema.number().default(3),
-  verbose: Schema.boolean().default(false),
-})
-
-export function apply(ctx: Context, config: Config) {
-  console.log(config.greeting)  // User value or schema default.
-}
-```
-
-在 `scratch-plugin/cordis.yml` 新插入的本地插件行中添加配置：
-
-```yaml
-- insert:
-    - id: hello
-      name: './src/my-plugin.ts'
-      config:
-        greeting: 'Hi there'
-        maxRetries: 5
-```
-
-插件加载时，Cordis 会通过导出的 schema 校验配置，并填充未提供字段的默认值。不要导出普通对象作为 `Config`，因为它不满足 Cordis 要求的 Standard Schema 接口。
-
-## Schema 校验
-
-对于需要严格校验的场景，使用 Schemastery 定义 schema：
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import Schema from '@deepseek-ai/schemastery'
-
-export const name = 'validated-plugin'
-
-export interface Config {
-  apiKey: string
-  timeout: number
-  mode: 'fast' | 'accurate'
-}
-
-export const Config = Schema.object({
-  apiKey: Schema.string().required(),
-  timeout: Schema.number().default(30000),
-  mode: Schema.union(['fast', 'accurate']).default('fast'),
-})
-
-export function apply(ctx: Context, config: Config) {
-  // config is validated and type-safe.
-}
-```
-
-Schema 在插件加载时执行校验。如果配置不合法，插件会加载失败并给出明确错误信息。
-
-## 设计原则
-
-### 无硬编码可调参数
-
-Harness 的约定：**凡是不同部署可能需要采用不同值的参数，都必须定义为配置字段**。
-
-```ts
-// Wrong: hardcoded timeout.
-const TIMEOUT = 30000
-
-// Correct: configurable.
-export interface Config {
-  timeoutMs: number  // Defaults to 30000.
-}
-```
-
-检验标准：能否在 `cordis.yml` 中改变这个值，而不需要修改代码？
-
-### 配置错误要响亮
-
-在 schema 中表达自身完备的约束，使无效配置在插件加载时失败。对服务或已注册资源的引用需要依赖注入；[服务教程](../framework/service.zh.md) 会介绍这项约定。
-
-## 配合 HMR
-
-配置变更会触发插件热替换：修改 `cordis.yml` 中某个插件的 `config` 后，框架会卸载旧实例并加载新实例。由于注册都属于 effect 并会自动清理，替换后不会保留旧实例的注册。
-
-## 下一步
-
-- [打包与安装插件](./publish.zh.md) — 把插件以可安装包的形式交付
-- [插件与生命周期](../framework/index.zh.md) — 深入了解插件的完整生命周期
-- [服务与依赖](../framework/service.zh.md) — 让你的插件对外提供服务

package/node_modules/better-dsh/dsh-docs/user/develop/basic/index.md

@@ -1,144 +0,0 @@
-# Your first plugin
-
-English | [中文](index.zh.md)
-
-This tutorial creates a minimal Harness plugin and loads it into the Web UI. Start from a repository checkout that has completed the [run-from-source path](../../../../README.md#run-from-source).
-
-## Create a local project
-
-From the repository root, create a scratch project for the tutorial:
-
-```sh
-mkdir -p scratch-plugin/src
-```
-
-## What is a plugin?
-
-In Harness, a plugin is a TypeScript module that exports an `apply` function. The framework calls `apply` when loading the plugin and passes a `ctx` context object through which the plugin registers capabilities:
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-export const name = 'my-plugin'
-
-export function apply(ctx: Context) {
-  // Register capabilities here.
-}
-```
-
-That is the complete configuration.
-
-## Create the plugin file
-
-Create `scratch-plugin/src/my-plugin.ts`:
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-export const name = 'hello-plugin'
-
-export function apply(ctx: Context) {
-  // Required dependencies are ready before apply runs.
-  console.log('[hello-plugin] plugin loaded!')
-}
-```
-
-## Register it in cordis.yml
-
-Run `pwd` from the repository root, then create `scratch-plugin/cordis.yml` as a Web overlay that inserts the local plugin. Replace `/absolute/path/to/deepseek-harness` below with the printed path:
-
-```yaml
-- insert:
-    - id: hello
-      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
-```
-
-The plugin path must be absolute. A patch file contributes configuration but does not change the profile directory from which the loader resolves module paths.
-
-Start the Web UI with that overlay:
-
-```sh
-pnpm dsh web --patch ./scratch-plugin/cordis.yml
-```
-
-Open `http://127.0.0.1:3080`. The terminal prints `[hello-plugin] plugin loaded!` during startup.
-
-## Automatic cleanup
-
-Anything registered through `ctx`—event listeners, tools, or timers—is cleaned up when the plugin unloads. You do not need to call removeListener or clearInterval manually.
-
-For a resource that needs explicit cleanup, such as a network connection, use `ctx.effect()` to provide its disposer:
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-export function apply(ctx: Context) {
-  ctx.effect(() => {
-    const timer = setInterval(() => {
-      console.log('heartbeat')
-    }, 5000)
-
-    // The returned function runs when the plugin unloads.
-    return () => clearInterval(timer)
-  })
-}
-```
-
-## Declare dependencies
-
-If the plugin consumes another service such as `tools` or `llm`, declare it in `inject`:
-
-```ts ignore-check
-import type { Context } from '@deepseek-ai/cordis'
-
-export const name = 'my-tool-plugin'
-export const inject = ['tools']
-
-export function apply(ctx: Context) {
-  // ctx.tools is ready here.
-  ctx.tools.register(/* ... */)
-}
-```
-
-The framework waits for every required service before loading the plugin.
-
-## Three plugin forms
-
-In addition to a function module, a plugin can use object or class form.
-
-### Object form
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-export default {
-  name: 'my-plugin',
-  inject: ['tools'],
-  apply(ctx: Context) {
-    // ...
-  },
-}
-```
-
-### Class form
-
-```ts
-import { Service, type Context } from '@deepseek-ai/cordis'
-
-export default class MyService extends Service {
-  static inject = ['tools']
-
-  constructor(ctx: Context) {
-    super(ctx, 'myService')
-    // Perform synchronous initialization in the constructor.
-  }
-}
-```
-
-Function form is sufficient in most cases. Use class form when the plugin provides a service to other plugins; see [services and dependencies](../framework/service.md).
-
-## Next steps
-
-- [Build a tool](./tool.md) — learn the tool definition DSL
-- [Plugin configuration](./config.md) — accept user configuration
-- [Cordis tutorial](../../../cordis-tutorial/index.md) — the plugin framework underneath, built from a scratch directory with no API key

package/node_modules/better-dsh/dsh-docs/user/develop/basic/index.zh.md

@@ -1,144 +0,0 @@
-# 第一个插件
-
-[English](index.md) | 中文
-
-本教程会创建一个最小的 Harness 插件，并将其加载到 Web UI 中。请从已完成[从源码运行路径](../../../../README.zh.md#run-from-source)的仓库检出开始。
-
-## 创建本地项目
-
-在仓库根目录创建本教程使用的临时项目：
-
-```sh
-mkdir -p scratch-plugin/src
-```
-
-## 插件是什么
-
-在 Harness 中，插件是一个导出 `apply` 函数的 TypeScript 模块。框架在加载时调用 `apply`，传入一个 `ctx`（上下文对象），你通过 `ctx` 注册能力：
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-export const name = 'my-plugin'
-
-export function apply(ctx: Context) {
-  // Register capabilities here.
-}
-```
-
-这就是完整配置。
-
-## 创建插件文件
-
-创建 `scratch-plugin/src/my-plugin.ts`：
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-export const name = 'hello-plugin'
-
-export function apply(ctx: Context) {
-  // Required dependencies are ready before apply runs.
-  console.log('[hello-plugin] plugin loaded!')
-}
-```
-
-## 注册到 cordis.yml
-
-在仓库根目录运行 `pwd`，然后创建 `scratch-plugin/cordis.yml`，作为插入本地插件的 Web 覆盖层。请将下文的 `/absolute/path/to/deepseek-harness` 替换为命令打印的路径：
-
-```yaml
-- insert:
-    - id: hello
-      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
-```
-
-插件路径必须是绝对路径。patch 文件只贡献配置，不会改变 loader 解析模块路径时使用的 profile 目录。
-
-使用该覆盖层启动 Web UI：
-
-```sh
-pnpm dsh web --patch ./scratch-plugin/cordis.yml
-```
-
-打开 `http://127.0.0.1:3080`。启动期间，终端会打印 `[hello-plugin] plugin loaded!`。
-
-## 自动清理
-
-通过 `ctx` 注册的任何东西——事件监听、工具、定时器——在插件卸载时都会被自动清理。你不需要手动 removeListener 或 clearInterval。
-
-如果你有需要手动清理的资源（比如一个网络连接），用 `ctx.effect()` 告诉框架怎么清理：
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-export function apply(ctx: Context) {
-  ctx.effect(() => {
-    const timer = setInterval(() => {
-      console.log('heartbeat')
-    }, 5000)
-
-    // The returned function runs when the plugin unloads.
-    return () => clearInterval(timer)
-  })
-}
-```
-
-## 声明依赖
-
-如果你的插件需要使用其他服务（如 `tools`、`llm`），需要声明 `inject`：
-
-```ts ignore-check
-import type { Context } from '@deepseek-ai/cordis'
-
-export const name = 'my-tool-plugin'
-export const inject = ['tools']
-
-export function apply(ctx: Context) {
-  // ctx.tools is ready here.
-  ctx.tools.register(/* ... */)
-}
-```
-
-框架会确保依赖的服务就绪后才加载你的插件。
-
-## 插件的三种形态
-
-除了函数形式，插件还支持对象形式和类形式：
-
-### 对象形式
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-export default {
-  name: 'my-plugin',
-  inject: ['tools'],
-  apply(ctx: Context) {
-    // ...
-  },
-}
-```
-
-### 类形式
-
-```ts
-import { Service, type Context } from '@deepseek-ai/cordis'
-
-export default class MyService extends Service {
-  static inject = ['tools']
-
-  constructor(ctx: Context) {
-    super(ctx, 'myService')
-    // Perform synchronous initialization in the constructor.
-  }
-}
-```
-
-大多数情况下，函数形式足够了。当插件需要向其他插件提供服务时，可使用类形式（见 [服务与依赖](../framework/service.zh.md)）。
-
-## 下一步
-
-- [开发一个工具](./tool.zh.md) — 了解工具定义 DSL
-- [插件配置](./config.zh.md) — 让插件接受用户配置
-- [Cordis 框架教程](../../../cordis-tutorial/index.zh.md) — 底层的插件框架，在临时目录中动手构建，无需 API 密钥