zoe-agent 0.3.1

package/README.md

@@ -0,0 +1,568 @@
+# Zoe Agent 🦞
+
+[![NPM Version](https://img.shields.io/npm/v/zoe-agent.svg?style=flat-square)](https://www.npmjs.com/package/zoe-agent)
+[![NPM Downloads](https://img.shields.io/npm/dm/zoe-agent.svg?style=flat-square)](https://www.npmjs.com/package/zoe-agent)
+[![GitHub Release](https://img.shields.io/github/v/tag/hashangit/zoe?style=flat-square&label=release)](https://github.com/hashangit/zoe/releases)
+[![License: BSL 1.1](https://img.shields.io/badge/License-BSL%201.1-blue.svg?style=flat-square)](https://github.com/hashangit/zoe/blob/main/LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
+
+**The Engineering-First Headless Agent Framework: CLI, SDK, and Server. Stable, Scalable Automation for the Post-Vision Era.**
+
+---
+
+🔗 **GitHub Repository**: [https://github.com/hashangit/zoe](https://github.com/hashangit/zoe)
+
+---
+
+Zoe Agent is a high-stability, open-source automation framework specifically engineered for **headless systems**.
+
+Unlike "screen-seeing" agents (such as OpenClaw) that rely on visual interpretation, Zoe Agent is built on a foundation of precise command-driven execution. This makes it significantly more **stable**, **robust from an engineering perspective**, and **easier to scale** across complex environments—whether it's a local server, a CI/CD pipeline, or thousands of containerized nodes.
+
+## Why Zoe Agent?
+- 🐳 **Docker Native**: Built to run safely inside containers. Minimal footprint (Node.js/Alpine friendly).
+- 🚀 **Better Engineering**: Operates via precise system APIs and shell commands rather than unstable visual recognition, ensuring deterministic outcomes.
+- 🛡️ **Superior Stability**: Immune to issues like UI rendering, screen resolution, or network lag that plague vision-based agents.
+- 📈 **Massive Scalability**: Low resource consumption allows orchestrating thousands of instances (e.g., in K8s) for true automation swarms.
+- 🔌 **Swarm Ready**: Stateless design allows for easy orchestration via K8s, Docker Swarm, or simple shell loops.
+- 🧩 **Extensible Integrations**: Built-in support for Web Search (Tavily), Email (SMTP), and Notification Webhooks (Feishu, DingTalk, WeCom).
+- 📦 **SDK & Server**: TypeScript SDK for programmatic use, standalone HTTP/WebSocket server for remote access.
+- 🛠 **Skills System**: Loadable skill packs with file references, custom tool registration, and extensible workflows.
+
+## Features
+
+- 🤖 **Multi-Provider Support**: Switch between OpenAI, Anthropic Claude, GLM, or any OpenAI-compatible endpoint
+- 🔄 **Runtime Provider Switching**: Change AI providers mid-conversation with `/models` command
+- 📜 **Headless Execution**: No browsers, no GUIs. Pure terminal efficiency.
+- 🚀 **Non-Interactive Mode**: Intelligent flag handling (`-y`, `--no-interactive`) for zero-touch automation.
+- 📂 **Universal Control**: From simple file I/O to complex system administration.
+- 🧠 **Context Aware**: Detects container environments and provides accurate system time for relative date queries.
+- 🌐 **Web Search**: Integrated with Tavily for real-time information retrieval.
+- 🕒 **Time Accuracy**: Built-in tool to get precise system date and time for correct temporal context.
+- 📧 **Communication**: Send emails and push notifications to chat groups automatically.
+- 📦 **TypeScript SDK**: Programmatic access via `createAgent`, `streamText`, `generateText`.
+- 🖥 **Server Mode**: Standalone HTTP/WebSocket server with API key auth and session management.
+- 🛠 **Skills System**: Loadable skill packs from directories with `@path` file references and custom tool creation.
+- 🐚 **Shell Approval**: Interactive prompts or non-interactive modes via `ZOE_SHELL_APPROVE` env var.
+- 🖥️ **Interactive TUI**: In a TTY, a full-screen Ink/React UI — bordered always-on input, streaming feed, session manager, message queue/`/steer`, and inline `write_file` diffs (atomic, crash-safe writes).
+
+## Tech Stack
+- **Runtime**: Node.js
+- **Language**: TypeScript
+- **Architecture**: Modular multi-adapter (core, CLI, SDK, server)
+- **Framework**: Commander.js
+- **UI**: Inquirer (interactivity), Chalk (styling), Ora (spinners)
+- **AI**: Multi-Provider (OpenAI, Anthropic Claude, GLM, OpenAI-Compatible)
+
+## Installation
+
+### npm
+```bash
+npm install -g zoe-agent
+```
+
+### pnpm
+```bash
+pnpm add -g zoe-agent
+```
+
+### Homebrew (macOS & Linux)
+```bash
+brew tap hashangit/zoe
+brew install zoe-agent
+```
+
+> **Note:** Requires [Node.js](https://nodejs.org/) 20 or later.
+
+### Server Binary
+The `zoe-server` binary is included for running the standalone HTTP/WebSocket server:
+```bash
+zoe-server --port 7337 --generate-api-key
+```
+
+### SDK Usage
+Import the SDK in your TypeScript/JavaScript project:
+```bash
+npm install zoe-agent
+```
+```ts
+// Main exports
+import { createAgent, streamText, generateText } from 'zoe-agent';
+// Server utilities
+import { createServer } from 'zoe-agent/server';
+```
+
+### Development Installation
+1.  Clone the repository:
+    ```bash
+    git clone https://github.com/hashangit/zoe.git
+    cd zoe
+    ```
+2.  Install dependencies:
+    ```bash
+    pnpm install
+    ```
+3.  Build the project:
+    ```bash
+    pnpm run build
+    ```
+4.  Link globally (optional):
+    ```bash
+    pnpm link
+    ```
+
+## Quick Start
+
+1.  **Setup**: Run the interactive setup wizard to configure your API keys and integrations.
+    ```bash
+    zoe setup
+    ```
+    The wizard now supports configuring multiple providers (OpenAI, Anthropic, GLM) in a single session.
+
+2.  **Run**: Start the agent in interactive mode.
+    ```bash
+    zoe
+    ```
+
+## Usage
+
+### Interactive Mode
+Simply run `zoe` to enter the chat loop.
+```bash
+zoe
+> List all TypeScript files in the src folder.
+```
+
+### Interactive TUI
+
+In a terminal (TTY), `zoe` launches a full-screen Ink/React TUI instead of the readline loop: a bordered always-visible input, a streaming message feed, a persistent task panel (`manage_todos`), session list/resume/export, and inline diffs for `write_file`. File writes are atomic (same-dir temp + `fs.rename`, so a crash never corrupts the file) and render as a green/red unified diff in the tool block; Ctrl+O expands collapsed blocks, and `/clear` starts a fresh session. It falls back to the readline REPL when piped or run with `--no-interactive`.
+
+### Headless Mode (One-Shot)
+Run a single command and exit.
+```bash
+zoe "Check disk usage and save the report to usage.txt" --no-interactive
+```
+
+### Auto-Confirm (CI/CD)
+Automatically approve all tool executions (dangerous, use with caution or in sandboxes).
+```bash
+zoe "Refactor src/index.ts to use ES modules" -y
+```
+
+### Provider Selection
+Use a specific provider for a single command:
+```bash
+zoe -p anthropic "Analyze this code for security issues"
+```
+
+### Switch Providers Mid-Conversation
+In interactive mode, type `/models` to switch between configured providers:
+```bash
+zoe
+> /models  # Select Anthropic from the list
+> Now analyze this with Claude...
+```
+
+### CLI Options
+- `-m, --model <model>`: Specify the LLM model (default: `gpt-4o`).
+- `-p, --provider <provider>`: Specify the LLM provider (`openai-compatible`, `openai`, `anthropic`, `glm`).
+- `-n, --no-interactive`: Exit after processing the initial query (Headless mode).
+- `-y, --yes`: Auto-confirm all tool executions (e.g., shell commands).
+- `--docker`: Run in Docker-optimized non-interactive mode (auto-detected in containers).
+- `--generate-api-key`: Generate an API key for server mode (use with `zoe-server`).
+
+### Interactive Commands
+- `/models`: Switch between configured providers during a conversation.
+- `/exit` or `/quit`: End the session.
+
+## Configuration
+
+Zoe Agent uses a hierarchical configuration system.
+
+**Priority Order (Highest to Lowest):**
+1.  **CLI Arguments**: (e.g., `-m gpt-4o`)
+2.  **Environment Variables**: (`OPENAI_API_KEY`, `.env` file)
+3.  **Project Config**: (`./.zoe/setting.json` in current directory)
+4.  **Global Config**: (`~/.zoe/setting.json`)
+
+### Supported Configuration Keys (JSON)
+
+**Environment Variables:**
+- `ZOE_SHELL_APPROVE`: Shell command approval mode (`auto`, `deny`, or unset for interactive)
+- `ZOE_SKILLS_PATH`: Colon-separated list of additional skill directories
+- `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GLM_API_KEY`: Provider API keys
+- `OPENAI_COMPAT_API_KEY`, `OPENAI_COMPAT_BASE_URL`, `OPENAI_COMPAT_MODEL`: OpenAI-compatible provider settings
+
+**Multi-Provider Configuration:**
+- `provider`: Active provider type (`openai-compatible`, `openai`, `anthropic`, `glm`)
+- `models`: Object containing per-provider configurations:
+  ```json
+  {
+    "models": {
+      "openai-compatible": { "apiKey": "...", "baseUrl": "...", "model": "gpt-4o" },
+      "openai": { "apiKey": "...", "model": "gpt-4o" },
+      "anthropic": { "apiKey": "...", "model": "claude-sonnet-4-5-20250929" },
+      "glm": { "apiKey": "...", "model": "sonnet" }
+    }
+  }
+  ```
+
+**Legacy Keys (Backward Compatible):**
+- `apiKey`: Your OpenAI API Key (legacy, treated as `openai-compatible`).
+- `baseUrl`: Custom Base URL (e.g., for DeepSeek or LocalLLM).
+- `model`: Default model to use.
+- `tavilyApiKey`: API Key for Tavily Web Search.
+- `smtpHost`, `smtpPort`, `smtpUser`, `smtpPass`, `smtpFrom`: SMTP Email settings.
+- `feishuWebhook`, `dingtalkWebhook`, `wecomWebhook`: Notification webhooks.
+
+### Project-Level Config Example
+
+**Multi-Provider Configuration:**
+```json
+{
+  "provider": "anthropic",
+  "models": {
+    "openai": { "apiKey": "sk-...", "model": "gpt-4o" },
+    "anthropic": { "apiKey": "sk-ant-...", "model": "claude-sonnet-4-5-20250929" }
+  }
+}
+```
+
+**Legacy Configuration (Still Supported):**
+Create a file at `.zoe/setting.json`:
+```json
+{
+  "model": "gpt-3.5-turbo",
+  "baseUrl": "https://api.deepseek.com/v1"
+}
+```
+
+> **⚠️ Security Warning**: If you store your `apiKey` or secrets in `.zoe/setting.json`, make sure to add `.zoe/` to your `.gitignore` file to prevent leaking secrets!
+
+## Integrations
+
+### Gateway (MCP Client + REST Proxy + OpenAPI Adapter)
+
+Zoe Agent v0.3.0 introduces a universal API gateway that connects to downstream MCP servers and REST APIs:
+
+- **Semantic Injection**: Middleware scores your message against all discovered tools and injects the top-K most relevant directly into the agent's tool context. Zero context pollution.
+- **Proxy Pattern**: Generic tools (`gateway_route`, `gateway_call_tool`, etc.) let the agent navigate targets when semantic injection finds no match.
+- **OpenAPI Import**: Import any OpenAPI spec (JSON/YAML) and auto-register all operations as a REST target.
+- **Credential Trust Guard**: Admin-registered targets can resolve stored credentials; agent-registered targets cannot — preventing credential exfiltration.
+- **Audit Logging**: Ring-buffer audit logs with per-target usage summaries for debugging and self-healing.
+
+**Configuration** (`~/.zoe/setting.json` or env vars):
+```json
+{
+  "gatewayEnabled": true,
+  "gatewaySemanticTopK": 3,
+  "gatewayRateLimit": 60,
+  "gatewayMaxAuditLogs": 1000
+}
+```
+
+**CLI Commands**: `/gateway list|add|remove|toggle|routes|credentials|audit|usage`
+
+**REST API**: `GET/POST/PATCH/DELETE /v1/gateway/*` (admin scope required for mutations)
+
+**SDK**:
+```ts
+import { gateway } from 'zoe-agent';
+const gw = await gateway.createGateway({ enabled: true, semanticTopK: 3, defaultRateLimitPerMin: 60, maxAuditLogsInMemory: 1000 });
+```
+
+### Multi-Provider LLM Support
+Zoe Agent supports multiple AI providers with seamless switching:
+- **OpenAI**: GPT-4, GPT-3.5-turbo, and latest models
+- **Anthropic**: Claude Sonnet, Haiku, Opus models
+- **GLM**: Z.ai GLM-4.5, GLM-4.7, GLM-5.1 models
+- **OpenAI-Compatible**: DeepSeek, LocalLLM, Ollama, LM Studio, and any OpenAI-compatible endpoint
+
+Configure multiple providers during setup and switch between them using `/models` command or `-p` flag.
+
+### Web Search (Tavily)
+Zoe Agent can search the web if you provide a Tavily API Key during setup or in config.
+- **Usage**: "Search for the latest Node.js release notes."
+
+### Email (SMTP)
+Configure SMTP settings to let the agent send emails.
+- **Usage**: "Send an email to user@example.com with the summary of the log file."
+
+### Notifications (Feishu/DingTalk/WeCom)
+Configure webhooks to receive alerts or reports in your team chat apps.
+- **Usage**: "Notify the team on Feishu that the build has finished."
+
+### Date & Time
+Built-in utility to provide the agent with the current system time, ensuring accurate handling of relative time requests.
+- **Usage**: "What's the date today?" or "Remind me to check the logs next Monday."
+
+## SDK & Programmatic Usage
+
+Zoe Agent provides a TypeScript SDK for building agent-powered applications.
+
+### Basic Agent
+```ts
+import { createAgent } from 'zoe-agent';
+
+const agent = await createAgent({
+  provider: 'anthropic',
+  model: 'claude-sonnet-4-5-20250929',
+});
+
+const result = await agent.chat('List all running Docker containers');
+console.log(result.text);
+```
+
+### Streaming
+```ts
+import { streamText } from 'zoe-agent';
+
+const stream = await streamText('Analyze the logs for errors', {
+  provider: 'openai',
+});
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+### Structured Output
+```ts
+import { generateText } from 'zoe-agent';
+
+const result = await generateText('Extract the top 3 issues from these logs', {
+  provider: 'anthropic',
+});
+console.log(result.text);
+```
+
+### Getting Started (SDK)
+
+Before first use, configure providers from your CLI config (or env vars):
+
+```ts
+import { configureProviders, loadProviderConfig } from 'zoe-agent';
+
+const config = loadProviderConfig(); // reads ~/.zoe/setting.json + .zoe/setting.json + env
+if (config) {
+  configureProviders(config);
+}
+
+// Now safe to call
+import { generateText } from 'zoe-agent';
+const result = await generateText('Hello, world!');
+```
+
+Without this step, `generateText` defaults to OpenAI using `OPENAI_API_KEY` if present, or throws a "no provider configured" error otherwise.
+
+### Custom Tools
+```ts
+import { createAgent, tool } from 'zoe-agent';
+
+const agent = await createAgent({
+  provider: 'openai',
+  tools: [
+    tool({
+      name: 'check_disk',
+      description: 'Check disk usage',
+      parameters: {},
+      execute: async () => {
+        const usage = await getDiskUsage();
+        return JSON.stringify(usage);
+      },
+    }),
+  ],
+});
+```
+
+### Session Persistence
+```ts
+const agent = await createAgent({
+  provider: 'anthropic',
+  persist: 'my-session',          // Resume a previous session
+});
+```
+
+## Server Mode
+
+Run Zoe Agent as a standalone HTTP/WebSocket server for remote agent access.
+
+### Starting the Server
+```bash
+# Start with default settings
+zoe-server
+
+# Generate an API key
+zoe-server --generate-api-key
+
+# Custom port
+zoe-server --port 8080
+```
+
+### REST API
+```bash
+# Send a prompt
+curl -X POST http://localhost:7337/api/chat \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"message": "Check disk usage", "provider": "openai"}'
+
+# List sessions
+curl http://localhost:7337/api/sessions \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
+### WebSocket Streaming
+```ts
+const ws = new WebSocket('ws://localhost:7337/ws?token=YOUR_API_KEY');
+
+ws.onopen = () => {
+  ws.send(JSON.stringify({
+    type: 'chat',
+    message: 'Analyze the error logs',
+    provider: 'anthropic',
+  }));
+};
+
+ws.onmessage = (event) => {
+  const chunk = JSON.parse(event.data);
+  process.stdout.write(chunk.text);
+};
+```
+
+## Skills System
+
+Skills are single `SKILL.md` files with YAML frontmatter that extend the agent with domain-specific prompts and tool restrictions. See [docs/sdk/skills.md](docs/sdk/skills.md) for full documentation.
+
+### Skill Format
+```yaml
+---
+name: docker-ops
+description: Docker operations assistant
+tags: [docker, devops]
+allowedTools: [execute_shell_command, read_file]
+args: [environment, service]
+model:
+  provider: anthropic
+  model: claude-sonnet-4-20250514
+---
+
+Skill instructions and templates here.
+Use {{environment}} and {{service}} for argument substitution.
+Reference files with @k8s/deployment.yaml.
+```
+
+### Key Features
+- **Argument substitution**: `{{argName}}`, `$1`/`$2`/`$ALL` for positional args
+- **File references**: `@path/to/file.yaml` injects file contents into the prompt
+- **Tool restrictions**: `allowedTools` limits which tools the skill can use
+- **Model selection**: `model` overrides provider/model per skill
+- **Lazy loading**: skill body is only read when invoked, keeping startup fast
+- **Body limits**: bodies over 8k chars warn, over 32k chars truncate (~8k tokens)
+
+### Discovery Locations
+Skills are discovered in priority order (last wins):
+1. Built-in bundled skills
+2. `~/.zoe/skills/`
+3. `.zoe/skills/` (project-level)
+4. `ZOE_SKILLS_PATH` directories
+
+```bash
+# Add custom skill directories
+export ZOE_SKILLS_PATH=/path/to/skills:/another/path
+```
+
+## Docker Support
+
+Zoe Agent includes a production-ready [`Dockerfile`](./Dockerfile) (Node 20 Alpine) and [`docker-compose.yml`](./docker-compose.yml) for containerized deployment.
+
+### Quick Start with Docker
+
+```bash
+# Clone and build
+git clone https://github.com/hashangit/zoe.git
+cd zoe
+docker build -t zoe-server .
+
+# Run the server
+docker run -d -p 7337:7337 \
+  -e OPENAI_API_KEY=sk-... \
+  zoe-server
+
+# Or use Docker Compose
+docker compose up -d
+```
+
+### Docker-Optimized CLI Mode
+Use `--docker` for non-interactive execution inside containers:
+```bash
+docker run --rm \
+  -e OPENAI_API_KEY=sk-... \
+  -e ZOE_SHELL_APPROVE=auto \
+  zoe-server zoe "Check disk usage" --docker
+```
+
+Zoe Agent auto-detects Docker and non-interactive environments. When running in a container, it adjusts behavior accordingly (no interactive prompts, streamlined output).
+
+### Shell Approval in Containers
+Set `ZOE_SHELL_APPROVE` to control how shell commands are approved without interactive prompts:
+- `auto`: Automatically approve all commands (use in trusted/sandboxed environments)
+- `deny`: Deny all shell command execution
+- _(unset)_: Interactive prompt (default, requires a TTY)
+
+```yaml
+# docker-compose.yml example
+services:
+  zoe:
+    build: .
+    ports:
+      - "7337:7337"
+    environment:
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+      - ZOE_SHELL_APPROVE=auto
+      - ZOE_SKILLS_PATH=/app/skills
+```
+
+### Non-Latin Font Issues in Screenshots
+When running Zoe Agent inside a Docker container (especially Alpine or Debian Slim), screenshots of websites with non-Latin text (e.g., CJK characters) may display text as square boxes ("tofu") due to missing fonts. Emojis (e.g., 🔥) may also appear as squares.
+
+**Solution:** Install CJK (Chinese/Japanese/Korean) and Emoji fonts in your container.
+
+**For Debian/Ubuntu:**
+```bash
+apt-get update && apt-get install -y fonts-noto-cjk fonts-wqy-zenhei fonts-noto-color-emoji
+```
+
+**For Alpine Linux:**
+```apk add font-noto-cjk font-noto-emoji```
+
+## License
+
+Zoe is distributed under the **Business Source License 1.1 (BSL)** — a
+source-available license.
+
+- **Free for personal, non-commercial use** (including students, educators,
+  and research), and for short evaluation/internal trial use.
+- **Commercial / production use** (including offering Zoe as a managed
+  service) requires a commercial license from the Licensor.
+- On the **Change Date (2028-01-01)** the Licensed Work automatically becomes
+  available under the Apache License 2.0.
+
+See the full terms in [LICENSE](./LICENSE). To obtain a commercial license,
+contact the maintainer.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1.  Fork the Project
+2.  Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3.  Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4.  Push to the Branch (`git push origin feature/AmazingFeature`)
+5.  Open a Pull Request
+
+---
+GitHub: [https://github.com/hashangit/zoe](https://github.com/hashangit/zoe)
+
+---
+

package/dist/adapters/cli/agent.d.ts

@@ -0,0 +1,59 @@
+import { LLMProvider } from '../../providers/types.js';
+import type { SkillRegistry } from '../../skills/types.js';
+import type { Message, StepResult, Usage, ApproveToolFn, PermissionLevel, ProviderType, PersistenceBackend } from '../../core/types.js';
+import type { Middleware } from '../../core/middleware.js';
+/**
+ * Outcome of a single `Agent.chat()` turn. Returned so non-readline callers
+ * (the TUI) can render terminal states (aborted / max-steps / error) instead
+ * of relying on chalk stdout. The readline path ignores it and prints the
+ * same chalk messages as before.
+ */
+export interface ChatResult {
+    finishReason: string;
+    error?: string;
+    usage?: Usage;
+}
+export declare class Agent {
+    private provider;
+    private messages;
+    private model;
+    private config;
+    private autoConfirm;
+    private skillRegistry;
+    private skillCatalog;
+    private abortController;
+    private _middleware;
+    private readonly systemPrompt;
+    private readonly providerType;
+    private readonly persistence;
+    private sessionId;
+    constructor(provider: LLMProvider, model?: string, config?: any, systemPrompt?: string, persistence?: PersistenceBackend | null, providerType?: ProviderType);
+    initializeSkills(): Promise<void>;
+    getSkillRegistry(): SkillRegistry | null;
+    /** Set middleware pipeline (e.g., gateway semantic injection). */
+    setMiddleware(middleware: Middleware[]): void;
+    chat(userInput: string, signal?: AbortSignal, approveTool?: ApproveToolFn, permissionLevel?: PermissionLevel, onStep?: (step: StepResult) => void): Promise<ChatResult>;
+    /**
+     * Load a previously persisted session by id, replacing the in-memory history.
+     * Re-seeds the system message if the loaded set has none. No-op when no
+     * backend is configured.
+     */
+    loadSession(sessionId: string): Promise<boolean>;
+    /** Active session id (rotated by `clearConversation` when persistence is on). */
+    getSessionId(): string;
+    /** Configured persistence backend, or null when persistence is disabled. */
+    getPersistence(): PersistenceBackend | null;
+    clearConversation(): void;
+    /** Public accessor for the current message history. */
+    getMessages(): Message[];
+    /** Replace the message history (e.g., after compaction). */
+    setMessages(messages: Message[]): void;
+    /** Public accessor for the active LLM provider. */
+    getProvider(): LLMProvider;
+    /** Public accessor for the active model name. */
+    getModel(): string;
+    switchProvider(provider: LLMProvider, model: string): void;
+    abort(): void;
+    createAbortSignal(): AbortSignal;
+    clearAbortController(): void;
+}