@modelprofile.com/flexharness 6.1.0 → 7.0.1

package/ts/readme.md

@@ -1,98 +1,154 @@
-FlexHarness is a modular toolbox for model inference, standalone agents, managed sessions, tools and provider capabilities. It brings SmartAI and SmartAgent into one repository while publishing independently installable packages through tspublish.
+FlexHarness is a modular toolbox for model inference, agents, managed sessions, chat, OCR, KVM control and provider capabilities. It brings SmartAI, SmartAgent, SmartChat, SmartKVM and SmartOCR's AI helpers into one repository through four focused packages published with tspublish.
 
 ## Issue Reporting and Security
 
 For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
-## Choose components
+## Install and choose an entrypoint
 
-All package names below use the `@modelprofile.com/` scope. Components share a release version; each published package declares only its own dependencies. The private repository root is a development dependency catalog, not an install-everything package.
+The toolbox publishes **four packages** under `@modelprofile.com`, with one shared
+release version. Integrations use subpath imports instead of additional package
+names.
 
-| Package | Responsibility |
+| Package | Use it for |
 | --- | --- |
-| `flexharness-models` | Model contracts, explicit `ModelRegistry`, AI SDK helpers and prompt caching |
-| `flexharness-provider-{anthropic,openai,google,groq,mistral,xai,perplexity,ollama}` | One explicitly selected model provider per package |
-| `flexharness-agent` | `runAgent`, `AgentSession`, canonical events, generation transactions and tool contracts |
-| `flexharness` | Managed scopes, sessions, permissions, public projections and persistence coordination |
-| `flexharness-tools` | Tool factories using a host-supplied execution context, HTTP and JSON tools |
-| `flexharness-tools-node` | Local filesystem/process contexts, `filesystemTool`, `shellTool` and file-backed job stores |
-| `flexharness-compaction` | Model-driven conversation compaction |
-| `flexharness-mcp` | MCP clients and AI SDK tool conversion |
-| `flexharness-openai-auth` | ChatGPT device/browser authentication, refresh and model connections |
-| `flexharness-openai-account` | Account lifecycle, model catalog, rate limits and credential envelopes |
-| `flexharness-openai-auth-files` | Explicit interoperability with existing external credential files |
-| `flexharness-media` | Vision recipes for an injected model |
-| `flexharness-media-openai` | OpenAI audio and image capabilities |
-| `flexharness-document` | PDF processing; this component alone brings SmartPDF |
-| `flexharness-ocr` | OCR contracts with an injected transport; no runtime dependencies |
-| `flexharness-research` | Anthropic research capabilities |
-
-For model inference without an agent:
+| `flexharness` | Managed sessions, permissions, tools, chat, OCR, documents and KVM |
+| `flexharness-agent` | Standalone `runAgent` and `AgentSession`; portable `/runner` |
+| `flexharness-models` | Model contracts, `ModelRegistry`, AI SDK helpers and caching |
+| `flexharness-providers` | All eight model providers, authentication, accounts, media and research |
+
+For a managed agent with model providers:
+
+```sh
+pnpm add @modelprofile.com/flexharness @modelprofile.com/flexharness-providers
+```
+
+For inference without an agent:
 
 ```sh
-pnpm add @modelprofile.com/flexharness-models @modelprofile.com/flexharness-provider-openai
+pnpm add @modelprofile.com/flexharness-models @modelprofile.com/flexharness-providers
 ```
 
 ```typescript
 import { ModelRegistry, generateText } from '@modelprofile.com/flexharness-models';
-import { createOpenAiModelProvider } from '@modelprofile.com/flexharness-provider-openai';
+import { createOpenAiModelProvider } from '@modelprofile.com/flexharness-providers/openai';
 
 const models = new ModelRegistry().register(createOpenAiModelProvider());
 const setup = models.getModelSetup({
-  provider: 'openai',
-  model: 'gpt-5.5',
-  apiKey: process.env.OPENAI_API_KEY,
+  provider: 'openai', model: 'gpt-5.5', apiKey: process.env.OPENAI_API_KEY,
 });
 const result = await generateText({ ...setup, prompt: 'Hello' });
 ```
 
-For a standalone agent, add `@modelprofile.com/flexharness-agent` and pass the same model setup to `runAgent({ ...setup, prompt: 'Hello' })`. Providers are registered on caller-owned registries; duplicate IDs and unknown providers fail explicitly. Importing a provider, agent or harness does not register anything globally.
+For a standalone agent, install `@modelprofile.com/flexharness-agent` and pass the
+same setup to `runAgent({ ...setup, prompt: 'Hello' })`. Node.js 24 or newer is
+required for Node entrypoints. Each application owns its model registry; imports
+do not register providers globally.
+
+## Harness subpaths
+
+All entries below belong to `@modelprofile.com/flexharness`. The root export stays
+focused on managed sessions. Importing it does not load UI, PDF, browser automation
+or provider SDKs.
+
+| Import suffix | Capability | Additional install |
+| --- | --- | --- |
+| `/tools` | Host-supplied execution contexts, HTTP and JSON tools | None |
+| `/tools/node` | Local filesystem and process tools, file-backed job adapters | None |
+| `/compaction` | Model-driven conversation compaction | None |
+| `/media` | Vision recipes using an injected model | None |
+| `/ocr` | `ImageOcr`, OCR contracts and Mistral transport | None |
+| `/chat` | Portable streaming `ChatSession`, history and usage | None |
+| `/chat/cli` | Ink/React terminal chat | `ink ink-text-input react`; TypeScript: `@types/react` |
+| `/chat/web` | Lit `flexchat-window`, `flexchat-message`, `flexchat-input` | `lit` |
+| `/kvm` | Browser control, terminal framing and OCR observation | `puppeteer` |
+| `/documents` | PDF processing and `extractTextFromPdf` | `@push.rocks/smartpdf` |
+| `/mcp` | MCP clients and AI SDK tool conversion | `@modelcontextprotocol/sdk` |
+| `/migration` | Existing versioned harness migrations | None |
+
+The integrations in the last column use optional peer dependencies. Install them
+only for the entrypoints your project imports, for example:
 
-For OpenAI ChatGPT authentication, add `flexharness-openai-auth` and set `connection: createOpenAiChatGptModelConnection(credentials)` in the OpenAI model options. This connection supplies the existing authentication settings and system-instruction middleware. API-key inference does not depend on the authentication or account packages.
-
-## Install the managed harness
-
-```bash
-pnpm add @modelprofile.com/flexharness
+```sh
+pnpm add @modelprofile.com/flexharness lit
 ```
 
-Node.js 24 or newer is required.
-
-## Overview
+```typescript
+import { ChatSession } from '@modelprofile.com/flexharness/chat';
+import '@modelprofile.com/flexharness/chat/web';
+```
 
-FlexHarness owns scope isolation, public session and message projections, permission decisions, event delivery, cancellation, and persistence coordination. Each session is backed by the `flexharness-agent` component's `AgentSession`, which owns the canonical private conversation and runtime event history. Model selection, tool execution, and optional execution-context creation remain application-defined extension points. The managed harness depends on the standalone agent; it does not install provider SDKs, MCP, document processing or local execution tools.
+Chat uses the portable `flexharness-agent/runner`. A browser application can provide
+a model backed by its own server transport, or supply `run` in
+`IChatSessionOptions`. The web element accepts an `IChatSession` and maintains its
+own subscription. Full Node `AgentSession` remains at the agent package root.
 
-## Migrating from SmartAI and SmartAgent
+## Provider subpaths
 
-Update all related imports together and install the components they reference. The old packages are superseded; their published versions remain available so existing installations can be migrated deliberately.
+Install `@modelprofile.com/flexharness-providers` once. Its root exports all provider
+factories; use a provider subpath to import just that implementation.
 
-| Previous import/API | Replacement |
+| Import suffix | Capability |
 | --- | --- |
-| `@push.rocks/smartai` model/cache/AI SDK contracts | `@modelprofile.com/flexharness-models` |
-| Global `getModel` / `getModelSetup` | A `ModelRegistry` with explicit provider registrations |
-| Provider-specific request types | The relevant `flexharness-provider-*` package |
-| `openAiChatGptAuth` model option | `connection: createOpenAiChatGptModelConnection(credentials)` from `flexharness-openai-auth` |
-| SmartAI root authentication functions/types | `flexharness-openai-auth` |
-| `@push.rocks/smartai/providers` | `flexharness-openai-account` |
-| `@push.rocks/smartai/openai-chatgpt-auth` | `flexharness-openai-auth-files` |
-| SmartAI `/vision`, `/audio`, `/image` | `flexharness-media`, `flexharness-media-openai`, `flexharness-media-openai` |
-| SmartAI `/document`, `/ocr`, `/research` | `flexharness-document`, `flexharness-ocr`, `flexharness-research` |
-| `@push.rocks/smartagent` agent/event/persistence/adapter contracts | `flexharness-agent` |
-| SmartAgent `/tools` factories and output formatting | `flexharness-tools` |
-| Local contexts, `filesystemTool`, `shellTool`, `FileToolJobStore` | `flexharness-tools-node` |
-| SmartAgent `/compaction`, `/mcp` | `flexharness-compaction`, `flexharness-mcp` |
-
-Existing `ISmartAi*` and `TSmartAi*` contract names remain where their semantics are unchanged. The models package accepts provider IDs as strings; applications that expose a fixed set of providers should own that narrower union. The OpenAI account registry remains `SmartAiProviderRegistry`; it manages account adapters and is distinct from inference's `ModelRegistry`.
-
-Durable Agent event/job schemas, FlexHarness projection schemas, credential envelopes, and external credential-source names and paths are preserved. The package move does not require a data migration. Existing FlexHarness versioned migration APIs remain at `@modelprofile.com/flexharness/migration`.
-
-## Developing and releasing the toolbox
-
-Each `ts_*` component has a `tspublish.json` declaring its dependencies, owned folders and published exports. Cross-component source imports use package names. TypeScript mappings provide source entrypoints for tsrun and declaration entrypoints for tsbuild's compiled-folder resolution; no workspace links are required.
-
-`pnpm build` builds the components in declared dependency order. `pnpm test` runs the deterministic model, agent and harness regressions. Live provider tests and the browser authentication smoke test are preserved in `test_integration/` and run only when explicitly selected; they are not part of release preflight.
-
-GitZone's `release.targets.npm.packageSource: "tspublish"` prepares and packs every component once, publishes the dependency order to the configured registries, and records the exact artifacts in its release journal. A partial release resumes those stored artifacts. Third-party OpenAI Codex notices accompany the authentication and account packages.
+| `/anthropic`, `/openai`, `/google`, `/groq`, `/mistral`, `/xai`, `/perplexity`, `/ollama` | Model adapters and their request types |
+| `/auth` | ChatGPT browser/device authentication, refresh and model connections |
+| `/accounts` | Account lifecycle, model catalogs, rate limits and credential envelopes |
+| `/auth/files` | Explicit interoperability with external credential files |
+| `/media` | OpenAI audio and image generation |
+| `/research` | Anthropic research utilities |
+
+Provider SDKs are installed together. Authentication, file access and vendor media
+are separate entrypoints and are not imported by the provider factory root. For
+ChatGPT authentication, pass
+`connection: createOpenAiChatGptModelConnection(credentials)` from `/auth` to the
+OpenAI model options. API-key inference needs no authentication setup.
+
+## Migration
+
+Replace the withdrawn 6.x component imports with the subpaths above. Provider
+imports change from individual provider packages to
+`@modelprofile.com/flexharness-providers/<provider>`. Keep direct agent and models
+imports and upgrade them to the same release version. The removed package names
+are not republished.
+
+| Previous API | Replacement |
+| --- | --- |
+| SmartAI models, caching and AI SDK contracts | `flexharness-models` and explicit `ModelRegistry` registrations |
+| SmartAI provider factories | `flexharness-providers/<provider>` |
+| SmartAI authentication, account adapters and external credential files | `flexharness-providers/auth`, `/accounts`, `/auth/files` |
+| SmartAI vision, document and OCR helpers | `flexharness/media`, `/documents`, `/ocr` |
+| SmartAI audio, image and research helpers | `flexharness-providers/media`, `/research` |
+| SmartAgent runtime, events and persistence contracts | `flexharness-agent` |
+| SmartAgent tools, local tools, compaction and MCP | `flexharness/tools`, `/tools/node`, `/compaction`, `/mcp` |
+| SmartChat sessions, CLI and web components | `flexharness/chat`, `/chat/cli`, `/chat/web` |
+| SmartKVM | `flexharness/kvm`: `BrowserKvm`, `KvmTerminal`, `createKvmTools` |
+| SmartOCR image AI helper | `ImageOcr.recognizeImageBytes` from `flexharness/ocr` |
+| SmartOCR PDF AI helper | `extractTextFromPdf` from `flexharness/documents` |
+
+For image OCR, rename `smartAiOcrEngine` to `engine` and `mistralOcrOptions` to
+`mistralOptions`; pass the API key explicitly. Native searchable-PDF processing
+through `SmartOcr.processPdfBuffer` remains in SmartOCR.
+
+Existing `ISmartAi*` and `TSmartAi*` contracts, durable event/job schemas, harness
+projections, credential envelopes and external credential paths remain unchanged.
+The OpenAI account `SmartAiProviderRegistry` is separate from inference's
+`ModelRegistry`. The package consolidation requires no data migration.
+
+## Developing and releasing
+
+Four named `tspublish.json` descriptors own the published packages. Other folder
+descriptors specify compilation order only. Each package explicitly declares its
+owned folders, exports and required or optional peer dependencies. Source and
+compiled declaration mappings support development without workspace links.
+
+Run `pnpm build`, `pnpm test` and `pnpm run check:test`. Tests install packed
+artifacts in disposable directories to check minimal dependency graphs, every
+public subpath and browser imports. Live provider and browser authentication tests
+remain opt-in in `test_integration/`.
+
+The configured GitZone release prepares four packages, records their exact
+artifacts, and publishes models before its dependents to npmjs and Verdaccio.
+Third-party OpenAI Codex notices accompany the providers package.
 
 ## Core Setup
 

package/ts_chat/classes.chatsession.ts

@@ -0,0 +1,116 @@
+import { runAgent } from './plugins.js';
+import type { ModelMessage, IAgentRunResult } from './plugins.js';
+import type { IChatSessionOptions, IChatCallbacks, IChatUsage } from './interfaces.js';
+
+/**
+ * ChatSession manages in-memory conversation state and wraps `runAgent()`.
+ * Conversation state stays in memory; consumers own persistence.
+ */
+export class ChatSession {
+  private messages: ModelMessage[] = [];
+  private usage: IChatUsage = {
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+    turns: 0,
+  };
+  private busy = false;
+  private readonly subscribers = new Set<IChatCallbacks>();
+
+  constructor(
+    private options: IChatSessionOptions,
+    private callbacks: IChatCallbacks = {},
+  ) {}
+
+  /**
+   * Send a user message, run the agent, and return the result.
+   * Updates internal message history automatically.
+   */
+  async send(userMessage: string): Promise<IAgentRunResult> {
+    if (this.busy) {
+      throw new Error('ChatSession is busy — wait for the current turn to complete.');
+    }
+
+    this.busy = true;
+
+    try {
+      const result = await (this.options.run ?? runAgent)({
+        model: this.options.model,
+        system: this.options.system,
+        prompt: userMessage,
+        tools: this.options.tools,
+        maxSteps: this.options.maxSteps ?? 20,
+        messages: this.messages,
+        onToken: (delta) => this.notify((callbacks) => callbacks.onToken?.(delta)),
+        onToolCall: (name, input) => this.notify((callbacks) => callbacks.onToolCall?.(name, input)),
+        onToolResult: (name, result) => this.notify((callbacks) => callbacks.onToolResult?.(name, result)),
+      });
+
+      // Update conversation history
+      this.messages = result.messages;
+
+      // Accumulate usage
+      this.usage.inputTokens += result.usage.inputTokens;
+      this.usage.outputTokens += result.usage.outputTokens;
+      this.usage.totalTokens += result.usage.totalTokens;
+      this.usage.turns++;
+
+      this.notify((callbacks) => callbacks.onTurnComplete?.(result));
+
+      return result;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.notify((callbacks) => callbacks.onError?.(err));
+      throw err;
+    } finally {
+      this.busy = false;
+    }
+  }
+
+  /** Whether a turn is currently in progress */
+  isBusy(): boolean {
+    return this.busy;
+  }
+
+  /** Get current conversation history */
+  getMessages(): ModelMessage[] {
+    return [...this.messages];
+  }
+
+  /** Replace messages (e.g. for restoring a saved session) */
+  setMessages(messages: ModelMessage[]): void {
+    this.messages = [...messages];
+  }
+
+  /** Clear conversation history and reset usage */
+  clear(): void {
+    this.messages = [];
+    this.usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0, turns: 0 };
+  }
+
+  /** Get accumulated token usage across all turns */
+  getUsage(): IChatUsage {
+    return { ...this.usage };
+  }
+
+  /** Update session options (model, system prompt, tools, etc.) */
+  updateOptions(options: Partial<IChatSessionOptions>): void {
+    Object.assign(this.options, options);
+  }
+
+  /** Update callbacks */
+  updateCallbacks(callbacks: Partial<IChatCallbacks>): void {
+    Object.assign(this.callbacks, callbacks);
+  }
+
+  /** Attach an independent UI observer without replacing the caller's callbacks. */
+  subscribe(callbacks: IChatCallbacks): () => void {
+    this.subscribers.add(callbacks);
+    return () => { this.subscribers.delete(callbacks); };
+  }
+
+  private notify(invoke: (callbacks: IChatCallbacks) => void): void {
+    invoke(this.callbacks);
+    for (const callbacks of [...this.subscribers]) invoke(callbacks);
+  }
+}

package/ts_chat/index.ts

@@ -0,0 +1,8 @@
+export { ChatSession } from './classes.chatsession.js';
+export type {
+  IChatSession,
+  IChatSessionOptions,
+  IChatCallbacks,
+  TChatEvent,
+  IChatUsage,
+} from './interfaces.js';

package/ts_chat/interfaces.ts

@@ -0,0 +1,64 @@
+import type { TSmartAiLanguageModel, ModelMessage, ToolSet, IAgentRunResult, IAgentRunOptions } from './plugins.js';
+
+/**
+ * Options for creating a ChatSession.
+ */
+export interface IChatSessionOptions {
+  /** The language model to use */
+  model: TSmartAiLanguageModel;
+  /** System prompt for the agent */
+  system?: string;
+  /** Tools available to the agent */
+  tools?: ToolSet;
+  /** Maximum agentic steps per turn */
+  maxSteps?: number;
+  /** Optional caller-owned runner, for example a server transport. */
+  run?: (options: IAgentRunOptions) => Promise<IAgentRunResult>;
+}
+
+/** Structural session contract shared by local sessions and remote frontends. */
+export interface IChatSession {
+  send(userMessage: string): Promise<IAgentRunResult>;
+  isBusy(): boolean;
+  getMessages(): ModelMessage[];
+  getUsage(): IChatUsage;
+  updateCallbacks(callbacks: Partial<IChatCallbacks>): void;
+  subscribe(callbacks: IChatCallbacks): () => void;
+}
+
+/**
+ * Callbacks for real-time streaming events during a turn.
+ */
+export interface IChatCallbacks {
+  /** Called for each streamed text token */
+  onToken?: (delta: string) => void;
+  /** Called when a tool call starts */
+  onToolCall?: (name: string, input: unknown) => void;
+  /** Called when a tool call completes */
+  onToolResult?: (name: string, result: unknown) => void;
+  /** Called when a turn completes */
+  onTurnComplete?: (result: IAgentRunResult) => void;
+  /** Called on error */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Events emitted during chat.
+ */
+export type TChatEvent =
+  | { type: 'token'; delta: string }
+  | { type: 'tool_call_start'; name: string; input: unknown }
+  | { type: 'tool_call_end'; name: string; result: string }
+  | { type: 'turn_start' }
+  | { type: 'turn_complete'; result: IAgentRunResult }
+  | { type: 'error'; error: Error };
+
+/**
+ * Usage stats accumulated across all turns.
+ */
+export interface IChatUsage {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  turns: number;
+}

package/ts_chat/plugins.ts

@@ -0,0 +1,7 @@
+// @modelprofile.com/flexharness-agent
+import { runAgent } from '@modelprofile.com/flexharness-agent/runner';
+export { runAgent };
+export type { IAgentRunOptions, IAgentRunResult } from '@modelprofile.com/flexharness-agent/runner';
+
+// @modelprofile.com/flexharness-models (types re-exported from ai SDK)
+export type { TSmartAiLanguageModel, ModelMessage, ToolSet } from '@modelprofile.com/flexharness-models';

package/ts_chat/readme.md

@@ -0,0 +1,49 @@
+In-memory chat sessions with streamed text, tool callbacks, conversation history and token usage. Works in Node and modern secure browser contexts.
+
+```sh
+pnpm add @modelprofile.com/flexharness
+```
+
+```typescript
+import { ChatSession } from '@modelprofile.com/flexharness/chat';
+
+const chat = new ChatSession({ model, system: 'Answer concisely.' }, {
+  onToken: (text) => console.log(text),
+  onToolResult: (name, output) => console.log(name, output),
+});
+await chat.send('Hello');
+console.log(chat.getMessages(), chat.getUsage());
+```
+
+Supply a model from your selected FlexHarness provider or a model backed by your server transport. Provider SDKs, terminal UI and web UI are separate installs. Private provider credentials belong on the server.
+
+`ChatSession` accepts `model`, `system`, `tools`, `maxSteps` and optional `run`. Its default runner is `flexharness-agent/runner`, which owns cleanup internally and preserves the agent's retry and tool ledger behavior. Pass a caller-owned `run` function to use another execution transport.
+
+Use `setMessages` to restore history, `clear` to reset history and usage, and `updateOptions` to change future turns. Concurrent `send` calls reject while a turn is active. Persistence is caller-owned. `updateCallbacks` updates the primary callbacks; `subscribe` adds an independent observer and returns its unsubscribe function. UI adapters use the structural `IChatSession` interface.
+
+This replaces `@push.rocks/smartchat`. Select `flexharness/chat/cli` for the terminal or `flexharness/chat/web` for Lit elements.
+
+## Issue Reporting and Security
+
+Report issues and security concerns through [community.foss.global](https://community.foss.global).
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts_chat_cli/components.chatapp.ts

@@ -0,0 +1,103 @@
+import { React, h, Box, Text, useInput, useApp, ChatSession } from './plugins.js';
+import type { TSmartAiLanguageModel, ToolSet, IChatUsage } from './plugins.js';
+import { MessageList } from './components.messagelist.js';
+import { InputArea } from './components.inputarea.js';
+import { StatusBar } from './components.statusbar.js';
+import type { IChatMessage } from './components.message.js';
+
+export interface IChatAppProps {
+  model: TSmartAiLanguageModel;
+  system?: string;
+  tools?: ToolSet;
+  maxSteps?: number;
+  modelName?: string;
+}
+
+const emptyUsage: IChatUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0, turns: 0 };
+
+export function ChatApp({ model, system, tools, maxSteps, modelName }: IChatAppProps): React.ReactElement {
+  const { exit } = useApp();
+  const [messages, setMessages] = React.useState<IChatMessage[]>([]);
+  const [streamingText, setStreamingText] = React.useState('');
+  const [busy, setBusy] = React.useState(false);
+  const [usage, setUsage] = React.useState<IChatUsage>({ ...emptyUsage });
+
+  const sessionRef = React.useRef<ChatSession | null>(null);
+
+  if (!sessionRef.current) {
+    sessionRef.current = new ChatSession(
+      { model, system, tools, maxSteps: maxSteps ?? 20 },
+      {
+        onToken: (delta) => {
+          setStreamingText((prev) => prev + delta);
+        },
+        onToolCall: (name, input) => {
+          setMessages((prev) => [
+            ...prev,
+            {
+              role: 'tool' as const,
+              content: '',
+              toolName: name,
+              toolInput: typeof input === 'string' ? input : JSON.stringify(input),
+            },
+          ]);
+        },
+      },
+    );
+  }
+
+  useInput((input, key) => {
+    if (input === 'c' && key.ctrl) {
+      exit();
+    }
+    if (input === 'l' && key.ctrl) {
+      setMessages([]);
+      setStreamingText('');
+      sessionRef.current?.clear();
+      setUsage({ ...emptyUsage });
+    }
+  });
+
+  const handleSubmit = async (text: string) => {
+    if (busy) return;
+
+    if (text === '/clear') {
+      setMessages([]);
+      setStreamingText('');
+      sessionRef.current?.clear();
+      setUsage({ ...emptyUsage });
+      return;
+    }
+
+    if (text === '/quit' || text === '/exit') {
+      exit();
+      return;
+    }
+
+    setMessages((prev) => [...prev, { role: 'user', content: text }]);
+    setBusy(true);
+    setStreamingText('');
+
+    try {
+      const result = await sessionRef.current!.send(text);
+      setStreamingText('');
+      setMessages((prev) => [...prev, { role: 'assistant', content: result.text }]);
+      setUsage(sessionRef.current!.getUsage());
+    } catch (error) {
+      const errMsg = error instanceof Error ? error.message : String(error);
+      setMessages((prev) => [...prev, { role: 'assistant', content: `Error: ${errMsg}` }]);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return h(Box, { flexDirection: 'column' as const },
+    h(Box, { paddingX: 1 },
+      h(Text, { bold: true, color: 'cyan' }, 'FlexChat'),
+      modelName ? h(Text, { dimColor: true }, ` \u2014 ${modelName}`) : null,
+    ),
+    h(MessageList, { messages, streamingText, busy }),
+    h(InputArea, { disabled: busy, onSubmit: handleSubmit }),
+    h(StatusBar, { modelName, usage, busy }),
+  );
+}

package/ts_chat_cli/components.inputarea.ts

@@ -0,0 +1,29 @@
+import { React, h, Box, Text, TextInput } from './plugins.js';
+
+interface IInputAreaProps {
+  disabled: boolean;
+  onSubmit: (text: string) => void;
+}
+
+export function InputArea({ disabled, onSubmit }: IInputAreaProps): React.ReactElement {
+  const [value, setValue] = React.useState('');
+
+  const handleSubmit = (text: string) => {
+    if (!text.trim()) return;
+    onSubmit(text.trim());
+    setValue('');
+  };
+
+  return h(
+    Box,
+    { borderStyle: 'single' as const, borderTop: true, borderBottom: false, borderLeft: false, borderRight: false, paddingX: 1 },
+    h(Text, { bold: true, color: disabled ? 'gray' : 'cyan' }, '> '),
+    h(TextInput, {
+      value,
+      onChange: setValue,
+      onSubmit: handleSubmit,
+      placeholder: disabled ? 'Waiting for response...' : 'Type a message...',
+      focus: !disabled,
+    }),
+  );
+}

package/ts_chat_cli/components.message.ts

@@ -0,0 +1,48 @@
+import { React, h, Box, Text } from './plugins.js';
+
+export interface IChatMessage {
+  role: 'user' | 'assistant' | 'tool';
+  content: string;
+  toolName?: string;
+  toolInput?: string;
+}
+
+interface IMessageProps {
+  message: IChatMessage;
+}
+
+function truncate(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text;
+  return text.substring(0, maxLen) + '...';
+}
+
+export function Message({ message }: IMessageProps): React.ReactElement | null {
+  switch (message.role) {
+    case 'user':
+      return h(Box, { marginY: 0 },
+        h(Text, { bold: true, color: 'blue' }, 'You: '),
+        h(Text, null, message.content),
+      );
+
+    case 'assistant':
+      return h(Box, { marginY: 0 },
+        h(Text, { bold: true, color: 'green' }, 'Assistant: '),
+        h(Text, null, message.content),
+      );
+
+    case 'tool':
+      return h(Box, { marginY: 0, marginLeft: 2, flexDirection: 'column' as const },
+        h(Text, { dimColor: true },
+          `tool: ${message.toolName}${message.toolInput ? ` (${message.toolInput})` : ''}`,
+        ),
+        message.content
+          ? h(Box, { marginLeft: 2 },
+              h(Text, { dimColor: true }, truncate(message.content, 200)),
+            )
+          : null,
+      );
+
+    default:
+      return null;
+  }
+}