Redesign routine create requests for LLMs

[henrypark133]

Summary

• redesign routine_create around a grouped request.kind canonical schema for LLMs
• keep legacy flat routine fields working through normalization and discovery-schema aliases
• add grouped routine trace coverage plus stronger routine persistence assertions

Testing

• RUSTFLAGS='-C debuginfo=0' CARGO_INCREMENTAL=0 CARGO_TARGET_DIR=/tmp/ironclaw-routine-request-target cargo test --lib parses_
• RUSTFLAGS='-C debuginfo=0' CARGO_INCREMENTAL=0 CARGO_TARGET_DIR=/tmp/ironclaw-routine-request-target cargo test --lib test_inline_schemas_for_complex_tools
• RUSTFLAGS='-C debuginfo=0' CARGO_INCREMENTAL=0 CARGO_TARGET_DIR=/tmp/ironclaw-routine-request-target cargo test --features libsql --test e2e_builtin_tool_coverage routine_
• RUSTFLAGS='-C debuginfo=0' CARGO_INCREMENTAL=0 CARGO_TARGET_DIR=/tmp/ironclaw-routine-request-target cargo test --features libsql --test e2e_advanced_traces routine_

[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 significantly refactors the internal representation and external API for creating routines, particularly for LLMs. The primary goal was to introduce a more structured and maintainable schema for routine requests, moving from a flat parameter list to a logically grouped one. This change improves clarity and extensibility for future routine enhancements, while carefully preserving compatibility with existing routine definitions through intelligent parsing and aliasing.

Highlights

• Routine Creation Schema Redesign: The routine_create request schema has been redesigned to use a grouped, canonical structure, organizing trigger, execution, delivery, and advanced settings into distinct nested objects.
• Backward Compatibility: Legacy flat routine fields are now supported through normalization and discovery-schema aliases, ensuring existing configurations continue to function without immediate modification.
• Enhanced Parsing Logic: New internal data structures and parsing functions were introduced to handle both the new grouped schema and the legacy flat schema, converting all incoming requests into a normalized internal representation.
• Updated Documentation and Tests: Workflow routine examples in documentation were updated to reflect the new schema, and comprehensive test cases were added to validate the parsing and functionality of both grouped and aliased requests.

Changelog

• skills/ironclaw-workflow-orchestrator/references/workflow-routines.md
  • Updated routine JSON examples to reflect the new grouped request, execution, and advanced fields.
• src/tools/builtin/routine.rs
  • Added HashMap, Map, and Value imports from serde_json.
  • Introduced new enum and struct definitions (NormalizedTriggerRequest, NormalizedExecutionMode, NormalizedExecutionRequest, NormalizedDeliveryRequest, NormalizedRoutineCreateRequest) to represent the normalized, grouped routine creation request.
  • Created helper functions (routine_request_properties, execution_properties, delivery_properties, advanced_properties) to generate JSON schema fragments for the new grouped fields.
  • Refactored routine_create_parameters_schema to generate a schema based on the new grouped structure and added routine_create_discovery_schema to include compatibility aliases for legacy flat fields.
  • Implemented utility functions (nested_object, string_field, bool_field, u64_field, string_array_field, object_field) for safely extracting and normalizing fields from JSON Value objects, supporting both grouped and aliased access.
  • Added validate_timezone_param and parse_system_event_filters for specific field validation and parsing.
  • Developed parse_routine_trigger, parse_execution_mode, parse_routine_execution, parse_routine_delivery, and parse_routine_create_request to convert raw JSON parameters into the new normalized routine request structures.
  • Created build_routine_trigger and build_routine_action to construct the internal Trigger and RoutineAction enums from the normalized request.
  • Updated the RoutineCreateTool::execute method to use the new parse_routine_create_request and build_routine_trigger/build_routine_action functions.
  • Modified RoutineUpdateTool::description to reflect broader update capabilities.
  • Refactored event_emit_schema to support canonical and aliased event_source fields, and updated event_emit_parameters_schema and added event_emit_discovery_schema accordingly.
  • Introduced parse_event_emit_args to handle event_emit parameters, supporting both event_source and source aliases.
  • Updated EventEmitTool::execute to utilize parse_event_emit_args.
  • Added extensive unit tests for parsing grouped and legacy routine creation requests, and for validating schema behavior with and without aliases.
• src/tools/schema_validator.rs
  • Updated the event_emit tool's schema reference to use the new event_emit_parameters_schema function.
• tests/e2e_builtin_tool_coverage.rs
  • Modified an existing test case to assert the prompt content within a Lightweight routine action.
  • Added a new end-to-end test routine_create_grouped to verify the creation of a routine using the new grouped schema for cron triggers, execution, and delivery settings.
  • Added a new end-to-end test routine_system_event_emit_grouped to confirm the successful creation of a system-event routine with grouped filters and its subsequent firing via event_emit.
• tests/fixtures/llm_traces/tools/routine_create_grouped.json
  • Added a new LLM trace fixture to simulate and test the routine_create tool with the new grouped parameter structure.
• tests/fixtures/llm_traces/tools/routine_system_event_emit_grouped.json
  • Added a new LLM trace fixture to simulate and test the routine_create and event_emit tools with grouped system event parameters.

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.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

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. ↩

[gemini-code-assist]

Code Review

This pull request introduces a significant and well-executed redesign of the routine_create tool, moving from a flat parameter structure to a more organized, grouped schema under request, execution, delivery, and advanced keys. The implementation thoughtfully maintains backward compatibility by supporting legacy flat fields as aliases, which is crucial for a smooth transition. The code is cleaner, more maintainable, and the addition of comprehensive tests for both the new schema and legacy compatibility is excellent. I have one minor suggestion to improve the clarity of a tool description.

[Copilot]

Pull request overview

This PR refactors the routine_create/event_emit built-in tool parameter schemas to support a grouped/nested request shape (while keeping legacy aliases for discovery), and adds new E2E coverage + fixtures demonstrating grouped routine creation and grouped system-event emission.

Changes:

• Refactor routine_create schema + parsing to prefer a grouped { request, execution, delivery, advanced } structure and add a separate discovery schema that retains legacy aliases.
• Refactor event_emit schema and parsing to prefer event_source, with a discovery-only source alias.
• Add new LLM trace fixtures and E2E tests covering grouped routine creation and firing grouped system-event routines.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/tools/builtin/routine.rs	Major refactor: new grouped schemas, normalization/parsing helpers, and discovery schemas for legacy alias compatibility.
src/tools/schema_validator.rs	Reuses the centralized event_emit parameter schema function in schema validator tests.
tests/e2e_builtin_tool_coverage.rs	Adds E2E tests for grouped routine_create and grouped system-event + event_emit behavior.
tests/fixtures/llm_traces/tools/routine_create_grouped.json	New trace fixture for grouped cron routine creation with delivery/advanced settings.
tests/fixtures/llm_traces/tools/routine_system_event_emit_grouped.json	New trace fixture for grouped system-event routine creation plus emitting a matching event.
skills/ironclaw-workflow-orchestrator/references/workflow-routines.md	Updates reference routine JSON examples to the new grouped shape and canonical event_source.

---

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

[henrypark133]

Addressed the valid review points in d8b8e79:

• tightened the compact schemas so routine_create now requires request and event_emit now requires canonical event_source
• kept backward compatibility in discovery schemas with alias-aware anyOf support
• constrained request.filters / event_filters to scalar values and now reject nested unsupported values instead of silently widening triggers
• clarified routine_update copy so it no longer suggests unsupported trigger edits
• updated the grouped event_emit trace fixture to prefer canonical event_source

Local verification passed:

• cargo fmt --all --check
• cargo clippy --all-targets --all-features -- -D warnings
• cargo test --lib tools::builtin::routine::tests::
• cargo test --lib test_inline_schemas_for_complex_tools
• cargo test --features libsql --test e2e_builtin_tool_coverage routine_
• cargo test --features libsql --test e2e_advanced_traces routine_

[Copilot]

Pull request overview

This PR updates the routine_create and event_emit built-in tools to support a new “grouped” request shape (nested request / execution / delivery / advanced objects) while keeping backward compatibility via parsing aliases and richer discovery schemas. It also adds E2E trace fixtures/tests and updates workflow documentation to the new format.

Changes:

• Refactor routine_create to accept grouped trigger/execution/delivery/advanced blocks, with legacy flat-field aliases supported in parsing and exposed via discovery_schema().
• Add event_emit schema + parsing support for a source alias in discovery while keeping event_source canonical in the compact parameters schema.
• Add new E2E coverage and fixtures for grouped routine creation and grouped system-event emission; update workflow routine docs accordingly.

Reviewed changes

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

Show a summary per file

File	Description
src/tools/builtin/routine.rs	Implements grouped schemas, parsing/normalization, and discovery schemas for routine_create and event_emit, plus expanded unit tests.
src/tools/schema_validator.rs	Reuses the centralized event_emit_parameters_schema() instead of inlining the schema.
tests/e2e_builtin_tool_coverage.rs	Adds E2E tests validating grouped routine_create flows and grouped system_event + event_emit behavior.
tests/fixtures/llm_traces/tools/routine_create_grouped.json	New trace fixture for grouped cron routine creation + routine listing.
tests/fixtures/llm_traces/tools/routine_system_event_emit_grouped.json	New trace fixture for grouped system-event routine creation + emitting a matching event.
skills/ironclaw-workflow-orchestrator/references/workflow-routines.md	Updates reference JSON examples to the grouped routine shape and canonical event_source for event_emit.

---

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

[zmanian]

LGTM. Clean redesign that genuinely improves LLM usability.

The grouped { request, execution, delivery, advanced } structure makes the discriminated-union nature of trigger types explicit. Backward compatibility via dual-schema approach (compact for validation, discovery with legacy aliases) is well-designed. CI is green, test coverage is solid (10 unit + 2 E2E).

Minor notes (non-blocking):

• Test helper wrappers (expect_ok, expect_some, etc.) add unnecessary indirection -- #[cfg(test)] code is already exempt from the no-unwrap rule
• Compact schema test only checks a subset of legacy aliases -- worth expanding for completeness

[henrypark133]

Addressed the two non-blocking review notes in 3a1f47b: removed the test-only helper wrappers and expanded the compact/discovery schema coverage to the full legacy alias set. cargo fmt --all --check and cargo clippy --all-targets --all-features -- -D warnings both pass.

[zmanian]

Review: Redesign routine create requests for LLMs

The redesign concept (grouping flat parameters into request, execution, advanced objects) is reasonable for LLM ergonomics, but CI is currently failing.

Blocking

1. CI failures

• "Code Style (fmt + clippy)" -- failing
• "No panics in production code" -- failing

These must be resolved before review of the code changes is meaningful. Please fix and push.

Preliminary observations (will review in depth after CI passes)

• The grouped schema (kind, source, event_type under request; mode under execution; cooldown_secs under advanced) is a cleaner LLM interface than flat parameters
• 1522 additions is large -- consider whether the skill reference doc changes can be a separate commit
• The zmanian review was dismissed, suggesting previous feedback exists -- please confirm prior items were addressed

Title check: accurate -- this is a schema redesign for LLM consumption.

[Copilot]

Pull request overview

Updates the routines tool API to support a new “grouped” request shape (nested request/execution/delivery/advanced objects) while keeping backward compatibility via discovery-schema aliases, and adds E2E fixtures/tests and documentation to cover the new shape.

Changes:

• Refactors routine_create and event_emit schemas to a grouped shape, adds parsing/normalization helpers, and exposes legacy fields as discovery-schema aliases.
• Adds new LLM trace fixtures and E2E coverage for grouped routine_create and grouped system_event + event_emit flows.
• Updates schema validation harness and workflow orchestrator reference docs to the new field names/shape.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/fixtures/llm_traces/tools/routine_system_event_emit_grouped.json	New fixture covering grouped system-event routine creation + emitting a matching event.
tests/fixtures/llm_traces/tools/routine_create_grouped.json	New fixture covering grouped cron routine creation with execution/delivery/advanced blocks.
tests/e2e_builtin_tool_coverage.rs	Adds new E2E tests that exercise grouped routine creation and grouped system-event emission.
src/tools/schema_validator.rs	Uses the centralized event_emit schema function in the schema sample list to avoid drift.
src/tools/builtin/routine.rs	Main refactor: grouped schemas + normalization/parsing, plus discovery schemas that retain legacy aliases.
skills/ironclaw-workflow-orchestrator/references/workflow-routines.md	Updates example routine configs and event_emit example to the new grouped/canonical fields.

---

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