# @push.rocks/smartchat

Interactive chat interfaces for AI agents — CLI TUI and web components, built on [`@push.rocks/smartagent`](https://code.foss.global/push.rocks/smartagent).

## Install

```bash
pnpm install @push.rocks/smartchat
```

## 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.

## Overview

`@push.rocks/smartchat` gives you everything you need to build conversational AI interfaces — in the terminal and on the web. It ships three entry points:

| Entry Point | Import Path | What You Get |
|---|---|---|
| **Core** | `@push.rocks/smartchat` | `ChatSession` — headless conversation state management |
| **CLI** | `@push.rocks/smartchat/cli` | `startChat()` — full-featured terminal TUI (ink-based) |
| **Web** | `@push.rocks/smartchat/web` | `<smartchat-window>` and friends — Lit-based web components |

Under the hood, every turn calls [`@push.rocks/smartagent`](https://code.foss.global/push.rocks/smartagent)'s `runAgent()`, giving you streaming tokens, tool calling, and multi-step agentic loops out of the box.

## Usage

### 🧠 Core — `ChatSession`

`ChatSession` manages in-memory conversation history and wraps the agent loop. It's headless — bring your own UI or use it from scripts, bots, and backend services.

```typescript
import { ChatSession } from '@push.rocks/smartchat';
import type { IChatSessionOptions, IChatCallbacks, IChatUsage } from '@push.rocks/smartchat';

// Create a session with your model and optional tools
const session = new ChatSession(
  {
    model: myLanguageModel,       // LanguageModelV3 from @push.rocks/smartai
    system: 'You are a helpful coding assistant.',
    tools: myToolSet,             // optional ToolSet
    maxSteps: 20,                 // max agentic steps per turn (default: 20)
  },
  {
    onToken: (delta) => process.stdout.write(delta),
    onToolCall: (name, input) => console.log(`🔧 ${name}`),
    onToolResult: (name, result) => console.log(`✅ ${name}`),
    onTurnComplete: (result) => console.log(`Done — ${result.usage.totalTokens} tokens`),
    onError: (err) => console.error(err),
  }
);

// Send a message and get the result
const result = await session.send('Explain the builder pattern in TypeScript');
console.log(result.text);

// Inspect state
console.log(session.getUsage());    // { inputTokens, outputTokens, totalTokens, turns }
console.log(session.getMessages()); // full conversation history
console.log(session.isBusy());      // false (turn complete)

// Manage conversation
session.clear();                    // reset history + usage
session.setMessages(savedHistory);  // restore a saved session
session.updateOptions({ system: 'New system prompt' });
session.updateCallbacks({ onToken: null });
```

#### `IChatSessionOptions`

| Property | Type | Description |
|---|---|---|
| `model` | `LanguageModelV3` | The language model to use (required) |
| `system` | `string` | System prompt for the agent |
| `tools` | `ToolSet` | Tools available to the agent |
| `maxSteps` | `number` | Max agentic steps per turn (default: `20`) |

#### `IChatCallbacks`

| Callback | Signature | When It Fires |
|---|---|---|
| `onToken` | `(delta: string) => void` | Each streamed text token |
| `onToolCall` | `(name: string, input: unknown) => void` | Tool call starts |
| `onToolResult` | `(name: string, result: string) => void` | Tool call completes |
| `onTurnComplete` | `(result: IAgentRunResult) => void` | Turn finishes |
| `onError` | `(error: Error) => void` | Error occurs |

#### `IChatUsage`

| Field | Type |
|---|---|
| `inputTokens` | `number` |
| `outputTokens` | `number` |
| `totalTokens` | `number` |
| `turns` | `number` |

---

### 💻 CLI — Terminal TUI

Launch a beautiful, interactive chat right in your terminal. Built with [ink](https://github.com/vadimdemedes/ink) (React for CLIs).

```typescript
import { startChat } from '@push.rocks/smartchat/cli';
import type { IStartChatOptions } from '@push.rocks/smartchat/cli';

await startChat({
  model: myLanguageModel,
  system: 'You are a friendly assistant.',
  tools: myToolSet,
  maxSteps: 30,
  modelName: 'Claude Opus',   // displayed in the header & status bar
});
```

#### Features

- ⚡ **Real-time streaming** — tokens appear as they're generated
- 🔧 **Tool call visibility** — see tool invocations inline
- 📊 **Status bar** — model name, token usage, turn count
- ⌨️ **Keyboard shortcuts**:
  - `Ctrl+C` — exit
  - `Ctrl+L` — clear conversation
- 💬 **Slash commands**:
  - `/clear` — reset the conversation
  - `/quit` or `/exit` — exit the TUI

#### `IStartChatOptions`

| Property | Type | Description |
|---|---|---|
| `model` | `LanguageModelV3` | The language model (required) |
| `system` | `string` | System prompt |
| `tools` | `ToolSet` | Tools for the agent |
| `maxSteps` | `number` | Max agentic steps per turn |
| `modelName` | `string` | Display name shown in header & status bar |

---

### 🌐 Web — Lit Web Components

Drop a full chat UI into any web app. Three custom elements, fully themeable with CSS custom properties.

```typescript
import '@push.rocks/smartchat/web';
import { ChatSession } from '@push.rocks/smartchat';

// Create a session
const session = new ChatSession({
  model: myLanguageModel,
  system: 'You are a helpful assistant.',
});

// Get the element and wire it up
const chatWindow = document.querySelector('smartchat-window');
chatWindow.chatSession = session;
```

```html
<smartchat-window placeholder="Ask me anything..."></smartchat-window>
```

#### Components

| Element | Description |
|---|---|
| `<smartchat-window>` | Full chat window — message list + input area. Pass a `ChatSession` via the `chatSession` property. |
| `<smartchat-message>` | Single message bubble. Attributes: `role` (`user` / `assistant` / `tool`), `content`, `toolName`. |
| `<smartchat-input>` | Input field + send button. Fires `send` custom event. Attributes: `disabled`, `placeholder`. |

#### 🎨 Theming with CSS Custom Properties

Every visual aspect is customizable:

```css
smartchat-window {
  /* Layout */
  --smartchat-bg: #111827;
  --smartchat-text: #e5e7eb;
  --smartchat-font: system-ui, -apple-system, sans-serif;
  --smartchat-radius: 12px;
  --smartchat-border: #1f2937;
  --smartchat-muted: #6b7280;

  /* User messages */
  --smartchat-user-bubble: #2563eb;
  --smartchat-user-text: #fff;

  /* Assistant messages */
  --smartchat-assistant-bubble: #374151;
  --smartchat-assistant-text: #e5e7eb;

  /* Tool messages */
  --smartchat-tool-bubble: #1e293b;
  --smartchat-tool-text: #94a3b8;
  --smartchat-tool-accent: #6366f1;

  /* Input area */
  --smartchat-input-bg: #1f2937;
  --smartchat-input-border: #374151;
  --smartchat-input-focus: #6366f1;
  --smartchat-input-text: #e5e7eb;
  --smartchat-input-placeholder: #6b7280;

  /* Send button */
  --smartchat-send-bg: #6366f1;
  --smartchat-send-text: #fff;

  /* Streaming cursor */
  --smartchat-cursor: #6366f1;
}
```

---

## Architecture

```
@push.rocks/smartchat
├── ts/              → Core module (ChatSession, interfaces)
├── ts_cli/          → CLI TUI (ink + React)
└── ts_web/          → Web components (Lit)
```

- **Core** (`ts/`) is headless and dependency-light. CLI and Web layers both import from Core.
- **CLI** (`ts_cli/`) uses [ink](https://github.com/vadimdemedes/ink) with `React.createElement` (no JSX).
- **Web** (`ts_web/`) uses [Lit](https://lit.dev/) with `static properties` (no decorators).
- The agentic loop is powered by [`@push.rocks/smartagent`](https://code.foss.global/push.rocks/smartagent), which orchestrates multi-step tool calling with any `LanguageModelV3` from [`@push.rocks/smartai`](https://code.foss.global/push.rocks/smartai).

## 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 [LICENSE](./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
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.