docs: unwrap hard-wrapped Markdown to one line per paragraph

Hard line breaks mid-paragraph make docs harder to edit and diff — a
one-word change reflows and re-diffs the whole paragraph. Reflow all
tracked non-vendor Markdown (plus vendor/AGENTS.md) so each prose
paragraph is a single line; soft-wrapping is the editor's job. Fenced
code, tables, and list structure are preserved (wrapped list items fold
to one line per bullet). Documents the convention in AGENTS.md.
This commit is contained in:
Tianyi Cui
2026-06-13 18:39:20 +08:00
parent e98c1c5d42
commit 066f94c7e0
39 changed files with 348 additions and 1206 deletions

View File

@@ -1,25 +1,20 @@
# dsh-agent
Agent interface, registry, and `agent/*` event vocabulary. Every plugin (UI,
hooks, orchestrators) programs against the `Agent` handle defined here — it has
zero loop dependency, so the loop is swappable.
Agent interface, registry, and `agent/*` event vocabulary. Every plugin (UI, hooks, orchestrators) programs against the `Agent` handle defined here — it has zero loop dependency, so the loop is swappable.
## Service: `AgentRegistry` (ctx key: `agents`)
Tracks live agents so UI, hook, and orchestrator plugins can find them without
importing the concrete loop package.
Tracks live agents so UI, hook, and orchestrator plugins can find them without importing the concrete loop package.
### Public API
- `ctx.agents.register(agent: Agent): () => void`
Register a live agent. Disposed with the calling fiber.
- `ctx.agents.register(agent: Agent): () => void` Register a live agent. Disposed with the calling fiber.
- `ctx.agents.get(id: string): Agent | undefined`
- `ctx.agents.list(): Agent[]`
### Events
The full `agent/*` event taxonomy is declared via declaration merging in
`dsh-agent` (not `dsh-agent-loop`), so plugins depend only on this package.
The full `agent/*` event taxonomy is declared via declaration merging in `dsh-agent` (not `dsh-agent-loop`), so plugins depend only on this package.
#### Lifecycle (emit)
@@ -34,12 +29,9 @@ The full `agent/*` event taxonomy is declared via declaration merging in
#### Interception seams (waterfall)
- `agent/request` — mutate `GenerateOptions` before the model call (hooks,
compaction, model switching, tool filtering)
- `agent/step-result` — post-process the assembled assistant message before tool
dispatch (validates what the log records)
- `agent/turn-continuation` — override the continue/stop decision
(force-continue /loop, force-stop budget guard)
- `agent/request` — mutate `GenerateOptions` before the model call (hooks, compaction, model switching, tool filtering)
- `agent/step-result` — post-process the assembled assistant message before tool dispatch (validates what the log records)
- `agent/turn-continuation` — override the continue/stop decision (force-continue /loop, force-stop budget guard)
#### Streaming + tool (emit)
@@ -52,20 +44,15 @@ The full `agent/*` event taxonomy is declared via declaration merging in
The handle every plugin programs against:
- `agent.send(content, options?)` — queue a message; starts a turn when idle
- `agent.steer(content, options?)` — steer a running turn (inject between steps);
behaves like `send` when idle
- `agent.inject(content, options?)` — inject in-session context without triggering
a turn (context/message event); next request sees it
- `agent.steer(content, options?)` — steer a running turn (inject between steps); behaves like `send` when idle
- `agent.inject(content, options?)` — inject in-session context without triggering a turn (context/message event); next request sees it
- `agent.abort(reason?)` — abort the in-flight step
- `agent.session`, `agent.status`, `agent.options`, `agent.id`
### Extension points
- Agent creation: `AgentLoop.create()` is the concrete implementation (in
`dsh-agent-loop`). Replace the loop by implementing `Agent` and registering
via `ctx.agents.register()`.
- Event listeners: all `agent/*` events are declared here — no dependency on the
loop package needed.
- Agent creation: `AgentLoop.create()` is the concrete implementation (in `dsh-agent-loop`). Replace the loop by implementing `Agent` and registering via `ctx.agents.register()`.
- Event listeners: all `agent/*` events are declared here — no dependency on the loop package needed.
### What is NOT here (TODO)