v0.3.21 — Reasoning Loop Engine

Reasoning Loop Engine

Autonomous plan-execute-evaluate cycle that can decompose goals, invoke skills, assess results, and iterate toward an answer.

Features

• Plan → Execute → Evaluate → Decide cycle with configurable LLM tier (default: local)
• Whitelisted skill execution through existing security stack (capability tokens, circuit breakers, content sanitizer)
• Full audit trail — every LLM prompt, response, skill call, rubric score, and working memory snapshot persisted to DB
• Deterministic pre-filter skips LLM decision calls for obvious cases (0ms decisions)
• Deterministic plan validation rejects malformed steps before execution
• Working memory compression every 3 iterations prevents stale context accumulation
• Evaluation score trend (improving/stable/degrading) injected into decision prompt
• Proportional time budget (~300s per step, scales with plan size)
• Orphaned session cleanup — terminate callback, boot sweep, LiveView mount check
• User intervention — pause, resume, steer, abort, step override (all real-time via PubSub)
• Dual-mode chat page — toggle between simple Chat and Reasoning mode
• Skill outputs embedded to pgvector for future session context
• Configurable LLM tier — default local, configurable to light/medium/heavy from config page
• Forced summary on adjust oscillation — prevents infinite polish loops

Known Limitations

• Output quality is model-dependent. Local models (7B-14B) produce functional but often imprecise results. They hallucinate details when source material is thin and struggle with multi-step context tracking. Routing to a stronger tier via reasoning.llm_tier improves quality at the cost of privacy and API spend.
• JSON schema drift with local models. The parser includes extensive normalization but novel deviations may still cause parse failures.
• Evaluation rubric is LLM-judged. Local models tend to rate their own output favorably. The deterministic pre-filter mitigates this for obvious cases.
• No parallel skill execution. Skills run sequentially, one per iteration.
• Working memory degradation. Long sessions (10+ iterations) accumulate stale context despite compression.

Configuration

All settings editable from the config page:

• reasoning.enabled — feature flag
• reasoning.llm_tier — local/light/medium/heavy
• reasoning.max_iterations — default 15
• reasoning.max_llm_calls — default 60
• reasoning.skill_whitelist — JSON array of allowed skill names
• reasoning.done_confidence_threshold — default 0.7
• reasoning.stuck_threshold — default 3
• Prompt templates editable at runtime

v0.3.20: Per-provider options, Qwen3, RAG pipeline, Services page

What's New

Services Page

• New /services admin page with real connectivity checks for 9 external services
  • Database (SELECT 1), Google API (OAuth token), Telegram Bot (sends test message), Discord Bot (sends test message), 2FA/TOTP (challenge via Telegram with PubSub auto-update), Ollama (lists models), LM Studio (lists models), GitHub API (authenticates with PAT), Web Automator (health check), Embeddings (stale model detection)
• Config button + Check button per service

RAG Pipeline Overhaul

• Embedding metadata — tracks embedding_model, embedding_dim, embedded_at per entry; stale_embedding_count/1 detects model mismatches; Embeddings panel on Services page
• Relevance grading — min_score opt filters vector results via SQL cosine similarity threshold (1 - (embedding <=> ?))
• Query rewriting — RAG.QueryRewriter generates 2-3 semantic variants via light-tier LLM with ETS cache (5min TTL); opt-in via rewrite: true
• Semantic chunking — RAG.Chunker splits on markdown headers, function defs, paragraphs (boundary-aware, not sliding window); long content auto-chunks into parent + children; search deduplicates chunks from same parent
• Fallback routing — RAG.Fallback searches both Memory + Knowledge with rewriting + grading; Research skill now cross-store; context section omitted when nothing found
• Research skill uses search_with_fallback/2 for full RAG pipeline
• CodeGenerator knowledge searches use query rewriting

Per-Provider Inference Options

• LLM providers now support per-model inference options (temperature, num_ctx, top_p, etc.)
• Dynamic options form in Admin > LLM Providers shows relevant fields based on provider type
  • Ollama: num_ctx, num_predict, temperature, top_p, top_k, repeat_penalty, num_thread, num_gpu
  • OpenAI-compatible: temperature, top_p, max_tokens, thinking toggle
  • Gemini/Anthropic: temperature, top_p, max_tokens

Ollama Chat API

• Switched from /api/generate to /api/chat with proper messages format

Qwen3 Thinking Mode Support

• Thinking toggle per provider for Qwen3 models (disables chain-of-thought token burn)
• OpenAI-compatible client falls back to reasoning_content when content is empty

Embedding Throttle

• New EmbedThrottle GenServer limits concurrent embedding requests (max 3) to prevent Finch connection pool exhaustion during bulk knowledge ingestion

Workflow Step Editor Fixes

• Save no longer closes the workflow or step editor — stay in place with flash confirmation
• Scaffold values (prompt template, config) now persist correctly to DB
• Nil llm_tier no longer silently blocks saves

GitHub Security Review

• Refactored as pure diff fetcher (no embedded LLM call)
• 5 modes: latest_pr, all_prs, latest_push, specific_pr, specific_commit
• Config presets in step editor dropdown

LLM Transform Simplified

• Removed config field from step editor
• Added 10 prompt presets: Security Review, Code Review, Changelog, Bullet Points, etc.
• Config rendered above Prompt Template for skills that use both

Config Page Improvements

• embedding.provider now shows a dropdown of enabled provider names
• Yellow tooltip hints on all settings
• Config seeder fix: env-backed settings no longer overwrite DB values on boot

Dashboard Cleanup

• Google status card moved to Services page
• Node name moved to dashboard header next to version

Forge / Code Generator

• Skill template and behaviour fetched directly from knowledge base
• <think> tags from Qwen3 models stripped before code extraction
• Knowledge searches now use query rewriting for broader retrieval

Migrations

• add_options_to_llm_providers — options map column on llm_providers
• add_embedding_metadata — embedding_model, embedding_dim, embedded_at on both stores
• add_chunking_support — parent_id, chunk_index on both stores

v0.3.19 — API Resource Discovery & Schema-Aware Workflows

What's New

API Resource Probe & OpenAPI Discovery

When creating or updating a resource of type api, AlexClaw now automatically probes the URL and attempts to discover an OpenAPI/Swagger specification.

• Light probe — HEAD/GET request to verify reachability, stores HTTP status, content-type, and server header in resource metadata
• OpenAPI discovery — scans common spec paths (/openapi.json, /swagger.json, /api-docs, etc.) relative to both the full URL and base host. Parses the spec and stores: title, version, base path, auth schemes, and up to 100 endpoints
• Async execution — discovery runs in the background under TaskSupervisor, PubSub notifies the UI on completion
• Manual re-discovery — "Discover" button on API resources in the admin UI
• Discovery status badges — table shows "discovering...", endpoint count, "no spec", or "discovery failed"
• Discovery summary panel — when editing an API resource with completed discovery, shows base URL, API title/version, endpoint count, auth schemes, and probe timestamp

api_request Skill — Resource Consumption

The api_request skill now consumes assigned API resources:

• URL resolution — if step config contains {base_url} placeholder, it's replaced with the resource's discovered base URL + base path. If config has a "path" key instead of "url", the full URL is constructed from the resource
• Auth header merging — if resource metadata contains "auth": {"header": "...", "value": "..."}, headers are merged into the request (without overriding existing ones)
• Backward compatible — steps without assigned resources work exactly as before

Schema-Aware Endpoint Selection in Workflow Step Editor

When adding an api_request step to a workflow with an assigned API resource that has discovered endpoints:

• Endpoint dropdown — appears above the config textarea, listing all discovered endpoints grouped by resource (ResourceName: GET /path — summary)
• Config pre-fill — selecting an endpoint fills the JSON config with method, URL, empty headers, and body

Documentation

• README, ARCHITECTURE, and SECURITY updated to align with v0.3.18 features (composable fetch skills, hexdocs scrapers, Forge page)

Files Changed

• lib/alex_claw/resources/api_discovery.ex — new discovery module
• lib/alex_claw/resources.ex — discovery hook on create/update
• lib/alex_claw/skills/api_request.ex — resource consumption + URL/auth resolution
• lib/alex_claw_web/live/admin_live/resources.ex — PubSub, discover event
• lib/alex_claw_web/live/admin_live/resources.html.heex — badges, button, summary panel
• lib/alex_claw_web/live/admin_live/workflows.ex — endpoint extraction, selection event
• lib/alex_claw_web/live/admin_live/workflows.html.heex — endpoint dropdown

Test Results

906 tests, 0 failures, 1 skipped

v0.3.18 — Forge & Knowledge Pipeline

What's New

Forge (Pre-Alpha)

Interactive skill generation page. Describe a goal in natural language, and the system automatically generates, compiles, validates, and hot-loads a dynamic skill — with real-time feedback at each step.

• Two-column layout: chat (goals/status) + code output
• Auto-iterate with configurable retries — keeps retrying on failure with error context
• Structural validation for external skills (no fake HTTP calls during validation)
• Defaults to local LLM (LM Studio) and Docs-only RAG context
• CodeGenerator module extracted from Coder skill for shared use

Chat Simplified

Stripped RAG/knowledge search and context source selector. Chat is now a clean conversational interface with model selection and memory context.

Knowledge Pipeline

• All 5 scraper skills now support timeout_ms, delay between items, and deadline-based execution
• Detailed reporting — every item shows stored/skipped/failed/timeout with reason
• New: HexDocs Guides Scraper — indexes guide pages (README, getting started, deployment, mix tasks). 649 guide chunks from Phoenix, LiveView, Ecto, Plug, Req, Jason
• Browser User-Agent — all SkillAPI HTTP calls include a Chrome User-Agent to prevent site blocking
• Skill versions bumped for all updated scrapers

Executor

• timeout_ms in step config JSON overrides the 30-second default SafeExecutor timeout — critical for long-running scraper workflows

UI Improvements

• Skill page: Reload/Unload/Upload buttons show "Waiting 2FA..." with yellow pulse animation during 2FA challenge
• Workflows page: Runs counter refreshes automatically when a run completes

Code Quality

• Convention violations: 164 → 19 (all remaining are intentional process_dictionary for auth context)
• Skill template updated with external/0, step_fields/0, config_hint/0, config_scaffold/0 docs

v0.3.17 — Dynamic Skill Metadata

What's New

Dynamic Skill Metadata

Skills now declare their own UI metadata via 7 new optional callbacks on the AlexClaw.Skill behaviour:

Callback	Purpose
step_fields/0	Which fields to show in the step editor (:llm_tier, :llm_model, :prompt_template, :config)
config_hint/0	Placeholder text for the config JSON field
config_scaffold/0	Default config map pre-filled on new steps
config_presets/0	Named config templates shown as quick-fill buttons
prompt_presets/0	Named prompt templates shown as quick-fill buttons
config_help/0	Tooltip help text for the config field
prompt_help/0	Tooltip help text for the prompt field

The workflow step editor reads metadata from SkillRegistry.get_skill_meta/1 and renders only the fields a skill needs. Zero hardcoded skill knowledge remains in the LiveView — ~200 lines of pattern-match functions removed.

For Dynamic Skill Authors

• Skills that don't use LLM should declare def step_fields, do: [:config] — the step editor will hide LLM Tier, Provider, and Prompt Template fields
• Skills with no configurable fields can declare def step_fields, do: []
• All callbacks are optional — undeclared defaults to showing all fields (backward compatible)
• See Writing Custom Skills for full documentation and examples

Other

• .gitattributes enforces LF line endings for .ex, .exs, .heex files

v0.3.16 — Workflow Export/Import

What's New

Workflow Export/Import

• Export workflows as self-contained JSON files — includes definition, all steps (configs, prompts, routes, input_from), and full resource data (name, type, URL, tags, metadata)
• Import from JSON via Admin UI file upload — resources matched by name+URL or created automatically. Imported workflows are disabled by default with (imported N) suffix on name conflicts
• JSON files are portable across instances and can be edited manually before importing

Workflow UI Improvements

• Name filter — search/filter the workflow list by typing in the input under the Name column
• Action buttons — Run, Runs, Export, Clone, Edit, Del restyled as colored pill buttons

Bug Fixes

• duplicate_workflow now correctly copies input_from and routes fields when cloning

Docker

• Services renamed for clarity: alexclaw → alexclaw-prod, db → db-prod (production), db → db-test (test)
• Explicit container_name set on all services for clean Docker Desktop display

Developer Experience

• Makefile: quiet Docker builds for tests, automatic teardown after test runs, new test-down target
• New .claude/rules/test-procedure.md documenting the test workflow

Documentation

• README, INSTALLATION, ALEXCLAW_ARCHITECTURE updated
• readthedocs pages updated: workflow-engine, admin-ui, docker, vps, installation, changelog

v0.3.15 — Composable Skills: Separate Fetch from LLM

DEPRECATION NOTICE: The monolithic skills web_browse, web_search, and rss_collector will be removed in v0.4.0 (estimated May 2026). These skills bundle fetching and LLM processing in a single step, which forces LLM provider/tier selection on pure fetch operations and wastes tokens when chained with llm_transform.

You have ~1 month to migrate existing workflows to the new composable pattern. See migration examples below.

---

What's New

Composable Fetch Skills (No LLM)

New pure-fetch skills that do one thing only — fetch data, return it, move on. No forced LLM call, no hidden summarization, no wasted tokens.

Skill	Description
web_fetch	Fetches a URL, returns extracted text. No LLM.
web_search_fetch	Searches DuckDuckGo, fetches top pages, returns raw content. No LLM.
rss_fetch	Fetches RSS feeds, deduplicates, filters recent items, returns JSON. No LLM.
llm_score	Batch-scores items for relevance via single LLM call. Configurable interests, threshold, max items.

Migration Guide

Web Browsing

Before (monolithic):

Step 1: web_browse  [fetches URL + forces LLM summarization]
Step 2: telegram_notify

After (composable):

Step 1: web_fetch        → raw page content (no LLM tier needed)
Step 2: llm_transform    → summarize/translate/classify (you choose the prompt)
Step 3: telegram_notify  → deliver

Web Search

Before:

Step 1: web_search  [searches + fetches pages + forces LLM synthesis]
Step 2: telegram_notify

After:

Step 1: web_search_fetch  → raw search results with page content
Step 2: llm_transform     → synthesize answer (your prompt, your tier)
Step 3: telegram_notify   → deliver

RSS News Workflow

Before:

Step 1: rss_collector  [fetches + scores + notifies all-in-one]
Step 2: telegram_notify

After:

Step 1: rss_fetch        → raw feed items as JSON
Step 2: llm_score        → scored + filtered by relevance (light tier)
Step 3: llm_transform    → format as morning briefing (medium tier)
Step 4: telegram_notify  → deliver

Why This Matters

• No forced LLM on fetch steps — web_fetch and rss_fetch don't show LLM tier/provider in the UI
• No wasted tokens — fetching a page doesn't cost an LLM call anymore
• Full control — you pick the prompt, the tier, the provider at each step
• Visible data flow — every intermediate result is inspectable in the workflow run view
• Reusable — llm_score works with any list of items, not just RSS

Also in this release

• llm_transform prompt scaffolds: Summarize, Translate, Classify, Extract, Q&A, Rewrite, Filter
• llm_score config scaffolds: News scoring, Strict filter
• rss_fetch config scaffolds: Recent 24h, Recent 48h, Force all

---

Full changelog: v0.3.14...v0.3.15

v0.3.14 — Content Sanitization & Prompt Injection Defense

What's New

Content Sanitization (Prompt Injection Defense)

AlexClaw now has architectural defenses against prompt injection attacks on external-facing skills.

External skill tagging — Skills that fetch external data declare def external, do: true. The SkillRegistry tracks this flag and the workflow executor auto-sanitizes their output.

AST-based detection — Dynamic skills are source-scanned at load time for HTTP/socket library calls (Req, HTTPoison, Finch, Tesla, gen_tcp, SkillAPI.http_*). Undeclared external calls → skill rejected. Fail-closed.

7-layer heuristic sanitizer (AlexClaw.ContentSanitizer):

1. Hidden HTML detection (noscript, template, aria-hidden)
2. Hidden CSS detection (display:none, visibility:hidden, font-size:0, color:transparent, off-screen positioning)
3. Zero-width unicode stripping (19 invisible character types)
4. HTML stripping (Floki-based semantic text extraction)
5. Size guard (configurable, default 10KB)
6. Pattern matching — 101 known injection phrases loaded from config/injection_patterns.json at runtime (sourced from NVIDIA Garak probe library). Updatable without recompilation.
7. Imperative tone heuristic — detects directive language (second-person pronouns + imperative verbs) to catch novel payloads not in the pattern list

Pre-LLM sanitization in web_browse and web_search — injection payloads stripped before the model sees them. Post-LLM auto-sanitization in the executor for all external skills.

Each stripped sentence is logged with its detection reason ([pattern], [imperative], [skill_mention]) for forensic analysis.

LLM Transform Prompt Scaffolds

New scaffold buttons for llm_transform steps: Summarize, Translate, Classify, Extract, Q&A, Rewrite, Filter — with matching config presets.

Documentation

12 documentation files updated across root docs and ReadTheDocs site.

---

Full changelog: v0.3.13...v0.3.14

v0.3.13 — MCP Server

MCP Server — Model Context Protocol Integration

AlexClaw now speaks MCP. External AI clients (Claude Code, Cursor, Claude Desktop) can discover and invoke all AlexClaw skills and workflows, and browse internal data stores — all through the standard Model Context Protocol.

New Features

MCP Tools (29 skills + 5 workflows)

• All registered skills exposed as skill:<name> tools
• All enabled workflows exposed as workflow:<name> tools
• Dynamic tool list refresh via PubSub when skills are loaded/unloaded
• Peri-compatible input schemas with per-skill config definitions

MCP Resources (6 URI templates)

• alexclaw://resources/{id} — RSS feeds, websites, documents, APIs
• alexclaw://knowledge/{id} — Knowledge base entries (supports search:query)
• alexclaw://memory/{id} — News items, facts, observations (supports search:query)
• alexclaw://workflows/{id} — Workflow definitions with steps
• alexclaw://runs/{id} — Workflow execution history
• alexclaw://config/{key} — Settings (sensitive values redacted)

Security

• Bearer token auth via mcp.api_key config (constant-time comparison)
• mcp_restriction policy rule type for blocking tools by name pattern
• PolicyEngine integration with :mcp caller type — full audit logging
• AuthContext extended with tool_name field and build_mcp/2 constructor

Observability

• /health now reports mcp: running/disabled
• /metrics includes MCP section (status, tools_registered)

Technical Details

• Built on anubis_mcp v1.0.0 (Streamable HTTP transport)
• Runtime plug forwarding avoids persistent_term race at boot
• Anubis Response builder for MCP-compliant tool results
• 855 tests, 0 failures
• 0 Giulia coding convention violations

New Modules

Module	Role
AlexClaw.MCP.Server	Anubis server — init, tool calls, resource reads, PubSub
AlexClaw.MCP.ToolSchema	Maps skills/workflows to MCP tool definitions
AlexClaw.MCP.ResourceProvider	Routes resource URIs to context modules
AlexClawWeb.Plugs.McpAuth	Bearer token validation
AlexClawWeb.Plugs.McpForward	Runtime forwarder to Anubis StreamableHTTP

v0.3.12 — Execution Outcome Annotation

What's New

Execution Outcome Annotation

• skill_outcomes table — every skill execution within a workflow is recorded with timing (duration_ms), truncated output snapshot (max 2KB), and metadata (branch taken, errors)
• /rate command — rate workflow outcomes from Telegram or Discord. Supports per-run or per-step rating with text shortcuts (+/-, up/down, yes/no) and emoji (👍/👎). Optional free-text feedback
• SkillAPI integration — skill_outcomes/3 and skill_outcome_stats/2 let skills query past execution outcomes as RAG context (requires :memory_read permission)
• Executor wiring — automatic timing and outcome recording after each step completes or fails

Foundation for

• Episodic memory — skills can learn from past execution quality
• Self-improvement loops — procedural memory via outcome-informed skill generation (planned)
• LLM output evaluator — soft failure detection using outcome data (planned)