Yichen Jiang
7b54768ee7
# Conflicts: # AGENTS.md # docs/architecture.md # docs/event-producer-consumer.md # docs/module-graph.md # docs/rfc/INDEX.md # packages/bash/bash-local/tests/executor.spec.ts # packages/bash/bash-local/tests/run.spec.ts # packages/core/agent-core/src/index.ts # packages/core/agent-core/tests/agent-core.spec.ts # packages/fs/fs-local/src/fsio.ts # packages/ui/acp-agent/package.json # packages/ui/acp-agent/src/index.ts # packages/ui/acp-agent/tsconfig.json # packages/ui/stdio-agent/package.json # packages/ui/stdio-agent/tsconfig.json # packages/util/README.md # pnpm-lock.yaml # tsconfig.build.json # tsconfig.json
1.7 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) |
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 |
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).