init

Author: radicalkjax

.cargo/config.toml

@@ -0,0 +1,12 @@
+[build]
+rustflags = [
+  "-D", "warnings",            # all warnings are errors
+  "-D", "clippy::unwrap_used", # no unwrap() in library code
+  "-D", "clippy::expect_used", # no expect() in library code (use thiserror)
+  "-D", "clippy::panic",       # no panic!() in library code
+]
+
+# Ban native-tls to enforce rustls across all transitive dependencies.
+# Any crate pulling native-tls will get this stub, which fails at compile time.
+[patch.crates-io]
+native-tls = { path = "vendor/native-tls-stub" }

.claude/phases/phase-1a.md

@@ -0,0 +1,157 @@
+# Phase 1b — Bot Foundations
+
+> Source: `docs/current-arch/ARCHITECTURE.md` §3, §6.9, §14.1-14.2
+> Depends on: Phase 1a complete
+
+## Goal
+
+Classical bot runtime with deterministic command routing. First chat
+connector (Telegram). No AI. Users talk to the bot through Telegram and
+get the same automation they configured in Phase 1a, plus interactive
+commands.
+
+## Two Sub-Milestones
+
+**1b-i: Bot core** — testable without any chat platform.
+**1b-ii: First chat connector** — Telegram makes the bot reachable.
+
+## Milestone 1b-i: springtale-bot
+
+The bot runtime lives in `crates/springtale-bot/`. It depends on core,
+crypto, connector, store, and transport.
+
+**How the event loop works:**
+
+```rust
+pub async fn run(bot: &Bot) -> Result<()> {
+    loop {
+        tokio::select! {
+            Some(msg) = bot.connector_events.recv() => {
+                // Route through command router
+                // On error: log + continue (NEVER propagate ? — kills the loop)
+            }
+            Some(trigger) = bot.rule_events.recv() => {
+                // Evaluate and dispatch through rule engine
+            }
+            Some(job) = bot.job_events.recv() => {
+                // Execute scheduled job
+            }
+        }
+    }
+}
+```
+
+**Critical design detail:** The event loop must NOT use `?` on individual
+message processing. A single bad message must not crash the bot. Log the
+error, continue to next event. This was flagged in the architecture audit.
+
+**Command router (no AI):**
+- `router::prefix` — exact prefix match: `/search`, `/help`, `/remind`, `/status`
+- `router::pattern` — regex and keyword matching for non-slash triggers
+- `router::alias` — user-defined aliases persisted in SQLite (e.g., `/s` -> `/search`)
+- `router::fallback` — no match returns "Unknown command. Try /help" (AI fallback added in Phase 2a)
+- Router is a pure function: `(message_text) -> RouteResult::Command(name, args) | RouteResult::NoMatch`
+
+**Handler dispatch:**
+- `handler::registry` — HashMap of command name -> handler function
+- `handler::builtin` — `/help` (list commands), `/status` (bot health), `/rules` (list active rules), `/connectors` (list installed)
+- `handler::connector` — generic handler: connector name + action derived from command. When connector-presearch is installed, `/search <query>` auto-registers.
+
+**How auto-registration works:** When a connector is installed via
+`springtale connector install`, the bot reads its `actions()` and
+registers each as a command. `connector-presearch` with action `search`
+becomes `/search`. `connector-github` with action `create_issue` becomes
+`/github create_issue`. Users create aliases for convenience.
+
+**Conversation state:**
+- `state::session` — per `(user_id, channel_id)` key in SQLite. Tracks what the bot last said, what it's waiting for (multi-step flows). Row-level isolation: no cross-user state access.
+- `state::prefs` — user preferences: timezone, language, notification settings. Persisted in SQLite. User manages via `/prefs set timezone America/New_York`.
+- `state::persona` — bot persona config: name, response tone, template library. Loaded from `springtale.toml`. Not user-configurable (admin sets it).
+
+**Persistent memory:**
+- `memory::persistent` — SQLite-backed. Structured typed schemas, not arbitrary strings. Encrypted at rest via vault.
+- `memory::context` — sliding window of recent conversation per user. Configurable size (default: 50 messages).
+- `memory::compaction` — Phase 1b: simple truncation (drop oldest). Phase 2a: AI summarization when adapter is plugged in.
+
+**Bot identity:**
+- `identity::bot_id` — Ed25519 keypair generated via springtale-crypto. Stored in vault.
+- Phase 1b: keypair is the bot's identity. Simple.
+- Phase 3: HKDF derives per-community pseudonyms from this keypair for Rekindle integration. The derivation code is not written yet — just the keypair.
+
+**Safety features (from audit §2.8 IPV threat model):**
+- No OS notifications by default. Connector events and bot responses do not trigger push notifications unless user explicitly enables via `/prefs set notifications on`.
+- Vault auto-lock after configurable inactivity (default: 5 min). CLI prompts for passphrase to resume. Tauri modal in Phase 2b.
+
+**Integration with springtaled:**
+- `springtaled` startup adds a new step between scheduler start and API start: initialize `springtale-bot` with references to connector registry, rule engine, scheduler, and store
+- Bot event loop runs as a tokio task alongside existing scheduler tasks
+- The rule engine from Phase 1a runs INSIDE the bot's event loop — cron rules, webhook rules, filesystem rules all fire through the same dispatch path
+
+**Testing (without Telegram):**
+- Headless integration test: fire a `Trigger::ConnectorEvent` -> bot routes -> handler executes -> response generated
+- Command routing tests: prefix match, pattern match, alias resolution, fallback
+- Session isolation tests: two users send commands concurrently, state does not leak
+- Memory compaction test: fill to N+1, verify oldest dropped
+
+## Milestone 1b-ii: connector-telegram
+
+Standard connector structure per `.claude/rules/connector-guidelines.md`.
+
+**How to build:**
+
+Telegram Bot API client. Two modes of receiving updates:
+1. **Webhook mode:** Telegram sends HTTPS POST to your endpoint. Requires public URL. Uses the management API's webhook endpoint: `POST /webhook/connector-telegram/message_received`.
+2. **Long-polling mode:** Bot calls `getUpdates` in a loop. Works behind NAT. Default for dev/self-hosted.
+
+Mode selected in connector config. Long-polling is default.
+
+**Auth:**
+- Bot token from BotFather, stored as `Secret<String>` in connector config
+- Webhook signature verification not natively supported by Telegram Bot API (unlike GitHub). Instead: use secret path token in webhook URL as auth.
+
+**Connector trait implementation:**
+- `triggers()`: `message_received`, `command_received` (filtered by /prefix)
+- `actions()`: `send_message`, `send_photo`, `edit_message`, `delete_message`, `send_inline_keyboard`
+- `execute("send_message", { chat_id, text, parse_mode })` -> call Telegram `sendMessage` API
+- `on_event("message_received", handler)` -> handler called for every incoming message
+
+**Typed API client:**
+- `client::api.rs` — reqwest client to `https://api.telegram.org/bot{token}/`
+- All request/response types as Rust structs with serde
+- Methods: `send_message`, `send_photo`, `edit_message_text`, `delete_message`, `get_updates`, `set_webhook`, `delete_webhook`
+- Inline keyboard builder for interactive buttons
+- Message formatting: MarkdownV2 and HTML modes
+
+**Research needed:** Telegram Bot API docs (https://core.telegram.org/bots/api).
+Update polling semantics (`offset` parameter for confirming received updates).
+MarkdownV2 escaping rules (Telegram has unusual escaping requirements).
+Rate limits (30 messages/second to same chat, 20 messages/minute to same group).
+
+**Integration:**
+- Install: `springtale connector install ./connector-telegram.toml`
+- Bot auto-registers Telegram message handler in event loop
+- User sends `/search tokyo weather` in Telegram chat
+- Bot receives via connector-telegram `on_event`
+- Router matches `/search` prefix -> SearchHandler
+- Handler calls `connector-presearch.execute("search", { query: "tokyo weather" })`
+- Result formatted via response template
+- Handler calls `connector-telegram.execute("send_message", { chat_id, text: formatted_result })`
+- User sees result in Telegram
+
+**Testing:**
+- Mock Telegram API server (axum test server returning canned responses)
+- Test: send_message serialization matches Telegram API format
+- Test: getUpdates polling loop handles timeout, empty response, error response
+- Integration test: message received -> routed -> connector called -> reply sent
+
+## Not In Phase 1b
+
+- No AI fallback parser (Phase 2a — router returns "unknown command" for now)
+- No AI-powered memory compaction (Phase 2a — truncation only)
+- No HKDF pseudonym derivation on BotId (Phase 3)
+- No recursive pipeline orchestration (Phase 2a)
+- No sub-agent spawning (Phase 2a)
+- No sentinel behavioral monitor (Phase 2a)
+- No additional chat connectors beyond Telegram (Phase 2a)
+- No ATProto bridge (Phase 2a)
+- No Rekindle bridge (Phase 3)

.claude/phases/phase-1b.md

@@ -0,0 +1,143 @@
+# Phase 2a — Full Chat Coverage + AI Adapters
+
+> Source: `docs/current-arch/ARCHITECTURE.md` §3, §6.7, §6.9-6.10, §14.3-14.5
+> Depends on: Phase 1b complete
+
+## Goal
+
+Full chat platform coverage. AI adapters as optional fallback parser and
+pipeline action. NL->Rule parser. Runtime behavioral monitoring. Sub-agent
+orchestration. This is where Springtale becomes a full, safe replacement
+for the existing agent/bot platforms.
+
+## Transport Upgrade
+
+Phase 2a upgrades from `LocalTransport` (Unix sockets, same-machine) to
+`HttpTransport` (LAN/VPN, axum server + reqwest client, mTLS).
+
+**How to integrate:**
+- Implement `HttpTransport` in `crates/springtale-transport/src/http/`
+- `http::server` — axum inbound endpoint, mTLS with rustls
+- `http::client` — reqwest outbound, peer cert validation
+- `runtime::boot` in `springtaled` selects transport based on `springtale.toml` config
+- All existing code uses `Arc<dyn Transport>` — no changes needed outside transport crate
+- mTLS cert fingerprints stored in `springtale-store`
+
+**Research needed:** mTLS setup with rustls + reqwest. Peer certificate
+pinning pattern. DNS rebinding protection via Host header validation.
+
+## AI Adapters
+
+The `AiAdapter` trait (defined in Phase 1a with NoopAdapter only) gets
+real implementations. These are thin HTTP clients to user-provided endpoints.
+
+**How to integrate:**
+- Each adapter is a feature-gated module in `crates/springtale-ai/src/`
+- `ollama::adapter` — HTTP client to `localhost:11434`, Ollama REST API
+- `openai::adapter` — `/v1/chat/completions` for any OpenAI-compatible API (GPT, Gemini, Kimi, DeepSeek, OpenRouter)
+- `anthropic::adapter` — `/v1/messages` with native tool_use
+- `voice::stt` — Whisper-compatible speech-to-text bridge
+- `voice::tts` — ElevenLabs / Piper text-to-speech bridge
+- User configures endpoint in `springtale.toml` or `springtale-cli ai configure`
+- HTTPS validated (HTTP rejected unless `--allow-insecure-ai-endpoint`)
+- `AiOptions { max_tokens, timeout }` controls cost. Default: 4096 tokens, 30s
+- Response body 10 MiB limit
+- `AiRequest` is a closed enum — `Secret<T>` values cannot serialize into it
+
+**Research needed:** Ollama REST API schema. OpenAI /v1/chat/completions
+streaming SSE format. Anthropic /v1/messages tool_use format. Whisper API
+variants (OpenAI, local faster-whisper).
+
+## NL->Rule Parser
+
+User says "notify me on Discord when my Kick stream goes live" -> AI generates
+structured `Rule` (TOML) -> rule runs deterministically forever, no AI needed again.
+
+**How to integrate:**
+- `springtale-ai::parser::rule_gen` — prompt templates inject available connector schemas
+- `springtale-ai::parser::prompt` — structured output prompt for the user's AI
+- Output is a `Rule` struct (from springtale-core), validated before saving
+- User reviews generated TOML before enabling
+- Works with any AI adapter (Ollama, OpenAI, Anthropic)
+
+## Chat Connectors (7)
+
+Each follows `.claude/rules/connector-guidelines.md`.
+
+| Connector | Key Integration Notes |
+|---|---|
+| `connector-discord` | Gateway WebSocket (not REST polling). Slash command registration. Voice channel join for presence. Embed builder. discord.js-equivalent in Rust. |
+| `connector-signal` | signal-cli bridge process. E2E encrypted messages. Disappearing messages support. No phone number exposed to Springtale. |
+| `connector-whatsapp` | Baileys-equivalent protocol. **Likely NativeConnector** (needs persistent WebSocket + Signal Protocol — too complex for WASM sandbox). QR code pairing. |
+| `connector-matrix` | Matrix SDK (ruma crate). Federated rooms. E2E encryption via vodozemac. Room state management. |
+| `connector-irc` | Lightweight. Raw TCP + rustls-tls. Channel join/part/msg. SASL auth. |
+| `connector-slack` | Socket mode (not HTTP). Slash commands. Block Kit. Thread replies. |
+| `connector-nostr` | NIP-01 relay client. Event signing with Ed25519. Encrypted DMs (NIP-04/NIP-44). |
+
+**Research needed per connector:** API docs, auth flows, WebSocket vs REST,
+rate limits, message format. connector-whatsapp needs special attention —
+Baileys reverse-engineers WhatsApp's protocol and may need NativeConnector
+trust level rather than WASM sandbox.
+
+## springtale-sentinel
+
+Runtime behavioral monitor. Ships with hard constraints only (Layer 1).
+
+**How to integrate:**
+- New crate: `crates/springtale-sentinel/`
+- Sentinel instance created in `springtaled` startup, passed to bot runtime
+- Bot runtime wraps pipeline dispatch: `sentinel.evaluate(action, connector)` before each stage
+- Sentinel does NOT live in springtale-core (no dependency cycle)
+- Integration point is `springtaled` and `springtale-bot` event loop
+
+**Modules:**
+- `rate_limiter` — actions/minute per connector, default 60, configurable
+- `circuit_breaker` — 3 consecutive failures -> stage disabled, user notified, auto-reset after cooldown
+- `dead_man` — N actions/minute without user interaction -> pause all pipelines
+- `toxic_pairs` — dangerous capability combos blocked at install time
+- `impact` — action tagged read-only / reversible / destructive
+- `audit::trail` — append-only SQLite table, every action logged
+- `audit::export` — export for CLI review + compliance
+
+## Recursive Pipeline Orchestration
+
+Derived from Clicky's subagent pattern.
+
+**How to integrate:**
+- `springtale-bot::orchestrator::recursive` — pipeline stage can spawn child pipeline
+- Each child gets `parent_remaining_fuel / num_children` fuel budget
+- Max concurrent children: 8. Max recursive depth: 4.
+- Children inherit read-only `PipelineContext` snapshot. Write to own context.
+- Parent collects child results at spawn-point stage.
+- `springtale-bot::orchestrator::subagent` — spawn child agent with scoped capabilities
+- `springtale-bot::orchestrator::coordinator` — multi-bot coordination via shared state
+
+## ATProto Bot Bridge
+
+Derived from malwarevangelist-bot.
+
+**How to integrate:**
+- `springtale-bot::bridge::atproto` — wraps connector-bluesky triggers/actions
+- `ATProtoBotBridge` provides `on_mention`, `on_follow`, `post`, `reply`
+- Maps Bluesky events to bot event loop
+- Session management patterns from malwarevangelist-bot's enCore engine
+
+## Memory-Only / Ephemeral Mode
+
+`--ephemeral` flag: vault exists only in memory. All state lost on exit.
+
+**How to integrate:**
+- `springtale-store::backend::memory` — in-memory StorageBackend implementation
+- `springtale-crypto::vault` — option to skip file persistence
+- `springtaled --ephemeral` creates everything in memory, warns user on startup
+
+## Not In Phase 2a
+
+- No Tauri desktop/mobile shell (2b)
+- No visual rule builder (2b)
+- No dashboard web UI (2b)
+- No browser automation connector (2b)
+- No Veilid transport (Phase 3)
+- No Rekindle bot bridge (Phase 3)
+- No statistical baseline learning for sentinel (deferred)
+- No trajectory analysis for sentinel (deferred)