refactor: extract AppEvent to crates/ironclaw_common

[ilblackdragon]

Summary

• New crate crates/ironclaw_common with AppEvent (renamed from SseEvent) and truncate_preview — shared types/utils that were leaking from the web gateway into 12+ modules
• Rename SseEvent → AppEvent across 23 files — the enum was the app-wide event protocol, not a web transport concern
• from_sse_event() → from_app_event() on WsServerMessage
• Wire format unchanged — serde renames are on variants, not the enum name
• web/types.rs and web/util.rs re-export from ironclaw_common for backward compat within the gateway

Motivation

SseEvent was defined in src/channels/web/types.rs but imported by agent, orchestrator, worker, tools, extensions, and CLI modules. This coupling would block extracting the web gateway into its own crate. Moving the event type to a neutral shared crate decouples the event protocol from the transport.

Aligned with the event bus direction on refactor/architectural-hardening where DomainEvent (≡ AppEvent) is wrapped in a SystemEvent envelope with category-based sink routing.

Test plan

• cargo check — clean compile
• cargo clippy --all --benches --tests --examples --all-features — zero warnings
• cargo fmt -- --check — clean
• cargo test -p ironclaw_common — 11 tests pass (truncate_preview)
• cargo test -p ironclaw --lib -- channels::web — 127 gateway tests pass
• cargo test -p ironclaw --lib -- job_monitor — 9 tests pass
• Full cargo test suite — 3576+ tests pass, 0 failures

🤖 Generated with Claude Code

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request focuses on refactoring and enhancing the IronClaw application by introducing a common crate for shared types, improving LLM provider support, enhancing security, and improving the robustness of the system. The changes aim to decouple components, improve security, and provide a more flexible and reliable platform.

Highlights

• Code Sharing: Introduces a new ironclaw_common crate for sharing code between different parts of the application, reducing code duplication and improving maintainability.
• Event Handling: Renames SseEvent to AppEvent to better reflect its purpose as an application-wide event protocol, decoupling it from web-specific transport concerns.
• LLM Provider Support: Adds support for GitHub Copilot and Google Gemini LLM providers, enhancing the system's flexibility and integration capabilities.
• Security Enhancements: Improves security by preventing prompt injection vulnerabilities through the escaping of tool output and external content, and by validating base URLs.
• Robustness: Improves the reliability of the system by adding a mechanism to queue messages during agent processing, ensuring no messages are lost during high load.

Ignored Files

• Ignored by pattern: .github/workflows/** (2)
  • .github/workflows/e2e.yml
  • .github/workflows/regression-test-check.yml

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[ilblackdragon]

Addressed Copilot review in 3e8afb1: renamed leftover sse_event vars to app_event in orchestrator/api.rs and ws.rs, renamed test functions from test_ws_server_from_sse_* to test_ws_server_from_app_event_*, updated stale SSE comments.

[zmanian]

Review: refactor: extract AppEvent to crates/ironclaw_common

+500/-477 across 24 files

Issues (ranked by severity)

1. No Deserialize derive on AppEvent (Medium)
The new AppEvent only derives Serialize + Debug + Clone. The old SseEvent also only had Serialize, but now that AppEvent lives in a shared crate intended for reuse by other workspace members, downstream consumers (e.g. test harnesses, CLI tools, external integrations) will likely need to deserialize incoming events. Adding Deserialize now avoids a semver-ish breaking change to the shared crate later.

2. event_type() manually duplicates serde rename values (Medium)
The event_type() match arm strings must stay in sync with the #[serde(rename = "...")] attributes. If a variant is added and the developer forgets to update event_type(), the compiler won't catch it (the match is exhaustive on variants, but the string could be wrong). Consider deriving the event type string from serde metadata or adding a test that round-trips serialization and asserts event_type() matches the "type" field in the JSON output.

3. Stale variable/comment references to "SSE" remain (Low)
Several comments and at least one variable still reference "SSE" — e.g. src/channels/web/server.rs:1203 still says "Broadcast SSE event", and src/worker/job.rs doc comment was only partially updated. Copilot and Gemini already flagged specific instances. Not a functional issue, but undermines the refactor's goal of decoupling from SSE terminology.

4. truncate_preview moved but public API surface unchanged (Low)
The old crate::channels::web::util::truncate_preview is now a re-export of ironclaw_common::truncate_preview. This is clean, but the re-export means two import paths work — both the old path (via pub use) and the new ironclaw_common::truncate_preview. This is fine for backward compat, but consider deprecating the old path to guide callers toward the canonical import.

5. ironclaw_common crate uses edition = "2024" and rust-version = "1.92" (Nit)
Just confirming this is intentional and aligns with the workspace's MSRV. If the workspace targets an older MSRV, this could cause issues for contributors on older toolchains.

What's good

• Clean mechanical rename with zero semantic changes — the serde wire format is identical (same #[serde(rename)] values), so this is fully backward-compatible on the wire.
• The event_type() helper consolidates three duplicate match blocks (SSE, WS, types) into one, reducing ~70 lines of duplication.
• Tests were updated consistently across all 24 files.
• truncate_preview extraction with comprehensive unit tests in the new crate is solid.
• publish = false on the new crate prevents accidental crates.io publishing.

Verdict

Approve with suggestions — This is a clean, low-risk refactor. The wire format is unchanged, so there are no breaking changes for clients. The suggestions above (especially adding Deserialize and a round-trip test for event_type()) would strengthen the shared crate for future consumers but are not blockers.

[ilblackdragon]

Addressed zmanian's review in e0cad3b:

1. Deserialize on AppEvent — Added Deserialize derive so downstream consumers can deserialize events. ✅
2. Round-trip test for event_type() — event_type_matches_serde_type_field serializes every variant, parses the JSON "type" field, and asserts it matches event_type(). Catches drift between serde renames and the manual match. Also added round_trip_deserialize test. ✅
3. Stale SSE comments — Updated remaining "SSE" references in server.rs, manager.rs, ws_gateway_integration.rs, and worker/job.rs. ✅
4. Re-export deprecation — Rust doesn't support #[deprecated] on pub use re-exports. Both callers (session.rs, thread_ops.rs) already import from ironclaw_common directly, so the old path is only used within the web gateway itself. No action needed.
5. Edition/MSRV — Confirmed aligned with workspace (edition = "2024", rust-version = "1.92"). ✅

[Copilot]

Pull request overview

Copilot reviewed 23 out of 24 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

truncate_preview appends a closing </tool_output> tag whenever the input starts with <tool_output and the truncated result doesn’t end with the closing tag. Since the truncated result always ends with ..., this will always append on truncation, and it can still produce malformed XML if the truncation point lands inside the closing tag (leaving a partial </tool_... fragment) or if the string isn’t actually wrapped (closing tag appears earlier / extra trailing content). Consider tightening the condition to only run when the original is actually wrapped (e.g., s.starts_with(..) && s.trim_end().ends_with("</tool_output>")) and, when truncating, ensure end never falls within the final closing tag (clamp end to the start of the closing tag before adding ... and re-appending the full closing tag).

Suggested change

	// Walk backwards from max_bytes to find a valid char boundary
	let mut end = max_bytes;
	while end > 0 && !s.is_char_boundary(end) {
	end -= 1;
	}
	let mut result = format!("{}...", &s[..end]);
	// Re-close <tool_output> if truncation cut through the closing tag.
	if s.starts_with("<tool_output") && !result.ends_with("</tool_output>") {
	// Detect strings that are actually wrapped in a <tool_output>...</tool_output> pair.
	let is_wrapped_tool_output = s.starts_with("<tool_output")
	&& s.trim_end().ends_with("</tool_output>");
	let closing_tag = "</tool_output>";
	let closing_start = if is_wrapped_tool_output {
	s.rfind(closing_tag)
	} else {
	None
	};
	// Walk backwards from an initial end position to find a valid char boundary.
	// For wrapped <tool_output> strings, avoid truncating inside the closing tag
	// by clamping `end` to the start of the final `</tool_output>`.
	let mut end = max_bytes;
	if let Some(close_start) = closing_start {
	if end > close_start {
	end = close_start;
	}
	}
	while end > 0 && !s.is_char_boundary(end) {
	end -= 1;
	}
	let mut result = format!("{}...", &s[..end]);
	// Re-close <tool_output> if we truncated a string that was originally wrapped.
	if is_wrapped_tool_output {

[ilblackdragon]

Re: Copilot comment on truncate_preview tool_output edge case —

This is pre-existing behavior moved verbatim from src/channels/web/util.rs. The function was not modified in this PR, only relocated. The edge case (string starting with <tool_output but not actually wrapped) doesn't occur in practice — all callers pass actual tool output that's always properly wrapped.

Tightening the logic is a reasonable improvement but belongs in a separate PR to keep this refactor focused on the extraction.