ForgeBook 1.0.7

Fixes from 1.0.6 playtest

/forgebook item was always returning RATE_LIMITED

The RAG pipeline was re-calling Authorizer.authorize in the off-tick executor after the tick-thread authorize had already consumed a token — so every /forgebook item spent two tokens for one request. The 1.0.6 burst cap made this fatal (bucket only held one token). Fixed — the off-tick re-check now skips the rate-limit step, still re-checks kill switch + OP gate.

Reverted the burst=1 cap from 1.0.6

Per-player burst cap doesn't actually solve Anthropic's org-level 10k-tokens-per-minute limit — a single player can still spend the full budget over a minute, just spaced out. The cap just made ergonomics worse. Back to the original capacity = max(1, rpm) semantics. A proper global TPM budget is the right fix and is tracked for a later release.

Tactical heading color

Replies now color headings only (gold + bold) instead of the 1.0.6 full-aqua-wash. Body text / bold / italic stay at Minecraft's default white so the readability balance is back.

Install

Drop forgebook-1.0.7.jar into both the client and server mods/ folders. Requires Minecraft 1.20.1 + Forge 47.4.18+.

ForgeBook 1.0.6

Three UX fixes

1. Loading messages on slash commands

/forgebook ask and /forgebook item now send ForgeBook is thinking… the moment the command is accepted, so you know the request is in flight instead of staring at silent chat for 5-15s while the model runs. The in-inventory chat UI already had an equivalent indicator — commands now match.

2. Cleaner, colored replies

Replies are piped through a markdown → Minecraft §-code converter before being sent to chat:

• **bold**, *italic*, _italic_, __underline__, ~~strike~~, `code`, ``` fences ``` — all render as real formatting instead of leaking raw asterisks / underscores.
• [text](url) renders as text (url).
• # Heading → bold; - bullet → • bullet.
• The whole reply is aqua so it's visually distinct from vanilla system text.

3. Rate-limit burst cap

RateLimiter now caps per-player burst at 1 token regardless of rate_limit_per_minute, while preserving the configured refill rate (one token every 60/rpm seconds). Reason: Anthropic's org-level input-token-per-minute limit is easy to blow with a rapid-fire burst — each ForgeBook request spends ~2-3k tokens on the system prompt + context, and a burst of 30 requests-per-minute in one second blows the 10k TPM budget. Sustained throughput over a full minute is unchanged.

Install

Drop forgebook-1.0.6.jar into both the client and server mods/ folders. Requires Minecraft 1.20.1 + Forge 47.4.18+. See docs/BUILD-AND-INSTALL.md.

ForgeBook 1.0.5

Fix

v1.0.4 crashed with NoClassDefFoundError: org.jsoup.Jsoup the first time the agent actually reached fetch_mod_docs_page — a bug that had been latent in every prior release but was masked by the 429 rate-limit issues 1.0.4 just fixed.

Root cause: the build relocated jsoup's bytecode to `com.forgebook.shadow.jsoup.`, but our own source (`ModDocsScraper`, `DuckDuckGoHtmlAdapter`) imported `org.jsoup.` — and the compiled call sites were never rewritten. The jar therefore shipped with classes only under the relocated package, leaving every jsoup call a `ClassNotFoundException` waiting to happen.

Fix: drop the relocation. Merge jsoup's classes into the mod jar under their original `org.jsoup.*` package so runtime matches compile time. Verified in the built jar:
```
jar tf forgebook-1.0.5.jar | grep org/jsoup/Jsoup.class
```

Docs (README, THIRD_PARTY_NOTICES, BUILD-AND-INSTALL, RELEASE-SMOKE) updated to reflect the new packaging.

Tests

365/365 passing.

ForgeBook 1.0.4

Fixes

Token-budget crunch (primary)

v1.0.3 dispatched ~16k input tokens per /forgebook ask or chat-UI call against Anthropic's 10,000 input-tokens/minute organization rate limit, so a single call often tripped a 429 and a second call in the same minute was guaranteed to fail. Five sub-fixes cut per-request size:

• System prompt mod list: now a comma-separated list of modIds (~15 ch/mod) instead of per-mod name/url rows (~100 ch/mod). For a 200-mod pack this saves ~16 kB per turn (~4k tokens). Biggest single win.
• Tool descriptions + schemas: trimmed to one-liners; per-property prose dropped. Another ~1 kB per request body.
• web_search: default limit 5→3, max 10→5, tool_result body hard-capped at 2,000 chars. Keeps turn-2+ request size bounded since tool_result blocks get replayed in the agent loop.

429 latency (interactive budget)

• ClaudeProvider now fast-fails on 429 when the retry-after hint exceeds the 10s interactive budget — the old code would block the worker thread up to maxDelay and almost always retry into a second 429.
• RetryPolicy maxDelay raised 5s → 10s so short retry-after hints (7-8s after a brief burst) are respected verbatim instead of being over-clamped.

/forgebook item silent failure

• RagItemPipeline + CurseForgeClient: CF API failure paths promoted DEBUG→WARN/INFO. Prior silent swallowing made v1.0.3 /forgebook item failures invisible at the default log level.

Tests

365/365 passing. Updated: RetryPolicyTest#6 (10s cap), SystemPromptBuilderTest (modId-only format).

ForgeBook v1.0.3

What's new in 1.0.3

Structured request-trace logging. Every stage of a ForgeBook request now emits one INFO-level line keyed by the invoking player's UUID, so a single request can be reconstructed end-to-end by grepping the server log for that UUID.

No user message content is ever logged — only metadata, lengths, tool names, outcomes, and latencies (SAFE-04 preserved).

Lifecycle coverage

• Chat UI — chat request / chat denied / chat reply / chat error
• /forgebook ask — ask request / ask denied / ask reply / ask error
• /forgebook item —
  • item request (modId, itemId, modURL, held-context hash)
  • rag denied / rag no_doc_url / rag resolved_via_web_search / rag docs_cache_hit
  • rag fetch uuid=… source=cf_api|safe_http … + rag fetch_ok / rag fetch_miss
  • rag reply (tokens + latency) / rag error
• Shared downstream —
  • dispatch start / dispatch reply / dispatch error (tokens + latency)
  • agent iter=N/M outcome=FinalReply|ToolUses|ProviderError tools=[…] + per-tool tool <name> ok
  • anthropic request / anthropic response status=… (retries logged) / anthropic io_error
  • safehttp fetch start / safehttp redirect / safehttp fetch ok (status, bytes, content-type, latency)

Fix

Null-guarded senderUuid in ChatRequestHandler so the authorizer path still logs cleanly when the sender is absent.

Compatibility

• Minecraft 1.20.1 / Forge 47.4.18
• No config changes. No breaking changes.

Full changelog: v1.0.2...v1.0.3

ForgeBook v1.0.2

ForgeBook v1.0.2

Bug-fix + reliability release. Replaces the previous v1.0.2 cut (which shipped only the SafeHttpFetcher rewrite).

What changed since v1.0.1

1. SafeHttpFetcher — no more IP-pinning
The original v1.0.0 fetcher pinned the HTTPS connection to a DNS-resolved IP literal with a custom HostnameVerifier. That interacted badly with the JDK's URL-spoofing check and every handshake died with HTTPS hostname wrong: should be <…>. SafeHttpFetcher now delegates TLS to the JDK defaults and enforces SSRF protections (private-IP block, redirect cap, 1 MB body cap, https-only) without fiddling with the handshake.

2. /forgebook item now works on CurseForge-hosted mods
Most mod displayURLs in mods.toml point at https://www.curseforge.com/minecraft/mc-mods/<slug>. CurseForge returns HTTP 403 to the SafeHttpFetcher user-agent, so /forgebook item used to always fail for CurseForge-hosted mods with "Could not fetch mod documentation."

When curseforge_api_key is set in the server config, the RAG pipeline now resolves the slug from the URL path and hits /v1/mods/search + /v1/mods/{id}/description instead — same HTML content, authenticated channel, no 403. On any failure (missing key, non-200, no search hit) the pipeline falls back to the existing SafeHttpFetcher path so non-CurseForge hosts (Fandom, Read the Docs, GitHub wikis) keep working.

3. Chat UI — empty-state hint no longer overflows
The "Ask about a mod, an item, or what you're looking at." placeholder was drawn as a single line and clipped the panel edges on narrow inventory-docked layouts. Now word-wraps and centers each line.

Operator action (optional)

To enable the CurseForge REST path, set curseforge_api_key in config/forgebook-server.toml. Apply for a key at console.curseforge.com. If left blank, /forgebook item behaves exactly as in v1.0.1 — direct HTML fetch only.

Install

Drop forgebook-1.0.2.jar in mods/. Forge 1.20.1-47.4.10 or later.

ForgeBook v1.0.1

ForgeBook v1.0.1

First hotfix release after v1.0.0. Targets the two biggest pain points from real-world install feedback: documentation discovery (most mods leave displayURL empty) and interactive-chat latency (single-digit seconds, not minutes).

What got fixed

Docs discovery

• /forgebook item now falls back to scanning the mod description and credits for a URL when displayURL is empty in mods.toml — since most mod authors put their wiki links in the description free-text field. Social links (Discord/Twitter/Patreon/etc.) are filtered out. Preference order: github / *.fandom.com / wiki / docs hosts.
• When all three URL tiers come up empty and enable_web_search = true, the pipeline now does a single web search to find a candidate URL before giving up. Skips obvious-junk domains.

Speed — target was 10–30s per query

• Claude request timeout: 60s → 30s
• Retry count: 3 → 1 (worst-case latency on a failing call went from ~240s to ~65s)
• max_tokens for /forgebook item: capped at 400 (Haiku finishes a ~400-token response in about 8s vs 20s+ for 1024)
• Scraped-doc truncation for RAG path: 8000 → 3000 chars (smaller prompt, faster TTFT)
• Docs-cache per URL: second-through-Nth query against the same mod skips fetch+parse entirely
• Agent loop iteration cap: 6 → 3 (bounds interactive chat latency)
• Default rate_limit_per_minute: 5 → 30 (5/min choked chat UI after five messages)

Chat UI bugs from v1.0.0

• Chat panel left-pinned, no parent re-render — fixes player model and item tooltips bleeding through the chat overlay
• Markdown → Minecraft §-codes on client side — **bold**, *italic*, # headings, - bullets, `code`, [link](url) all render inline instead of as raw syntax

Infrastructure

• DuckDuckGo search backend: routed through plain HttpClient instead of SafeHttpFetcher (fixes HTTPS hostname wrong TLS handshake failures — SafeHttpFetchers SNI workaround was designed for HttpsURLConnection and does not work with java.net.http.HttpClient). Brave backend untouched (already worked).
• Server config moved from ModConfig.Type.SERVER to COMMON (so the file lives at config/forgebook-server.toml, persists across restarts, and is not synced over the network to clients at login)
• Stripped jsoup META-INF/** noise from the main jar (fixes resource-pack breakage when ForgeBook is installed in a modpack)

Install / upgrade

Drop forgebook-1.0.1.jar into mods/ on both client and server, replacing forgebook-1.0.0.jar.

If you had rate-limit issues on v1.0.0: either /op <yourname> (OPs bypass entirely) or edit config/forgebook-server.toml and bump rate_limit_per_minute = 30 (existing installs keep the value from their v1.0.0 config; only new installs get the new default).

See docs/BUILD-AND-INSTALL.md for full setup.

Requirements (unchanged)

• Minecraft 1.20.1
• Forge 1.20.1-47.4.18 or newer 47.x
• Java 17
• Anthropic API key (server-side; console.anthropic.com)

License

MIT. See LICENSE and THIRD_PARTY_NOTICES.md.

— Nick Doxa

ForgeBook v1.0.0

ForgeBook v1.0.0 — first public release

AI-grounded item + mod documentation inside Minecraft. Hold an unfamiliar item, ask what it does, get a cited answer without leaving the game.

Features

• /forgebook item — held-item or argument-form AI lookup with source citation
• /forgebook ask — single-turn chat from the command line
• In-inventory docked chat UI (left-pinned panel) with per-session conversation and loading/error states
• Grounded tool-using agent loop with mod-docs scraping, web search, and CurseForge enrichment
• Claude provider by default; OpenAI + Ollama are selectable stubs for future contributions
• Safety: server-side-only API keys, SSRF-safe fetcher, per-player rate limiting, OP-only default, kill switch, audit logging

Install

Drop forgebook-1.0.0.jar into your Forge 1.20.1-47.4.18 mods/ folder on both client and server.

Server owners: on first start a config/forgebook-server.toml file is generated. Edit it to set ai_api_key = "sk-ant-..." (get one from console.anthropic.com), then either restart or run /forgebook reload in-game as an OP.

Full setup guide: docs/BUILD-AND-INSTALL.md.

Compatibility

Tested clean against JEI, REI, Embeddium, Oculus, Jade, Mouse Tweaks, Quark, Inventory HUD+ — see docs/COMPATIBILITY.md.

Requirements

• Minecraft 1.20.1
• Forge 1.20.1-47.4.18 or newer 47.x
• Java 17
• Anthropic API key (server-side; console.anthropic.com)

License

MIT. See LICENSE and THIRD_PARTY_NOTICES.md.

— Nick Doxa