create-hq 6.0.0 → 10.0.0

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

@@ -1,169 +0,0 @@
-# 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

@@ -1,132 +0,0 @@
-# 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

@@ -1,131 +0,0 @@
-# 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

@@ -1,117 +0,0 @@
-# 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

@@ -1,94 +0,0 @@
-# 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`