feat(samples): add a complete TypeScript Agent SDK Web UI showcase

[Ldabai]

Summary

Add a comprehensive local Web application template built with the Qoder TypeScript Agent SDK, Fastify, React, and TypeScript.

Unlike the repository's focused cross-language samples, this TypeScript-only template demonstrates how SDK capabilities can be assembled into a maintainable end-to-end product with explicit server, application, transport, and browser boundaries.

What’s Included

Query and Session lifecycle

• Long-lived Query instances backed by AsyncIterable<SDKUserMessage>
• Streaming Assistant and Tool output projected into stable semantic conversation items
• Session creation, resume, fork, rename, tagging, deletion, and history recovery
• Workspace-bound Sessions with native directory selection
• Message queuing, interruption, cancellation, and SDK Session state handling
• Graceful close coordination for live Queries and application shutdown

Product interactions

• Inline Tool Approval with allow and deny flows
• Structured AskUserQuestion interactions
• MCP form and URL elicitation
• Model, Permission Mode, Context, and additional-directory controls
• Prompt Suggestions, Commands, Skills, Agents, Plugins, Account, and Usage discovery
• Subagent transcript lookup and isolated detail views
• Task message projection and server/API control adapters

MCP, Hooks, and diagnostics

• Read-only in-process showcase_project MCP Server
• Optional server-side remote MCP configuration
• MCP connection, OAuth, callback, and reconnect flows
• Hook callback observations and SDK Hook lifecycle events
• Default-closed SDK Console for MCP, Hooks, Raw Events, extensions, and account information
• Bounded browser projections with schema validation and credential-key redaction

Checkpoints

• File, conversation, and combined rewind scopes
• Dry-run impact previews before execution
• Revision-bound, expiring, single-use previews
• Idle-state and capability gates
• Mutation fencing against concurrent Session changes
• Authoritative conversation replacement from persisted SDK history

Realtime and recovery

• Zod-validated REST commands, WebSocket frames, snapshots, and events
• Ordered event journal with epoch and cursor recovery
• Snapshot fallback for gaps, stale epochs, and invalid frames
• Consistent live and restored conversation semantics
• Command ownership so failures are shown by the control or turn that initiated them

Documentation

• English package README and runtime-selection guide
• Copyable SDK Quick Start for one-shot and long-lived Queries
• End-to-end SDK Code Tour and capability map
• Product Trial Guide with 17 acceptance cases
• SDK adapter maintenance guide
• Exact Chinese UI labels retained where needed to match the current product interface

Architecture

The browser does not import or receive SDK objects directly.

• src/server/sdk/ is the only directory allowed to import @qoder-ai/qoder-agent-sdk
• Server services depend on narrow application-owned ports
• src/shared/ defines validated commands, events, snapshots, and browser-safe view models
• React consumes normalized application state rather than raw SDK messages
• SDK import direction is enforced by npm run check:boundary

Verification

The following account-independent verification passed:

• TypeScript checks
• SDK import-boundary check
• 333 unit tests
• 63 integration tests
• Production build
• Production HTTP/WebSocket smoke test
• 6 Playwright browser journeys

Run the complete gate with:

npm run check

The real-account smoke test remains explicitly opt-in:

npm run test:smoke:real

It was not part of the default verification and may create a temporary real SDK Session and model turn.

Scope and Limitations

• This is a TypeScript-only comprehensive application template, not a focused cross-language sample.
• The product UI is currently Chinese, while developer and trial documentation is English.
• It is designed as a single-user loopback application.
• It does not provide application authentication, authorization, tenant isolation, or hosted-service hardening and must not be exposed directly through a reverse proxy.
• Deterministic tests use injected Query, catalog, picker, and repository fixtures; they do not prove real account, model, CLI, or remote MCP availability.
• Task state and backgroundTasks() / stopTask() adapters are included, but the current React product does not expose a reachable Task list or Task control entry point.