0 Fork 0

Files

T

Tianyi Cui 7f024a1a9d 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.

2026-06-11 13:01:00 +08:00

src

Document the codebase thoroughly and tighten type safety

2026-06-11 13:01:00 +08:00

cordis.yml

Add runnable echo-agent example

2026-06-11 10:55:05 +08:00

package.json

Add runnable echo-agent example

2026-06-11 10:55:05 +08:00

README.md

Document the codebase thoroughly and tighten type safety

2026-06-11 13:01:00 +08:00

start.ts

Add runnable echo-agent example

2026-06-11 10:55:05 +08:00

README.md

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 "
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/steers 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

yarn demo
# or:
node --expose-internals --import tsx examples/echo-agent/start.ts

Type a message and press Enter. "echo " 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