7a1c2779a7
Ship @deepseek-ai/dsh-retention under packages/util/: pure ItemRetainer / TextRetainer plus neutral notice helpers, so tools that cap model-facing output share one "what did we keep, what did we omit, may we stop reading" mechanic while keeping grouping, exit codes, provider errors, and recovery prose tool-owned. The two retainers are separate names because they differ in resource model: item-head can stop the upstream on the first over-cap probe (shouldStop), while text tail/head-tail must read to the end. The library documents glob/grep/bash/web_fetch/web_search mappings but migrates no tool yet — glob/grep don't exist, and migration is deliberately separate work. Flips the RFC to implemented/ and rewrites its skeleton to shipped reality.
2.3 KiB
util/ — low-level shared utilities
Zero-dependency primitives shared across the other groups. A package lands here when it owns a tiny, foundational type or helper that several capability families need but that belongs to none of them — keeping it out of any one group avoids a capability package depending on an unrelated one just to reach a shared primitive. These are support packages: small, stable, and free of harness dependencies.
| Package | Role |
|---|---|
brand/ |
The type-only Branded<B> nominal-typing primitive (no runtime code, no harness deps) |
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-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).
dsh-retention is the same split for bounded tool output: a tool (glob/grep/bash/web_fetch/web_search) feeds items or text into a retainer and gets back "what we kept, what we omitted, may you stop reading" — while grouping, exit codes, provider errors, and recovery prose stay tool-owned. It deliberately owns only the retention mechanic; truncated is a budget fact, never an "incomplete inspection" state (see the retention-library RFC).