interface-implementation

Files (1)

• SKILL.md

SKILL.md (first lines)

# Interface Implementation Guide

All assistant interfaces **MUST** route user messages through the
`Orchestrator` (`assistant-runtime`). Direct `LlmProvider::chat_streaming()`
calls bypass the system prompt, tools, skills, memory, and ReAct loop —
producing a "dumb chatbot" instead of the full assistant.

## Architecture invariant

```text
User message
  -> Interface (transport layer)
    -> Orchestrator.submit_turn()        <-- REQUIRED
      -> Worker dispatches to one of:
         run_turn()                      (default)
         run_turn_streaming()            (with token sink)
         run_turn_with_tools()           (with extension tools)
      -> System prompt (MemoryLoader)
      -> Tool specs (ToolExecutor + extensions)
      -> Skills XML (SkillRegistry)
      -> ReAct loop (multi-iteration tool calling)
    <- TurnResult { answer, attachments }
  <- Interface renders / delivers response
```

An interface that calls `llm.chat_streaming()` directly violates this
invariant and MUST be fixed.

---

## Checklist for a new interface

### 1. Add an `Interface` variant

In `crates/core/src/types.rs`, add a variant to the `Interface` enum:

```rust
pub enum Interface {
    Cli,
    Signal,
    Mcp,
    Slack,
    Mattermost,
    Web,           // <-- new
    Scheduler,
}
```

### 2. Bootstrap the full dependency chain

Every interface needs these components, in order:

```text
AssistantConfig        (load from ~/.assistant/config.toml)
  -> StorageLayer      (SQLite, migrations)
  -> SkillRegistry     (load embedded + dir-scanned skills)
  -> LlmProvider       (Ollama / Anthropic / OpenAI)
  -> ToolExecutor      (storage, llm, registry, config)
  -> MessageBus        (if config.bus.kind == "nats": NatsMessageBus::connect(&config.bus), else storage.message_bus())
  -> Orchestrator      (llm, storage, executor, registry, bus, config)
  -> executor.set_subagent_runner(orchestrator)   // break init cycle
```

The `assistant_runtime::bootstrap` module provides shared helpers:

- `load_config(path)` — loads config TOML
- `skill_dirs(config, project_root)` — returns skill search directories
- `AutoDenyConfirmation` — for non-interactive interfaces

### 3. Spawn the worker

The orchestrator's bus-based processing requires a background worker:

```rust
let worker_orch = orchestrator.clone();
tokio::spawn(async move {
    worker_orch.run_worker("web-worker").await;
});
```

Without this, `submit_turn()` will publish to the bus but nothing will
claim and process the request.

### 4. Manage conversations

Each logical conversation needs a stable `Uuid`:

| Interface  | Key                             | Strategy                    |
| ---------- | ------------------------------- | --------------------------- |
| CLI        | session                         | `Uuid::new_v4()` at startup |
| Slack      | `(channel_id, thread_ts)`       | HashMap                     |
| Mattermost | `(channel_id, root_post_id)`    | LRU cache (10k)             |
| Signal     | sender phone number             | HashMap                     |
| Web UI     | conversation UUID from database | `ConversationStore` rows    |

The orchestrator creates the conversation record lazily inside
`prepare_history()` via `create_conversation_with_id()` (upsert).

### 5. Choose a delivery mode

| Mode                | Registration call             | Worker method           | Use case                  |
| ------------------- | ----------------------------- | ----------------------- | ------------------------- |
| **Streaming**       | `register_token_sink(id, tx)` | `run_turn_streaming()`  | CLI, Signal, Web UI (SSE) |
| **Extension tools** | `register_extensions(id, ..)` | `run_turn_with_tools()` | Slack, Mattermost         |
| **Fire-and-forget** | (none)                        | `run_turn()`            | Scheduler, MCP            |

For web interfaces, streaming via `register_token_sink` is the natural
fit — pipe tokens to SSE events.

### 6. Submit the turn

```rust
// For streaming:
orchestrator.register_token_sink(conversation_id, token_tx).await;

// For extension tools:
orchestrator.register_extensions(conversation_id, tools, attachments).await;

// Then submit (always):

From cedricziel/assistant, MIT.

More from cedricziel/assistant