Tianyi Cui
7f024a1a9d
Docs: per-folder README.md for packages/ (family overview + one per package: service, events, API, extension points, TODOs), examples/, and examples/echo-agent/; folder-level AGENTS.md (+ CLAUDE.md symlinks) for packages/ and vendor/; module-level doc comments in every packages/*/src file; richer JSDoc on all exported API (event side effects, disposal contracts, error behavior). Root AGENTS.md gains a "Type Safety and Documentation" policy section: the codebase aims to be very type-safe and well documented; type gymnastics are acceptable in core packages when they improve plugin-author DX; verbose docs are fine as long as they stay strictly in sync with the code. Type safety: removed the upstream-inherited "noImplicitAny": false from tsconfig.base.json — packages/* now compile under full strict mode; vendor/loader and vendor/include set it locally (vendor/cordis already did). Eliminated every `: any` / `as any` from packages and examples (catch clauses use unknown + a CodedError narrowing type; event data access uses discriminated-union narrowing). Typed tool schemas: new @deepseek-ai/dsh-tools schema DSL — SchemaSpec with per-property `required: true` booleans, type-level InferArgs<S>, a runtime SchemaSpec → JSON Schema converter, and defineTool() so first-party tools get typed execute(args) with zero casts (raw JSON Schema still accepted for MCP interop; chosen over schemastery because it targets JSON Schema generation directly). echo-tool and all test tools migrated; +7 tests.
41 lines
1.8 KiB
Markdown
41 lines
1.8 KiB
Markdown
# echo-agent
|
|
|
|
Runnable demo: stdin chat with a scripted mock model and an echo tool.
|
|
|
|
## What it shows
|
|
|
|
- A complete Cordis app loaded from `cordis.yml` — the standard "stack of plugins" pattern
|
|
- `mock-llm.ts` — a mock `LlmAdapter` that streams scripted responses and calls the
|
|
`echo` tool when the user types "echo <something>"
|
|
- `echo-tool.ts` — a tool registered via `ctx.tools.register()` that echoes text
|
|
back uppercased
|
|
- `session-jsonl.ts` — a minimal persistence plugin: write-behind buffering of
|
|
`session/event` notifications, drained to a JSONL file at `session/flush`
|
|
- `stdio-chat.ts` — a minimal UI plugin: reads stdin lines and `send`/`steer`s
|
|
the agent, renders stream deltas, tool calls, and tool results
|
|
|
|
## Plugin files
|
|
|
|
| File | Role | Key patterns demonstrated |
|
|
|---|---|---|
|
|
| `mock-llm.ts` | `LlmAdapter` registration | `ctx.llm.registerAdapter([])`, streaming chunks with proper `block-start`/`block-end` protocol |
|
|
| `echo-tool.ts` | Tool registration | `ctx.tools.register()`, tool execution returning `ContentBlock[]` |
|
|
| `session-jsonl.ts` | Persistence | `session/event` listener + `session/flush` drain, fiber-dispose cleanup |
|
|
| `stdio-chat.ts` | UI | `agent/stream-chunk`, `session/event` (tool/*), stdin→send/steer |
|
|
| `start.ts` | Bootstrap | `Context` + `Loader` + `plugin-include` wired to `cordis.yml` |
|
|
|
|
## Run
|
|
|
|
```sh
|
|
yarn demo
|
|
# or:
|
|
node --expose-internals --import tsx examples/echo-agent/start.ts
|
|
```
|
|
|
|
Type a message and press Enter. "echo <text>" triggers a tool call round-trip
|
|
(the mock model requests the `echo` tool, which echoes the text uppercased,
|
|
and the next model step acknowledges it).
|
|
|
|
The session is persisted to `<session-id>.jsonl` in the `examples/echo-agent/`
|
|
directory. Clean up with: `rm -f examples/echo-agent/*.jsonl`
|