Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge origin/master into codex/truncated-design

Browse Source
This commit is contained in:
Dudu-0223
2026-07-17 18:21:54 +08:00
parent 8ab39267f3 44e126e306
commit a3f62478e1
1057 changed files with 42961 additions and 18526 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
packages/util/README.md
View File

@@ -5,10 +5,11 @@ Zero-dependency primitives shared across the other groups. A package lands here
| Package | Role |
|---|---|
| `brand/` | The type-only `Branded<B>` nominal-typing primitive (no runtime code, no harness deps) |
| `paths/` | Shared filesystem path constants and helpers for harness user data |
| `timeout/` | The timing/classification half of a timeout — `clampTimeout`/`deadline`/`timeoutOf`/`TimeoutReason` (pure functions, no harness deps); termination stays in each capability |
| `retention/` | Bounded model-facing output — `ItemRetainer`/`TextRetainer` + neutral notice helpers (pure, no harness deps); business semantics stay in each tool |
`dsh-brand` is the canonical case: it owns ONLY the `Branded<B>` helper, so a capability package can brand the ids it owns (`dsh-bash`'s `BashTaskId`/`OwnerToken`, `dsh-session`'s `SessionId`, …) by depending on `dsh-brand` alone, without pulling in an unrelated package just to reach `Branded`.
`dsh-brand` is the canonical case: it owns ONLY the `Branded<B>` helper, so a capability package can brand the ids it owns (`dsh-tasks`'s `TaskId`, `dsh-session`'s `SessionId`, …) by depending on `dsh-brand` alone, without pulling in an unrelated package just to reach `Branded`.
`dsh-timeout` follows the same shape for the timeout family: `dsh-bash` and `dsh-web-fetch-local` each fuse a caller's cancellation with a deadline and later classify "timed out" vs "cancelled" by depending on `dsh-timeout` alone. It deliberately owns only the timing/classification half — the *termination* (SIGKILL a process group, tear down a fetch socket) stays in each capability, because no shared layer can own every capability's kill (see [the timeout-library RFC](../../docs/rfc/implemented/architecture/2026-07-06-timeout-deadline-library.md)).

6
packages/util/brand/README.md
View File

@@ -17,10 +17,10 @@ export function SessionId(id: string): SessionId {
}
```
Construction goes through the per-id factory in the OWNING package (a plain cast inside — zero runtime cost). Comparison, logging, JSON serialization, and the wire format all behave exactly as for an ordinary string; the brand is erased at compile time.
Construction goes through the per-id factory in the owning package. Comparison, logging, JSON serialization, and the wire format behave as for an ordinary string; the brand is erased at compile time.
## Policy: brand ids that cross package boundaries
A package brands the ids it OWNS — `CallId` in `dsh-llm` (tool-call correlation), `SessionId` in `dsh-session`, `AgentId` in `dsh-agent`, `BashTaskId`/`OwnerToken` in `dsh-bash`. Branding is for ids that cross package boundaries and could plausibly be confused; **not every string needs a brand.**
A package brands the ids it owns — `CallId` in `dsh-llm`, `SessionId` in `dsh-session`, `AgentId` in `dsh-agent`, and `TaskId` in `dsh-tasks`. Brand cross-package ids that could plausibly be confused; not every string needs one.
This package owns ONLY the primitive — no concrete id, no runtime code beyond the (erased) type. Keeping the primitive dependency-free is the point: a capability package can brand its ids without depending on an unrelated package. `dsh-bash`, for example, brands `BashTaskId`/`OwnerToken` by depending on `dsh-brand` alone — it never pulls in `dsh-llm` (or `dsh-session`) just to reach `Branded`.
This package owns only the primitive. Keeping it dependency-free lets `dsh-tasks`, for example, brand `TaskId` without importing an unrelated capability package merely to reach `Branded`.

4
packages/util/brand/package.json
View File

@@ -22,9 +22,9 @@
],
"license": "BSD-3-Clause",
"peerDependencies": {
"cordis": "^4.0.0-rc.6"
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
"cordis": "^4.0.0-rc.6"
"cordis": "^4.0.0-rc.7"
}
}

8
packages/util/brand/src/index.ts
View File

@@ -10,13 +10,13 @@
* comparison, logging, and serialization all behave as ordinary strings.
*
* Policy: a package brands the ids it owns — `CallId` in dsh-llm (tool-call
* correlation), `SessionId` in dsh-session, `AgentId` in dsh-agent,
* `BashTaskId`/`OwnerToken` in dsh-bash. Branding is for ids that cross package
* boundaries and could plausibly be confused; not every string needs a brand.
* correlation), `SessionId` in dsh-session, `AgentId` in dsh-agent, and
* `TaskId` in dsh-tasks. Branding is for ids that cross package boundaries and
* could plausibly be confused; not every string needs a brand.
* This package owns ONLY the primitive — no concrete id, no runtime code beyond
* the (erased) type — so the brand vocabulary stays dependency-free and a
* package can brand its ids without depending on an unrelated capability
* package (e.g. dsh-bash brands its ids without pulling in dsh-llm).
* package.
*
* @module @deepseek-ai/dsh-brand
*/

18
packages/util/paths/README.md Normal file
View File

@@ -0,0 +1,18 @@
# dsh-paths
Shared filesystem path helpers for DeepSeek Harness user data.
## DSH home
`DSH_HOME_DIR_NAME` owns the default user-data directory name: `.dsh`.
`defaultDshHome()` returns the default DeepSeek Harness home by joining the operating-system home directory with `.dsh`, using Node's platform path rules.
`expandHomePath()` expands `~`, `~/...`, and Windows-style `~\...` prefixes against the operating-system home directory. It leaves non-tilde paths and `~user/...` untouched.
This package is intentionally small and harness-dep-free so product packages can share user-data path conventions without depending on one another.
## Known Limitations and Deferred Work
- **Expansion is deliberately narrow** — only bare `~`, `~/...`, and `~\...` use the current operating-system home; named-user forms such as `~alice/...`, environment variables, and shell expressions remain unchanged.
- **Helpers do not touch the filesystem** — callers still own directory creation, existence checks, permissions, and trust policy for the resulting path.

30
packages/util/paths/package.json Normal file
View File

@@ -0,0 +1,30 @@
{
"name": "@deepseek-ai/dsh-paths",
"description": "Shared filesystem path helpers for the DeepSeek Harness",
"version": "0.0.1",
"private": true,
"type": "module",
"main": "lib/index.js",
"types": "lib/types/index.d.ts",
"exports": {
".": {
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
"cordis": "^4.0.0-rc.6"
},
"devDependencies": {
"cordis": "^4.0.0-rc.6"
}
}

47
packages/util/paths/src/index.ts Normal file
View File

@@ -0,0 +1,47 @@
/**
* Shared filesystem path helpers for DeepSeek Harness user data.
*
* @module @deepseek-ai/dsh-paths
*/
import { homedir } from 'node:os'
import { join, resolve } from 'node:path'
/** Directory name for the default DeepSeek Harness home under the OS home. */
export const DSH_HOME_DIR_NAME = '.dsh'
/** Stable user-facing display form for the default DeepSeek Harness home. */
export const DEFAULT_DSH_HOME_DISPLAY = `~/${DSH_HOME_DIR_NAME}`
/** Environment variable that overrides the default DeepSeek Harness home. */
export const DSH_HOME_ENV = 'DSH_HOME'
/**
* Resolve the default DeepSeek Harness home using Node's platform path rules.
* @returns the absolute default harness home path.
*/
export function defaultDshHome(): string {
return join(homedir(), DSH_HOME_DIR_NAME)
}
/**
* Expand supported tilde prefixes against the operating-system home.
* @param path - configured path that may begin with `~`, `~/`, or `~\`.
* @returns the expanded path, or the original value when no supported prefix is present.
*/
export function expandHomePath(path: string): string {
if (path === '~') return homedir()
if (path.startsWith('~/') || path.startsWith('~\\')) return join(homedir(), path.slice(2))
return path
}
/**
* Resolve an explicitly configured, environment-selected, or default DSH home.
* @param configured - explicit harness-home override, which has highest precedence.
* @param env - environment mapping used to read `DSH_HOME`.
* @returns the normalized absolute harness home path.
*/
export function resolveDshHome(configured?: string, env: Record<string, string | undefined> = process.env): string {
const selected = configured ?? env[DSH_HOME_ENV] ?? defaultDshHome()
return resolve(expandHomePath(selected))
}

34
packages/util/paths/tests/paths.spec.ts Normal file
View File

@@ -0,0 +1,34 @@
import { homedir } from 'node:os'
import { join } from 'node:path'
import { describe, expect, it } from 'vitest'
import {
DEFAULT_DSH_HOME_DISPLAY,
DSH_HOME_DIR_NAME,
defaultDshHome,
expandHomePath,
resolveDshHome,
} from '@deepseek-ai/dsh-paths'
describe('dsh path helpers', () => {
it('owns the shared default DSH home directory name', () => {
expect(DSH_HOME_DIR_NAME).toBe('.dsh')
expect(DEFAULT_DSH_HOME_DISPLAY).toBe('~/.dsh')
expect(defaultDshHome()).toBe(join(homedir(), '.dsh'))
})
it('expands tilde paths without changing non-tilde paths', () => {
expect(expandHomePath('~')).toBe(homedir())
expect(expandHomePath('~/.dsh')).toBe(join(homedir(), '.dsh'))
expect(expandHomePath('~\\.dsh')).toBe(join(homedir(), '.dsh'))
expect(expandHomePath('/tmp/.dsh')).toBe('/tmp/.dsh')
expect(expandHomePath('~other/.dsh')).toBe('~other/.dsh')
})
it('resolves explicit DSH home before environment and default locations', () => {
const envHome = join(homedir(), 'env-dsh')
expect(resolveDshHome(undefined, { DSH_HOME: '~/env-dsh' })).toBe(envHome)
expect(resolveDshHome('/tmp/explicit-dsh', { DSH_HOME: '~/env-dsh' })).toBe('/tmp/explicit-dsh')
expect(resolveDshHome(undefined, {})).toBe(defaultDshHome())
})
})

11
packages/util/paths/tsconfig.json Normal file
View File

@@ -0,0 +1,11 @@
{
"extends": "../../../tsconfig.base.json",
"compilerOptions": {
"rootDir": "src",
"outDir": "lib/types"
},
"include": [
"src"
],
"references": []
}

9
packages/util/retention/README.md
View File

@@ -80,3 +80,12 @@ const footer = formatRetentionNotice(
({ kept }) => `Results capped at ${kept}. Narrow the pattern, path, or include to see more.`,
)
```
## Model Experience
Indirectly, through tool consumers that render retained content and omission metadata.
## Known Limitations and Deferred Work
- **Item retention supports `head` only** — tail, head/tail, pagination, grouping, and provider-completeness semantics remain tool-owned.
- **Text retention is byte-oriented** — line and character windows such as `read` pagination require a separate renderer, and a cut may discard partial UTF-8 boundary bytes to keep returned text valid.

10
packages/util/timeout/README.md
View File

@@ -47,3 +47,13 @@ Pass your own `code` to `timeoutOf` so classification composes under nesting: wh
## What does NOT get a timeout
Local file `read`/`write`/`edit` take no `timeoutMs`: a syscall is best-effort-abortable at most, a timeout could not force `fsync`/`rename` to stop, and adding one would be an implicit default that violates explicit-over-implicit. See [`fs/`](../../fs/README.md).
## Model Experience
Indirectly, through consumers such as `dsh-timeout-policy`, which may replace a provider result with a retained timeout error or suppress a late result.
## Known Limitations and Deferred Work
- **Notification only** — a deadline cannot stop work that ignores its signal; every capability still needs its own socket/process/task termination path.
- **`timeoutMs <= 0` is internal vocabulary** — it disables the local timer only after an owning backend has resolved policy, never as a public model/plugin knob.
- **The first abort reason wins classification** — when an upstream cancellation beats the local timer, this layer cannot later report that its own timeout would also have elapsed.

4
packages/util/timeout/package.json
View File

@@ -22,9 +22,9 @@
],
"license": "BSD-3-Clause",
"peerDependencies": {
"cordis": "^4.0.0-rc.6"
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
"cordis": "^4.0.0-rc.6"
"cordis": "^4.0.0-rc.7"
}
}

95
packages/util/timeout/src/index.ts
View File

@@ -1,43 +1,13 @@
/**
* The timing-and-classification half of a timeout — a zero-dependency library
* of pure functions shared by every capability that clamps a caller's timeout
* hint, arms a deadline, and later has to tell "timed out" apart from
* "cancelled". It owns NO termination: the returned {@link deadline} signal only
* NOTIFIES; actually stopping the work (SIGKILL a process group, tear down a
* fetch socket, …) stays in each capability's implementation, because that
* mechanism differs per capability and no shared layer can own all of them.
*
* This is deliberately a library, not a cordis service or plugin: it takes no
* `ctx`, registers nothing, holds no cross-call state, and emits no events. A
* "timeout service" would have to understand how to stop every capability's
* work — exactly the knowledge a microkernel keeps out of shared layers.
*
* The four exports and their division of labor:
* - {@link clampTimeout} — validate a caller's optional positive hint, fill the
* backend default, cap at the backend max (pure arithmetic + the shared
* positive-finite request contract).
* - {@link deadline} — fuse upstream cancellation with a timeout into one
* `AbortSignal`, the timeout carrying an identifiable {@link TimeoutReason};
* `[Symbol.dispose]` clears the timer.
* - {@link timeoutOf} — classify an aborted signal (or error): a
* {@link TimeoutReason} means the timeout fired, anything else (or nothing)
* means it did not.
* - {@link TimeoutReason} — the internal classification reason; providers
* translate it into their own public error/result shape before returning.
*
* Shared timeout arithmetic, signal fusion, and classification. The library
* only notifies through abort signals; each capability still owns the mechanism
* that stops its work and translates timeout reasons into public outcomes.
* @module @deepseek-ai/dsh-timeout
*/
/**
* The internal reason attached to a timeout abort so consumers can classify it
* after the fact. It carries the failing `code` (each capability's own string —
* `BASH_TIMEOUT`, `WEB_FETCH_TIMEOUT`, …) and the `timeoutMs` that elapsed.
*
* It is an INTERNAL classification reason, not a public error: providers
* translate it into their seam-specific error code or result field (via
* {@link timeoutOf}) before returning to callers. Native `AbortSignal.timeout()`
* yields a fixed `TimeoutError` indistinguishable across timeout kinds; this
* type is identifiable and carries the code/duration.
* Internal abort reason carrying a capability-owned code and elapsed deadline.
* Providers translate it through {@link timeoutOf} before returning to callers.
*/
export class TimeoutReason extends Error {
override name = 'TimeoutReason'
@@ -52,16 +22,15 @@ export class TimeoutReason extends Error {
}
/**
* Validate a caller's optional timeout hint, fill it from the backend default,
* then cap at the backend max. The shared positive-finite request contract:
* a supplied `requested` must be a positive finite number or this throws —
* `0` is NOT a caller-facing "disable timeout" value (that sentinel is internal
* to {@link deadline}). A missing `requested` falls back to `def`.
* Validate a caller's optional timeout hint, use the backend default, then cap
* it. Supplied values must be positive and finite; zero is not a public
* disable-timeout sentinel.
*
* @param requested The caller's optional hint; validated when present.
* @param def The backend default applied when `requested` is absent.
* @param max The backend upper bound the result is capped to.
* @param name Field name used in the thrown message (so the caller sees which input was bad).
* @param name Field name used in the thrown message (so the caller sees which input was
* bad).
* @returns The effective timeout in milliseconds: `min(requested ?? def, max)`.
*/
export function clampTimeout(
@@ -85,23 +54,9 @@ export interface Deadline {
}
/**
* Build a deadline signal that aborts on upstream cancellation OR on timeout,
* with the timeout carrying an identifiable {@link TimeoutReason} (unlike
* native `AbortSignal.timeout()`, whose fixed `TimeoutError` is opaque). It is
* `AbortSignal.any([upstream, <timeout>])` — the single primitive that fuses
* two abort sources — with the reason and a disposable timer added on top.
*
* `timeoutMs <= 0` is the INTERNAL "no timeout" sentinel for backend-owned
* background work: arm no timer and forward only the upstream signal; with no
* upstream either, return a never-aborting signal so callers keep one call
* shape. External request hints validate as positive finite via
* {@link clampTimeout} before reaching here, so `0` never arrives from a model
* or plugin.
*
* The returned object's `[Symbol.dispose]` clears the timer — use `using` for a
* scope-lifetime consumer, or call it manually for an event-lifetime one. The
* signal only NOTIFIES; the caller must attach its own termination (kill the
* process group, abort the fetch, …).
* Fuse upstream cancellation with an identifiable timeout. `timeoutMs <= 0` is
* the internal no-timer sentinel; the returned disposer clears an armed timer.
* The signal only notifies, so callers must stop their own work.
*
* @param upstream The caller's cancellation signal, if any, fused into the result.
* @param timeoutMs Deadline in milliseconds; `<= 0` means "no timeout" (arm no timer).
@@ -114,9 +69,8 @@ export function deadline(
code: string,
): Deadline {
if (timeoutMs <= 0) {
// No timeout (background work): forward only the upstream signal, or a
// never-aborting one when there is no upstream. No timer, so dispose is a
// no-op — the empty method keeps the one call shape for every caller.
// No timeout (background work): forward only the upstream signal, or a never-aborting one
// when there is no upstream.
return { signal: upstream ?? new AbortController().signal, [Symbol.dispose]() {} }
}
@@ -132,22 +86,9 @@ export function deadline(
}
/**
* Recover the {@link TimeoutReason} from an aborted signal (or any object with a
* `reason`), else `undefined`. This is the classification half: a provider
* calls it on the deadline signal after an abort to decide whether the cause
* was its timeout (translate to the capability's timeout error/field) or an
* ordinary upstream cancellation (`undefined` → the cancel path).
*
* Pass `code` to scope the match to THIS deadline's timer. It matters under
* nesting: when the `upstream` handed to {@link deadline} is itself a deadline
* signal (e.g. a future `tools/execute` middleware arming a per-call deadline),
* `AbortSignal.any` preserves the OUTER `TimeoutReason` if the outer timer fires
* first. Without `code`, the inner capability would misclassify that outer
* timeout as its own (`timedOut:true` / `WEB_FETCH_TIMEOUT`) though its local
* timer never expired; with `code`, a foreign timeout reads as `undefined` and
* falls through to the upstream-cancel path, which is the correct classification
* from the inner capability's view. Omit `code` only to ask "was this ANY
* timeout" (a generic middleware that owns no single code).
* Recover a timeout reason from a reason-bearing object. Supplying `code`
* distinguishes this deadline from a nested upstream deadline; a foreign code
* follows the ordinary cancellation path.
*
* @param x An {@link AbortSignal} or any `{ reason }` carrier (e.g. a caught abort error).
* @param code When provided, only a {@link TimeoutReason} with this exact `code` matches.

7
packages/util/timeout/tests/timeout.spec.ts
View File

@@ -171,10 +171,9 @@ describe('timeoutOf', () => {
describe('deadline — nested deadlines', () => {
it("does not misclassify an outer deadline's timeout as the inner code", () => {
// The upstream handed to the inner deadline is ITSELF a deadline that has
// already timed out (outer). AbortSignal.any preserves the outer reason;
// scoping timeoutOf to the inner code keeps the inner capability from
// reporting the outer timeout as its own — it reads as an upstream cancel.
// The upstream handed to the inner deadline is ITSELF a deadline that has already timed out
// (outer). `AbortSignal.any` preserves that reason, but scoping `timeoutOf` to the inner code
// must classify it as upstream cancellation rather than the inner capability's timeout.
const outer = new AbortController()
outer.abort(new TimeoutReason('OUTER_TIMEOUT', 30))
using inner = deadline(outer.signal, 60_000, 'BASH_TIMEOUT')