better-dsh 0.2.3 → 0.2.4

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

@@ -0,0 +1,15 @@
+# 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/dsh-docs/user/develop/practice/dynamic-cordis.zh.md

@@ -0,0 +1,15 @@
+# 用 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/dsh-docs/user/develop/practice/index.md

@@ -0,0 +1,155 @@
+# 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/dsh-docs/user/develop/practice/index.zh.md

@@ -0,0 +1,155 @@
+# 能力的三种角色设计
+
+[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/dsh-docs/user/develop/practice/llm-adapter.md

@@ -0,0 +1,189 @@
+# 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' } }
+  }
+}
+```