create-hq 5.0.0

package/template/knowledge/loom/code-style.md

@@ -0,0 +1,169 @@
+# Code Style & Conventions
+
+## Rust Formatting
+
+```toml
+# rustfmt.toml
+hard_tabs = true
+tab_spaces = 2
+max_width = 100
+```
+
+## Error Handling
+
+```rust
+// Use thiserror for error enums
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum MyError {
+    #[error("failed to do X: {0}")]
+    SomeFailure(String),
+}
+
+// Use anyhow for propagation
+use anyhow::Result;
+
+pub fn do_thing() -> Result<()> {
+    // ...
+}
+```
+
+## Async
+
+- Runtime: Tokio
+- Trait methods: `async-trait`
+
+```rust
+use async_trait::async_trait;
+
+#[async_trait]
+pub trait MyTrait: Send + Sync {
+    async fn do_thing(&self) -> Result<()>;
+}
+```
+
+## HTTP Clients
+
+**Never use `reqwest::Client` directly.** Use `loom-http` wrapper:
+
+```rust
+use loom_http::{new_client, builder};
+
+// Consistent User-Agent and retry logic
+let client = new_client()?;
+```
+
+## Secrets
+
+Use `loom-secret` for API keys, tokens, passwords:
+
+```rust
+use loom_secret::{Secret, SecretString};
+
+let api_key: SecretString = SecretString::new("sk-xxx");
+
+// Access via expose()
+api_key.expose()
+
+// Auto-redacts in Debug/Display/Serialize/tracing
+```
+
+## Imports
+
+Group in order:
+1. `std` crates
+2. External crates
+3. Internal `loom-*` crates
+
+```rust
+use std::collections::HashMap;
+
+use serde::{Deserialize, Serialize};
+use tokio::sync::mpsc;
+
+use loom_common_core::Message;
+use loom_secret::SecretString;
+```
+
+## Naming
+
+| Category | Style |
+|----------|-------|
+| Functions/variables | `snake_case` |
+| Types | `PascalCase` |
+| Constants | `SCREAMING_CASE` |
+
+## Comments
+
+**Minimal comments.** Only add when code is complex and requires context.
+
+**Copyright header required** on all files.
+
+## Logging
+
+Use `tracing` with structured fields:
+
+```rust
+use tracing::{info, instrument};
+
+#[instrument(skip(self, secrets, large_args), fields(id = %id))]
+async fn do_thing(&self, id: Uuid, secrets: SecretString) -> Result<()> {
+    info!("doing thing");
+    // ...
+}
+```
+
+**Always skip secrets in instrument.**
+
+## Testing
+
+| Type | Use Case |
+|------|----------|
+| `proptest` | Property-based tests (preferred for complex logic) |
+| Unit tests | Simple cases |
+| Integration tests | End-to-end flows |
+
+```rust
+use proptest::prelude::*;
+
+proptest! {
+    #[test]
+    fn test_invariant(input in any::<u32>()) {
+        prop_assert!(invariant_holds(input));
+    }
+}
+```
+
+## i18n (Internationalization)
+
+Uses GNU gettext with `.po` files:
+
+```rust
+use loom_i18n::{t, t_fmt, is_rtl, resolve_locale};
+
+// Simple translation
+let subject = t("es", "server.email.magic_link.subject");
+
+// With variables
+let body = t_fmt("es", "server.email.invitation.subject", &[
+    ("org_name", "Acme Corp"),
+]);
+
+// RTL support
+if is_rtl(locale) {
+    // Use dir="rtl" in HTML
+}
+```
+
+**String naming**: `{prefix}.{domain}.{component}.{element}`
+- Prefixes: `server.` (backend), `client.` (CLI)
+- Domains: `email`, `api`, `auth`, `org`
+
+**Supported locales**: `en`, `es`, `ar` (RTL)
+
+## Svelte (Web)
+
+See [web-frontend.md](web-frontend.md) for Svelte 5 patterns.
+
+Key rule: **Always use Svelte 5 runes, never Svelte 4.**

package/template/knowledge/loom/llm-proxy.md

@@ -0,0 +1,132 @@
+# LLM Proxy Architecture
+
+Loom uses a server-side proxy for all LLM interactions. API keys stay on the server; clients communicate through proxy endpoints.
+
+**Source**: `crates/loom-server-llm-proxy/`, `crates/loom-server-llm-service/`
+
+## Architecture
+
+```
+┌─────────────┐      HTTP       ┌─────────────┐     Provider API    ┌─────────────┐
+│  loom-cli   │ ───────────────▶│ loom-server │ ──────────────────▶ │  Anthropic  │
+│             │ /proxy/{provider}│             │                     │   OpenAI    │
+│ ProxyLlm-   │  /complete      │  LlmService │                     │  Vertex AI  │
+│ Client      │  /stream        │             │                     │             │
+└─────────────┘ ◀─────────────  └─────────────┘ ◀────────────────── └─────────────┘
+                  SSE stream                        SSE stream
+```
+
+## Supported Providers
+
+| Provider | Crate | Endpoint |
+|----------|-------|----------|
+| Anthropic (Claude) | `loom-server-llm-anthropic` | `/proxy/anthropic/stream` |
+| OpenAI | `loom-server-llm-openai` | `/proxy/openai/stream` |
+| Vertex AI | `loom-server-llm-vertex` | `/proxy/vertex/stream` |
+
+## LlmClient Trait
+
+```rust
+pub trait LlmClient: Send + Sync {
+    async fn complete(&self, request: LlmRequest) -> Result<LlmResponse, LlmError>;
+    async fn complete_streaming(&self, request: LlmRequest) -> Result<LlmStream, LlmError>;
+}
+```
+
+## Request/Response Types
+
+```rust
+pub struct LlmRequest {
+    pub model: String,
+    pub messages: Vec<Message>,
+    pub tools: Vec<ToolDefinition>,
+    pub max_tokens: Option<u32>,
+    pub temperature: Option<f32>,
+}
+
+pub struct LlmResponse {
+    pub message: Message,
+    pub tool_calls: Vec<ToolCall>,
+    pub usage: Option<Usage>,
+    pub finish_reason: Option<String>,
+}
+```
+
+## Streaming Events
+
+SSE wire format uses `LlmStreamEvent`:
+
+```rust
+pub enum LlmStreamEvent {
+    TextDelta { content: String },
+    ToolCallDelta { call_id: String, tool_name: String, arguments_fragment: String },
+    ServerQuery(ServerQuery),        // Phase 2: server→client queries
+    Completed { response: LlmProxyResponse },
+    Error { message: String },
+}
+```
+
+SSE format:
+```
+event: llm
+data: {"type":"text_delta","content":"Hello"}
+
+event: llm
+data: {"type":"completed","response":{...}}
+```
+
+## ProxyLlmClient (Client Side)
+
+```rust
+pub struct ProxyLlmClient {
+    base_url: String,
+    provider: LlmProvider,
+    http_client: reqwest::Client,
+    auth_token: Option<SecretString>,
+}
+
+// Factory methods
+ProxyLlmClient::anthropic("http://loom.server")
+ProxyLlmClient::openai("http://loom.server")
+ProxyLlmClient::vertex("http://loom.server")
+```
+
+## Stream Parsing
+
+Client buffers SSE chunks until `\n\n` separator:
+
+```rust
+pub struct ProxyLlmStream {
+    inner: Pin<Box<dyn Stream<Item = Result<Bytes, reqwest::Error>> + Send>>,
+    buffer: String,
+}
+```
+
+Parsing flow:
+1. Buffer bytes until `\n\n`
+2. Extract `event: llm` and `data: {...}`
+3. Parse JSON as `LlmStreamEvent`
+4. Convert to `LlmEvent` for agent
+
+## Server Query (Phase 2)
+
+Enables server to request client actions during streaming:
+
+```rust
+pub enum ServerQueryKind {
+    ReadFile { path: String },
+    ExecuteCommand { command, args, timeout_secs },
+    RequestUserInput { prompt, input_type, options },
+    GetEnvironment { keys: Vec<String> },
+    GetWorkspaceContext,
+    Custom { name, payload },
+}
+```
+
+Currently scaffolded but not fully implemented.
+
+## Security
+
+- API keys stored server-side only
+- Clients authenticate via session token
+- No direct LLM API access from clients

package/template/knowledge/loom/state-machine.md

@@ -0,0 +1,131 @@
+# Agent State Machine
+
+The core of Loom is an explicit, event-driven state machine that manages conversation flow and tool execution.
+
+**Source**: `crates/loom-common-core/src/state.rs`, `crates/loom-common-core/src/agent.rs`
+
+## Design Principles
+
+1. **Predictable** - All transitions are explicit and testable
+2. **Self-contained** - Each state carries its required context
+3. **Pure** - No async in state machine; caller drives I/O
+4. **Deterministic** - Same events → same actions (enables replay)
+
+## States
+
+| State | Description | Key Fields |
+|-------|-------------|------------|
+| `WaitingForUserInput` | Idle, ready for user message | `conversation` |
+| `CallingLlm` | LLM request in flight | `conversation`, `retries` |
+| `ProcessingLlmResponse` | Examining LLM response | `conversation`, `response` |
+| `ExecutingTools` | Running tool calls in parallel | `conversation`, `executions` |
+| `PostToolsHook` | Running post-tool hooks (auto-commit) | `conversation`, `pending_llm_request`, `completed_tools` |
+| `Error` | Recoverable error with retry | `conversation`, `error`, `retries`, `origin` |
+| `ShuttingDown` | Terminal state | (none) |
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `UserInput(Message)` | User submitted message |
+| `LlmEvent::TextDelta` | Streaming text from LLM |
+| `LlmEvent::ToolCallDelta` | Streaming tool call data |
+| `LlmEvent::Completed(LlmResponse)` | LLM finished |
+| `LlmEvent::Error(LlmError)` | LLM error |
+| `ToolCompleted { call_id, outcome }` | Tool execution finished |
+| `PostToolsHookCompleted` | Hooks finished |
+| `RetryTimeoutFired` | Retry backoff expired |
+| `ShutdownRequested` | Graceful shutdown |
+
+## Actions
+
+Actions are returned to caller indicating what I/O to perform:
+
+| Action | Description |
+|--------|-------------|
+| `SendLlmRequest(LlmRequest)` | Call LLM provider |
+| `ExecuteTools(Vec<ToolCall>)` | Run tool calls |
+| `RunPostToolsHook { completed_tools }` | Run auto-commit |
+| `WaitForInput` | Idle |
+| `DisplayMessage(String)` | Show to user |
+| `DisplayError(String)` | Show error |
+| `Shutdown` | Terminate |
+
+## Transition Table
+
+| Current State | Event | New State | Action |
+|---------------|-------|-----------|--------|
+| WaitingForUserInput | UserInput | CallingLlm | SendLlmRequest |
+| CallingLlm | TextDelta | CallingLlm | DisplayMessage |
+| CallingLlm | Completed | ProcessingLlmResponse | (internal) |
+| CallingLlm | Error (retries < max) | Error | WaitForInput |
+| CallingLlm | Error (retries >= max) | WaitingForUserInput | DisplayError |
+| ProcessingLlmResponse | (has tool calls) | ExecutingTools | ExecuteTools |
+| ProcessingLlmResponse | (no tools) | WaitingForUserInput | WaitForInput |
+| ExecutingTools | ToolCompleted (some pending) | ExecutingTools | WaitForInput |
+| ExecutingTools | ToolCompleted (all done, mutating) | PostToolsHook | RunPostToolsHook |
+| ExecutingTools | ToolCompleted (all done, non-mutating) | CallingLlm | SendLlmRequest |
+| PostToolsHook | PostToolsHookCompleted | CallingLlm | SendLlmRequest |
+| Error | RetryTimeoutFired | CallingLlm | SendLlmRequest |
+| *any* | ShutdownRequested | ShuttingDown | Shutdown |
+
+## Flow Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> WaitingForUserInput : Agent::new()
+
+    WaitingForUserInput --> CallingLlm : UserInput
+
+    CallingLlm --> CallingLlm : TextDelta / ToolCallDelta
+    CallingLlm --> ProcessingLlmResponse : Completed
+    CallingLlm --> Error : Error (retries < max)
+    CallingLlm --> WaitingForUserInput : Error (retries >= max)
+
+    ProcessingLlmResponse --> ExecutingTools : has tool calls
+    ProcessingLlmResponse --> WaitingForUserInput : no tool calls
+
+    ExecutingTools --> ExecutingTools : ToolCompleted (some pending)
+    ExecutingTools --> PostToolsHook : ToolCompleted (all done, mutating)
+    ExecutingTools --> CallingLlm : ToolCompleted (all done, no mutation)
+
+    PostToolsHook --> CallingLlm : PostToolsHookCompleted
+
+    Error --> CallingLlm : RetryTimeoutFired
+
+    WaitingForUserInput --> ShuttingDown : ShutdownRequested
+    CallingLlm --> ShuttingDown : ShutdownRequested
+    ExecutingTools --> ShuttingDown : ShutdownRequested
+
+    ShuttingDown --> [*]
+```
+
+## Mutating Tools
+
+Tools that modify files trigger `PostToolsHook` for auto-commit:
+- `edit_file`
+- `bash`
+
+Non-mutating tools skip hooks and go directly back to `CallingLlm`.
+
+## Key Implementation Pattern
+
+```rust
+// Agent is purely reactive - no async code
+pub fn handle_event(&mut self, event: AgentEvent) -> AgentResult<AgentAction> {
+    match (&mut self.state, event) {
+        (AgentState::WaitingForUserInput { conversation }, AgentEvent::UserInput(msg)) => {
+            conversation.messages.push(msg);
+            self.state = AgentState::CallingLlm { conversation: conversation.clone(), retries: 0 };
+            Ok(AgentAction::SendLlmRequest(request))
+        }
+        // ... more transitions
+    }
+}
+```
+
+**Inversion of control**: Caller executes actions (LLM calls, tool runs) and feeds events back. Enables:
+- Offline operation
+- Different async runtimes
+- Comprehensive testing
+- Replay/debugging

package/template/knowledge/loom/thread-system.md

@@ -0,0 +1,117 @@
+# Thread System
+
+Threads persist complete conversation snapshots including messages, agent state, and git context.
+
+**Source**: `crates/loom-common-thread/src/`
+
+## Thread Structure
+
+```rust
+pub struct Thread {
+    pub id: ThreadId,                      // T-{uuid7}
+    pub version: u64,                      // Optimistic locking
+
+    // Timestamps
+    pub created_at: String,
+    pub updated_at: String,
+    pub last_activity_at: String,
+
+    // Environment snapshot
+    pub workspace_root: Option<String>,
+    pub cwd: Option<String>,
+    pub loom_version: Option<String>,
+
+    // Git context
+    pub git_branch: Option<String>,
+    pub git_remote_url: Option<String>,
+    pub git_initial_branch: Option<String>,
+    pub git_initial_commit_sha: Option<String>,
+    pub git_current_commit_sha: Option<String>,
+    pub git_start_dirty: Option<bool>,
+    pub git_end_dirty: Option<bool>,
+    pub git_commits: Vec<String>,          // All commits observed
+
+    // Conversation
+    pub provider: Option<String>,
+    pub model: Option<String>,
+    pub conversation: ConversationSnapshot,
+    pub agent_state: AgentStateSnapshot,
+
+    // Metadata
+    pub metadata: ThreadMetadata,          // Title, tags, pinned
+    pub visibility: ThreadVisibility,      // Organization/Private/Public
+    pub is_private: bool,                  // Local-only (no sync)
+    pub is_shared_with_support: bool,
+}
+```
+
+## ThreadStore Trait
+
+```rust
+pub trait ThreadStore: Send + Sync {
+    async fn load(&self, id: &ThreadId) -> Result<Option<Thread>, ThreadStoreError>;
+    async fn save(&self, thread: &Thread) -> Result<(), ThreadStoreError>;
+    async fn list(&self, limit: u32) -> Result<Vec<ThreadSummary>, ThreadStoreError>;
+    async fn delete(&self, id: &ThreadId) -> Result<(), ThreadStoreError>;
+    async fn save_and_sync(&self, thread: &Thread) -> Result<(), ThreadStoreError>;
+}
+```
+
+## LocalThreadStore
+
+Default implementation for local persistence:
+
+- **Location**: `~/.local/share/loom/threads/{ThreadId}.json`
+- **Atomic writes**: temp file + rename
+- **Search**: FTS5 across title, branch, messages, tags, commit SHAs
+
+## ConversationSnapshot
+
+```rust
+pub struct ConversationSnapshot {
+    pub messages: Vec<Message>,
+}
+
+pub struct Message {
+    pub role: Role,               // System, User, Assistant, Tool
+    pub content: String,
+    pub tool_call_id: Option<String>,
+    pub name: Option<String>,
+    pub tool_calls: Vec<ToolCall>,
+}
+```
+
+## ThreadMetadata
+
+```rust
+pub struct ThreadMetadata {
+    pub title: Option<String>,
+    pub tags: Vec<String>,
+    pub pinned: bool,
+}
+```
+
+## Visibility
+
+```rust
+pub enum ThreadVisibility {
+    Organization,    // Visible to org members
+    Private,         // Only visible to owner
+    Public,          // Publicly shareable
+}
+```
+
+## Key Features
+
+1. **Complete snapshot** - Full conversation + agent state + git context
+2. **Optimistic locking** - Version numbers prevent conflicts
+3. **FTS5 search** - Full-text across all thread content
+4. **Local-first** - `is_private` keeps threads from syncing
+5. **Git tracking** - Captures branch, commits, dirty state
+
+## Persistence Flow
+
+1. Agent processes events
+2. Thread updated after each action
+3. `save()` writes atomic JSON
+4. Optional `save_and_sync()` for server sync

package/template/knowledge/loom/tools.md

@@ -0,0 +1,94 @@
+# Tool System
+
+Tools extend the agent's capabilities to perform file operations, execute commands, and search the web.
+
+**Source**: `crates/loom-cli-tools/src/`
+
+## Tool Trait
+
+```rust
+#[async_trait]
+pub trait Tool: Send + Sync {
+    fn name(&self) -> &str;
+    fn description(&self) -> &str;
+    fn input_schema(&self) -> serde_json::Value;
+    async fn invoke(&self, args: serde_json::Value, ctx: &ToolContext) -> Result<serde_json::Value, ToolError>;
+}
+```
+
+## ToolRegistry
+
+HashMap-based dynamic dispatch for tool lookup:
+
+```rust
+pub struct ToolRegistry {
+    tools: HashMap<String, Arc<dyn Tool>>,
+}
+
+impl ToolRegistry {
+    pub fn register(&mut self, tool: Arc<dyn Tool>);
+    pub fn get(&self, name: &str) -> Option<Arc<dyn Tool>>;
+    pub fn list(&self) -> Vec<&str>;
+}
+```
+
+## Built-in Tools
+
+### File Operations
+
+| Tool | Purpose |
+|------|---------|
+| `ReadFileTool` | Read file contents (truncates large files) |
+| `ListFilesTool` | Directory listing with path validation |
+| `EditFileTool` | Snippet-based text replacement (atomic edits) |
+
+### Command Execution
+
+| Tool | Purpose |
+|------|---------|
+| `BashTool` | Execute shell commands with timeout/truncation |
+
+**Note**: `BashTool` is a "mutating" tool that triggers `PostToolsHook` for auto-commit.
+
+### LLM/Search
+
+| Tool | Purpose |
+|------|---------|
+| `OracleTool` | Consult secondary LLM via server proxy |
+| `WebSearchToolGoogle` | Web search via Google CSE |
+| `WebSearchToolSerper` | Web search via Serper API |
+
+## Security
+
+All tools validate paths against workspace boundaries:
+- Prevents directory traversal (`../`)
+- Restricts to project root
+- Validates file existence
+
+## Tool Execution Flow
+
+1. LLM returns `tool_calls` in response
+2. Agent transitions to `ExecutingTools` state
+3. Caller invokes tools via `ToolRegistry.get(name).invoke(args, ctx)`
+4. Each tool returns success/error outcome
+5. Results collected in `ToolExecutionStatus`
+6. When all complete → check if mutating → `PostToolsHook` or `CallingLlm`
+
+## ToolContext
+
+Passed to every tool invocation:
+
+```rust
+pub struct ToolContext {
+    pub workspace_root: PathBuf,
+    pub cwd: PathBuf,
+    pub thread_id: Option<ThreadId>,
+}
+```
+
+## Adding a New Tool
+
+1. Implement the `Tool` trait
+2. Register with `ToolRegistry`
+3. Add to tool definitions sent to LLM
+4. If mutating, ensure it triggers `PostToolsHook`