super-dsh 0.3.0-a → 0.3.0-d

package/node_modules/better-dsh/dsh-docs/user/develop/practice/dynamic-cordis.md

@@ -1,15 +0,0 @@
-# Extend a running agent with Cordis tools
-
-English | [中文](dynamic-cordis.zh.md)
-
-This practice guide enables [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/extensions/tool-cordis/README.md). The agent can inspect its current Cordis process and mount or unmount model-authored plugins in memory. Temporary plugins disappear when they are unmounted or the process exits and may affect other sessions in the same process.
-
-## Run it
-
-Start the browser interface with the checked-in overlay:
-
-```sh
-pnpm dsh web --patch apps/cli/config/examples/cordis/cordis.yml
-```
-
-The command requires a model credential. The [Cordis tool reference](../../../../packages/extensions/tool-cordis/README.md) defines the tool arguments, lifetime, cleanup, and safety contracts.

package/node_modules/better-dsh/dsh-docs/user/develop/practice/dynamic-cordis.zh.md

@@ -1,15 +0,0 @@
-# 用 Cordis 工具扩展运行中的智能体
-
-[English](dynamic-cordis.md) | 中文
-
-本实战指南启用 [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/extensions/tool-cordis/README.zh.md)。智能体可以检查当前 Cordis 进程，并在内存中挂载或卸载模型编写的插件。临时插件会在卸载或进程退出时消失，并可能影响同一进程中的其他会话。
-
-## 运行
-
-使用仓库内 overlay 启动浏览器界面：
-
-```sh
-pnpm dsh web --patch apps/cli/config/examples/cordis/cordis.yml
-```
-
-该命令需要模型凭据。[Cordis 工具参考](../../../../packages/extensions/tool-cordis/README.zh.md)定义了四类约定：工具参数、存续时间、清理行为和安全性。

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

@@ -1,155 +0,0 @@
-# Three-role capability design
-
-English | [中文](index.zh.md)
-
-This page has two parts: a concept reference for the three-role capability pattern, followed by an advanced tutorial that builds one capability. Complete the [basic plugin path](../basic/index.md) and [services tutorial](../framework/service.md) first.
-
-## Concept reference
-
-When a capability is general enough to need replaceable providers, such as Bash execution, Harness separates three roles: a **Service Definition**, a **Service Provider**, and a **Consumer**. Put the roles in separate packages when they need to evolve or be replaced independently; a package may otherwise own more than one role. The complete capability is its seam. No individual role is a seam.
-
-## Bash example
-
-The Bash execution capability consists of:
-
-- **Service Definition** (`dsh-shell`) — defines the Cordis service and Bash request and result types
-- **Service Provider** (`dsh-bash-local`) — executes commands on the local machine
-- **Consumer** (`dsh-tool-bash`) — exposes the capability as a model-callable tool
-
-```
-┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
-│  dsh-shell   │────▶│  dsh-bash-local  │     │ dsh-tool-bash│
-│(definition) │     │    (provider)     │     │(consumer/tool)│
-└─────────────┘     └──────────────────┘     └──────────────┘
-       ▲                                            │
-       └────────────────────────────────────────────┘
-                    inject: ['shell']
-```
-
-## Benefits of the split
-
-### Replace providers
-
-One Service Definition can have multiple providers selected through `cordis.yml`:
-
-```yaml
-# Local execution
-- name: '@deepseek-ai/dsh-bash-local'
-
-# Replace this row with another package that provides the same service.
-```
-
-The Service Definition and tool remain unchanged while the provider changes.
-
-### Evolve independently
-
-- The Service Definition changes rarely after callers depend on its contract.
-- Service Providers can improve performance and security independently.
-- Consumers can change how they present the capability to the model.
-
-### Decouple dependencies
-
-- The Service Provider depends on the Service Definition.
-- The Consumer depends on the Service Definition.
-- The Service Provider and Consumer **do not depend on each other**.
-
-The [capability-seam reference](../../../capability-seams.md) owns the current built-in families and package links.
-
-## Tutorial: develop a three-role capability
-
-### Step 1: write the Service Definition
-
-```ts ignore-check
-// packages/my-cap/my-cap/src/index.ts
-import { Service, type Context } from '@deepseek-ai/cordis'
-
-declare module '@deepseek-ai/cordis' {
-  interface Context {
-    myCap: MyCapService
-  }
-}
-
-export abstract class MyCapService extends Service {
-  constructor(ctx: Context) {
-    super(ctx, 'myCap')
-  }
-
-  /** Execute the capability. */
-  abstract execute(request: MyCapRequest): Promise<MyCapResult>
-}
-
-export interface MyCapRequest {
-  input: string
-}
-
-export interface MyCapResult {
-  output: string
-}
-```
-
-### Step 2: write a Service Provider
-
-```ts ignore-check
-// packages/my-cap/my-cap-local/src/index.ts
-import type { Context } from '@deepseek-ai/cordis'
-import { MyCapService, type MyCapRequest, type MyCapResult } from '@deepseek-ai/dsh-my-cap'
-
-class MyCapLocal extends MyCapService {
-  async execute(request: MyCapRequest): Promise<MyCapResult> {
-    // Local provider behavior.
-    return { output: request.input.toUpperCase() }
-  }
-}
-
-export const name = 'my-cap-local'
-
-export function apply(ctx: Context) {
-  ctx.plugin(MyCapLocal)
-}
-```
-
-### Step 3: write a consumer
-
-```ts ignore-check
-// packages/my-cap/tool-my-cap/src/index.ts
-import type { Context } from '@deepseek-ai/cordis'
-import { defineTool } from '@deepseek-ai/dsh-tools'
-
-export const name = 'tool-my-cap'
-export const inject = ['tools', 'myCap']
-
-export function apply(ctx: Context) {
-  ctx.tools.register(defineTool({
-    name: 'my_cap',
-    description: 'Execute my capability.',
-    parameters: {
-      input: { type: 'string', required: true },
-    },
-    output: {
-      schema: { type: 'string' },
-      render: (_args, value) => [{ type: 'text', text: value }],
-    },
-    async execute(args) {
-      const result = await ctx.myCap.execute({ input: args.input })
-      return result.output
-    },
-  }))
-}
-```
-
-### Compose them in cordis.yml
-
-```yaml
-- name: '@deepseek-ai/dsh-my-cap-local'
-- name: '@deepseek-ai/dsh-tool-my-cap'
-```
-
-## Design points
-
-- **Do not split preemptively** — use separate packages only when the roles need to evolve independently. A simple tool plugin does not.
-- **The Service Definition owns Request/Result types** — Service Providers and Consumers depend only on the Service Definition package.
-- **Explicit > implicit** — resolve defaults in an explicit `resolve(request): Spec` step rather than hiding `?? default` expressions inside `run()`.
-
-## Next steps
-
-- [LLM adapter](./llm-adapter.md) — implement an LLM provider

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

@@ -1,155 +0,0 @@
-# 能力的三种角色设计
-
-[English](index.md) | 中文
-
-本文分为两部分：先参考三种角色能力模式的概念，再通过高级教程构建一项能力。请先完成[基础插件路径](../basic/index.zh.md)和[服务教程](../framework/service.zh.md)。
-
-## 概念参考
-
-当一项能力足够通用，需要支持可替换的提供方时（例如 Bash 执行），harness 会区分三种角色：**Service Definition**、**Service Provider** 和 **Consumer**。角色需要独立演进或替换时，将它们放入不同包；否则一个包可以承担多个角色。完整能力构成其 seam。任何单一角色都不是 seam。
-
-## 以 Bash 为例
-
-以 Bash 执行能力为例：
-
-- **Service Definition** (`dsh-shell`)：定义 Cordis 服务以及 Bash 请求和结果类型
-- **Service Provider** (`dsh-bash-local`)：在本地计算机上执行命令
-- **Consumer** (`dsh-tool-bash`)：将该能力公开为模型可调用的工具
-
-```
-┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
-│  dsh-shell   │────▶│  dsh-bash-local  │     │ dsh-tool-bash│
-│(definition) │     │    (provider)     │     │(consumer/tool)│
-└─────────────┘     └──────────────────┘     └──────────────┘
-       ▲                                            │
-       └────────────────────────────────────────────┘
-                    inject: ['shell']
-```
-
-## 拆分的好处
-
-### 提供方可替换
-
-同一个 Service Definition 可以有多个提供方，可通过 `cordis.yml` 选择：
-
-```yaml
-# Local execution
-- name: '@deepseek-ai/dsh-bash-local'
-
-# Replace this row with another package that provides the same service.
-```
-
-更换提供方时，Service Definition 和工具均保持不变。
-
-### 独立演进
-
-- 调用方开始依赖 Service Definition 的约定后，Service Definition 很少改动。
-- Service Provider 可以独立优化性能和安全性。
-- Consumer 可以调整能力向模型呈现的方式。
-
-### 依赖解耦
-
-- Service Provider 依赖 Service Definition。
-- Consumer 依赖 Service Definition。
-- Service Provider 和 Consumer **互不依赖**。
-
-当前内置系列及其包链接由[能力 seam 参考](../../../capability-seams.zh.md)负责。
-
-## 教程：开发三种角色的能力
-
-### 第一步：编写 Service Definition
-
-```ts ignore-check
-// packages/my-cap/my-cap/src/index.ts
-import { Service, type Context } from '@deepseek-ai/cordis'
-
-declare module '@deepseek-ai/cordis' {
-  interface Context {
-    myCap: MyCapService
-  }
-}
-
-export abstract class MyCapService extends Service {
-  constructor(ctx: Context) {
-    super(ctx, 'myCap')
-  }
-
-  /** Execute the capability. */
-  abstract execute(request: MyCapRequest): Promise<MyCapResult>
-}
-
-export interface MyCapRequest {
-  input: string
-}
-
-export interface MyCapResult {
-  output: string
-}
-```
-
-### 第二步：编写 Service Provider
-
-```ts ignore-check
-// packages/my-cap/my-cap-local/src/index.ts
-import type { Context } from '@deepseek-ai/cordis'
-import { MyCapService, type MyCapRequest, type MyCapResult } from '@deepseek-ai/dsh-my-cap'
-
-class MyCapLocal extends MyCapService {
-  async execute(request: MyCapRequest): Promise<MyCapResult> {
-    // Local provider behavior.
-    return { output: request.input.toUpperCase() }
-  }
-}
-
-export const name = 'my-cap-local'
-
-export function apply(ctx: Context) {
-  ctx.plugin(MyCapLocal)
-}
-```
-
-### 第三步：编写消费方
-
-```ts ignore-check
-// packages/my-cap/tool-my-cap/src/index.ts
-import type { Context } from '@deepseek-ai/cordis'
-import { defineTool } from '@deepseek-ai/dsh-tools'
-
-export const name = 'tool-my-cap'
-export const inject = ['tools', 'myCap']
-
-export function apply(ctx: Context) {
-  ctx.tools.register(defineTool({
-    name: 'my_cap',
-    description: 'Execute my capability.',
-    parameters: {
-      input: { type: 'string', required: true },
-    },
-    output: {
-      schema: { type: 'string' },
-      render: (_args, value) => [{ type: 'text', text: value }],
-    },
-    async execute(args) {
-      const result = await ctx.myCap.execute({ input: args.input })
-      return result.output
-    },
-  }))
-}
-```
-
-### 在 cordis.yml 中组合
-
-```yaml
-- name: '@deepseek-ai/dsh-my-cap-local'
-- name: '@deepseek-ai/dsh-tool-my-cap'
-```
-
-## 设计要点
-
-- **不要预防性拆分**：只有角色需要独立演进时，才使用不同包。简单的工具插件无需拆分。
-- **Service Definition 拥有 Request/Result 类型**：Service Provider 和 Consumer 只依赖 Service Definition 包。
-- **显式优于隐式**：实现应通过显式的 `resolve(request): Spec` 步骤处理默认值，而不是在 `run()` 中隐藏 `?? default`。
-
-## 下一步
-
-- [LLM（大语言模型）适配器](./llm-adapter.zh.md)：实现一个 LLM 提供方

package/node_modules/better-dsh/dsh-docs/user/develop/practice/llm-adapter.md

@@ -1,189 +0,0 @@
-# LLM adapters
-
-English | [中文](llm-adapter.zh.md)
-
-This guide connects a new LLM provider to Harness.
-
-## Overview
-
-An LLM adapter extends `LlmAdapter` and implements `stream()`, translating Harness's provider-neutral request into a provider API call and translating the response back into Harness chunks.
-
-## Minimal implementation
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import Schema from '@deepseek-ai/schemastery'
-import { LlmAdapter, type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm'
-
-class MyAdapter extends LlmAdapter {
-  private apiKey: string
-
-  constructor(apiKey: string) {
-    super()
-    this.apiKey = apiKey
-  }
-
-  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
-    // 1. Convert options.messages to the provider format.
-    // 2. Call the streaming API.
-    // 3. Convert the response into StreamChunk values.
-  }
-}
-
-export interface Config {
-  apiKey: string
-  providers: string[]
-}
-
-export const Config: Schema<Config> = Schema.object({
-  apiKey: Schema.string().required(),
-  providers: Schema.array(Schema.string()).required(),
-})
-
-export const name = 'my-llm-adapter'
-export const inject = ['llm']
-
-export function apply(ctx: Context, config: Config) {
-  const adapter = new MyAdapter(config.apiKey)
-  ctx.llm.registerAdapter(config.providers, adapter)
-}
-```
-
-## StreamChunk protocol
-
-`stream()` yields chunks using this protocol:
-
-```ts
-import { brandString } from '@deepseek-ai/dsh-brand'
-import type { StreamChunk, ToolCallId } from '@deepseek-ai/dsh-llm'
-
-async function* exampleChunks(): AsyncIterable<StreamChunk> {
-  // 1. Start each content block with block-start.
-  yield { type: 'block-start', index: 0, blockType: 'text' }
-
-  // 2. Stream text through text-delta.
-  yield { type: 'text-delta', index: 0, text: 'Hello' }
-  yield { type: 'text-delta', index: 0, text: ' world' }
-
-  // 3. End each content block with block-end and the complete block.
-  yield {
-    type: 'block-end',
-    index: 0,
-    block: { type: 'text', text: 'Hello world' },
-  }
-
-  // 4. Tool-call block.
-  yield { type: 'block-start', index: 1, blockType: 'tool-call' }
-  yield {
-    type: 'tool-call-delta',
-    index: 1,
-    id: brandString<ToolCallId>('call-123'),
-    name: 'bash',
-    argumentsDelta: '{"command":"ls"}',
-  }
-  yield {
-    type: 'block-end',
-    index: 1,
-    block: {
-      type: 'tool-call',
-      id: brandString<ToolCallId>('call-123'),
-      name: 'bash',
-      arguments: '{"command":"ls"}',
-    },
-  }
-
-  // 5. Token usage.
-  yield { type: 'usage', usage: { inputTokens: 100, outputTokens: 50 } }
-
-  // 6. Finish reason.
-  yield { type: 'finish', reason: { kind: 'stop' } }
-  // Alternatively, { kind: 'tool-calls' } requests tool execution.
-}
-```
-
-### Key rules
-
-- Every `block-start` has a matching `block-end`.
-- `index` increases from 0 and identifies content-block order.
-- A `tool-call-delta` carries raw JSON text in `argumentsDelta`, either all at once or over multiple chunks.
-- `finish` is the final chunk.
-- Emit `usage` before `finish`.
-
-## GenerateOptions
-
-`stream()` receives the exported `GenerateOptions` type. It includes the model, adapter-owned reasoning-effort id, conversation history, system prompt, tool schemas, generation parameters, stop sequences, and abort signal; treat the TypeScript type exported by `@deepseek-ai/dsh-llm` as authoritative. Map supported fields to the provider API. If the provider cannot honor a field, throw `LlmError` with a stable code instead of silently dropping it.
-
-Override `resolveModel(provider, model, signal?)` to return exact provider/model identity plus optional `context` and `reasoning` metadata in one lookup. Reasoning metadata contains ordered opaque ids and display names plus an optional configured default; preserve the adapter's authoritative selectable list, including `off` when its upstream capability API returns it, instead of promoting those values into a core enum. Honor the optional signal for asynchronous lookup so cancellation and disposal reach quiescence. The service validates the aggregate and rejects unsupported explicit efforts before `stream()`; omitting `reasoning` means that model has no selectable reasoning-effort capability.
-
-## Register an adapter
-
-```ts ignore-check
-ctx.llm.registerAdapter(['my-provider'], adapter)
-```
-
-The first argument lists provider routes handled by the adapter. `GenerateOptions.provider` selects the registered adapter, while `GenerateOptions.model` passes an adapter-owned model id without lifecycle registration. Override `listModels()` when the adapter can advertise model choices to selectors.
-
-## Use it from cordis.yml
-
-```yaml
-- id: my-llm
-  name: './src/my-llm-adapter.ts'
-  config:
-    apiKey: !!js process.env.MY_API_KEY
-    providers:
-      - my-provider
-
-- id: agent-loop
-  name: '@deepseek-ai/dsh-agent-loop'
-  config:
-    agents:
-      - id: main
-        provider: my-provider
-        model: my-model-v1
-```
-
-## Reference implementations
-
-The repository contains complete implementations:
-
-- `packages/llm/llm-deepseek/` — DeepSeek API adapter using the OpenAI-compatible format
-- `packages/llm/llm-pi-ai/` — Pi AI adapter using a different API format
-
-Compare the two shipped adapters to see the same harness contract implemented over different provider SDKs.
-
-## Error handling
-
-Adapters throw transport and protocol failures as `LlmError` values with stable codes. The agent loop preserves the error and code for diagnostics and policy; it does not convert an ordinary `Error` automatically. Every provider HTTP request must also merge `attributionHeaders()` and forward `options.signal`.
-
-```ts
-import {
-  attributionHeaders,
-  LlmAdapter,
-  LlmError,
-  type GenerateOptions,
-  type StreamChunk,
-} from '@deepseek-ai/dsh-llm'
-
-class HttpAdapter extends LlmAdapter {
-  constructor(private readonly endpoint: string) {
-    super()
-  }
-
-  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
-    const response = await fetch(this.endpoint, {
-      method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        ...attributionHeaders(),
-      },
-      body: JSON.stringify({ model: options.model, messages: options.messages }),
-      ...options.signal ? { signal: options.signal } : {},
-    })
-    if (!response.ok) {
-      throw new LlmError(`Provider API error: ${response.status}`, 'PROVIDER_HTTP_ERROR')
-    }
-    // A real adapter parses the response and emits the complete chunk sequence.
-    yield { type: 'finish', reason: { kind: 'stop' } }
-  }
-}
-```