dsh-plugin-dev-kb 1.6.0 → 1.8.1

package/kb/site/en/develop/practice/llm-adapter.md

@@ -1,192 +1,192 @@
----
-editSource: "docs/user/develop/practice/llm-adapter.md"
-rawMarkdownPath: "en/develop/practice/llm-adapter.md"
----
-
-# LLM adapters
-
-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 adapter using the Messages API
-- `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' } }
-  }
-}
-```
+---
+editSource: "docs/user/develop/practice/llm-adapter.md"
+rawMarkdownPath: "en/develop/practice/llm-adapter.md"
+---
+
+# LLM adapters
+
+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 adapter using the Messages API
+- `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. `new LlmError` accepts only the built-in codes of `LLM_FAILURE_CODES`; an adapter's own code goes through `LlmError.fromFailure`. 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 LlmError.fromFailure({ message: `Provider API error: ${response.status}`, code: 'PROVIDER_HTTP_ERROR', status: response.status })
+    }
+    // A real adapter parses the response and emits the complete chunk sequence.
+    yield { type: 'finish', reason: { kind: 'stop' } }
+  }
+}
+```

package/kb/site/en/guide/desktop-uninstall-cleanup.md

@@ -0,0 +1,63 @@
+---
+editSource: "docs/user/guide/desktop-uninstall-cleanup.md"
+rawMarkdownPath: "en/guide/desktop-uninstall-cleanup.md"
+---
+
+# Uninstall DSH Desktop
+
+Use this guide to uninstall DeepSeek Harness Desktop on macOS or Windows. Local data cleanup is optional.
+
+## 1. Uninstall the app
+
+Finish any commands using Desktop's bundled CLI. If you installed the `dsh` command through Desktop, first select **Manage dsh Command… → Remove** in the application menu. This removes Desktop's command registration without uninstalling independent CLI programs.
+
+Quit DeepSeek Harness, then uninstall it using your platform's procedure:
+
+- **macOS:** Delete the app from Applications in Finder.
+- **Windows:** Uninstall it through Settings → Apps → Installed apps on Windows 11, or Control Panel → Programs → Programs and Features.
+
+## 2. Clean up local data
+
+This step is optional. If you want to clean up local data, select the script for your platform below, then paste and run it in Terminal on macOS or PowerShell on Windows.
+
+The scripts permanently delete the current user's default Harness home and the Desktop data paths listed below, including sessions, credentials, settings, plugins, caches, and shared CLI state. If you configured `DSH_HOME`, inspect that directory separately before deleting it; the scripts still delete the default `~/.dsh`. Isolated development and test data directories are outside this cleanup scope.
+
+On Windows, the uninstaller normally removes the two application-data directories listed in the script but retains the Harness home. The script also handles those directories if uninstallation left files behind or retained app data.
+
+::: code-group
+
+```sh [macOS]
+sh -c '
+rm -rf -- \
+  "$HOME/.dsh" \
+  "$HOME/Library/Application Support/@deepseek-ai/dsh-desktop" \
+  "$HOME/Library/Logs/DeepSeek Harness" \
+  "$HOME/Library/Preferences/com.deepseek.dsh.plist" \
+  "$HOME/Library/Preferences/ByHost"/com.deepseek.dsh.ShipIt.*.plist \
+  "$HOME/Library/Caches/com.deepseek.dsh" \
+  "$HOME/Library/Caches/com.deepseek.dsh.ShipIt" \
+  "$HOME/Library/HTTPStorages/com.deepseek.dsh" \
+  "$HOME/Library/Caches/@deepseek-aidsh-desktop-updater" \
+  "$(getconf DARWIN_USER_CACHE_DIR)/com.deepseek.dsh" \
+  "$(getconf DARWIN_USER_CACHE_DIR)/com.deepseek.dsh.helper"
+'
+```
+
+```powershell [Windows]
+$ErrorActionPreference = 'Stop'
+@(
+    (Join-Path $env:USERPROFILE '.dsh'),
+    (Join-Path $env:APPDATA '@deepseek-ai\dsh-desktop'),
+    (Join-Path $env:LOCALAPPDATA '@deepseek-aidsh-desktop-updater')
+) | ForEach-Object {
+    if (Test-Path -LiteralPath $_) {
+        Remove-Item -LiteralPath $_ -Recurse -Force
+    }
+}
+```
+
+:::
+
+## 3. Verify cleanup
+
+If you ran a cleanup script, confirm before reinstalling that the paths listed in it no longer exist. If the script reports an error, resolve it, rerun the script, and check all listed paths again. The Windows script stops at the first error, so later paths may remain.

package/kb/site/en/guide/network-proxy.md

@@ -60,7 +60,7 @@ export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
 
 Node reads that variable only at process start, so export it before running `dsh`.
 
-**Tools DSH runs for you follow the same proxy.** Commands in the bash tool, `git`, `gh`, and MCP servers started as child processes all inherit these variables. A child that is itself a Node program honors them only on Node 22.21 or later; an older Node connects directly. If one of your proxy variables holds a value DSH rejected — a SOCKS URL, say — Node-based tools also connect directly rather than fail to start, while `curl` and `git` still read that value.
+**Tools DSH runs for you follow the same proxy.** Commands in the bash tool, `git`, `gh`, and MCP servers started as child processes all inherit these variables. A child Node program uses its own installed runtime: Node 22.21+ and Node 24+ honor these variables; an older runtime connects directly. If one of your proxy variables holds a value DSH rejected — a SOCKS URL, say — Node-based tools also connect directly rather than fail to start, while `curl` and `git` still read that value.
 
 **A password in the proxy URL reaches those tools too.** `HTTPS_PROXY=http://alice:s3cret@proxy.example:8080` is a normal environment variable, so every command DSH runs — including the ones the model writes — can read it, and a command that prints its environment puts the password in output that is kept. This is how the variable already behaves for everything else in your shell. If that matters, give the proxy a credential-free entry point, or authenticate it some other way than in the URL.