Document the codebase thoroughly and tighten type safety

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.

examples/echo-agent/README.md

@@ -0,0 +1,40 @@
+# 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`

examples/echo-agent/src/echo-tool.ts

@@ -1,19 +1,19 @@
 import type { Context } from 'cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
 
 export const name = 'echo-tool'
 export const inject = ['tools']
 
 export function apply(ctx: Context) {
-  ctx.tools.register({
+  ctx.tools.register(defineTool({
     name: 'echo',
     description: 'Echo the given text back, uppercased.',
     parameters: {
-      type: 'object',
-      properties: { text: { type: 'string' } },
-      required: ['text'],
+      text: { type: 'string', required: true },
     },
-    async execute(args: any) {
-      return [{ type: 'text', text: `ECHO: ${String(args?.text ?? '').toUpperCase()}` }]
+    async execute(args) {
+      // args is typed: { text: string }
+      return [{ type: 'text', text: `ECHO: ${args.text.toUpperCase()}` }]
     },
-  })
+  }))
 }

examples/echo-agent/src/stdio-chat.ts

@@ -25,11 +25,11 @@ export function apply(ctx: Context) {
 
   ctx.on('session/event', (_session, event) => {
     if (event.type === 'tool/call') {
-      const { name: toolName, arguments: args } = event.data as any
+      const { name: toolName, arguments: args } = event.data
       process.stdout.write(`\n  [tool call] ${toolName}(${args})`)
     } else if (event.type === 'tool/result') {
-      const { content } = event.data as any
-      const text = content.filter((b: any) => b.type === 'text').map((b: any) => b.text).join('')
+      const { content } = event.data
+      const text = content.filter(b => b.type === 'text').map(b => b.text).join('')
       process.stdout.write(`\n  [tool result] ${text}\n  `)
     }
   })