feat(tool): add Forgejo built-in tool to the tool registry #2215

Open
opened 2026-04-03 09:35:47 +00:00 by freemo · 2 comments
Owner

Metadata

  • Branch: feature/forgejo-builtin-tool
  • Commit Message: feat(tool): add Forgejo built-in tool to the tool registry
  • Milestone: v3.2.0
  • Parent Epic: #374

Background and Context

CleverAgents currently supports MCP-sourced tools, Agent Skills tools, and custom Python tools registered via agents tool add. However, there is no first-class built-in tool for interacting with Forgejo (the project's self-hosted Git forge), despite the fact that many autonomous agent workflows — code review, issue triage, PR creation, branch management — require direct Forgejo API access.

Per the specification, tools are the atomic unit of execution and are registered in the Tool Registry with JSON Schema inputs/outputs, capability metadata (read_only, writes, checkpointable), and a four-stage lifecycle (discover / activate / execute / deactivate). Adding a Forgejo built-in tool follows the same pattern as the existing file and git operation built-ins (see feat(tool): add built-in file tools and feat(skill): add git operation skills).

Expected Behavior

A new built-in tool (or small suite of tools) is registered in the Tool Registry under the local/ namespace that exposes the most commonly needed Forgejo REST API operations to actors. Actors can then reference these tools in their skill definitions or actor YAML graphs to perform forge operations autonomously without requiring an external MCP server.

Acceptance Criteria

  • A ForgejoCient (or equivalent) abstraction is implemented in the infrastructure layer, wrapping the Forgejo REST API with proper authentication (PAT via config key).
  • At minimum, the following operations are exposed as individually registered tools:
    • forgejo/create_issue — create a new issue in a given repo
    • forgejo/list_issues — list open/closed issues with optional label/milestone filters
    • forgejo/get_issue — retrieve a single issue by number
    • forgejo/create_issue_comment — post a comment on an issue
    • forgejo/create_pull_request — open a pull request from a head branch to a base branch
    • forgejo/list_pull_requests — list open/closed PRs
    • forgejo/merge_pull_request — merge a PR using a specified merge style
    • forgejo/add_issue_labels — apply labels to an issue
    • forgejo/list_branches — list branches in a repository
    • forgejo/create_branch — create a new branch from a source ref
  • Each tool declares correct capability metadata: read_only is true for list/get operations; writes is true for create/merge/label operations; checkpointable is false for all (forge state is external).
  • Authentication is configured via a forge.forgejo.pat config key (never hardcoded).
  • A forgejo built-in skill is added that composes all Forgejo tools into a single reusable skill, following the pattern of the existing git skill.
  • All tools are covered by BDD (Behave) unit scenarios and Robot Framework integration tests.
  • Static type checking passes with no suppressions.
  • Coverage remains ≥ 97%.
  • All nox sessions pass.

Supporting Information

  • Specification: Tool abstraction — atomic unit of execution with JSON Schema I/O, capability metadata, and four-stage lifecycle.
  • Existing patterns: feat(tool): add built-in file tools (#276), feat(skill): add git operation skills (#300).
  • Forgejo REST API docs: https://git.cleverthis.com/api/swagger
  • Config key convention: follows forge.forgejo.pat pattern consistent with provider config keys.

Subtasks

  • Design ForgejoCient infrastructure class with PAT-based auth and base URL from config
  • Implement forgejo/create_issue tool with JSON Schema input/output
  • Implement forgejo/list_issues tool with JSON Schema input/output
  • Implement forgejo/get_issue tool with JSON Schema input/output
  • Implement forgejo/create_issue_comment tool with JSON Schema input/output
  • Implement forgejo/create_pull_request tool with JSON Schema input/output
  • Implement forgejo/list_pull_requests tool with JSON Schema input/output
  • Implement forgejo/merge_pull_request tool with JSON Schema input/output
  • Implement forgejo/add_issue_labels tool with JSON Schema input/output
  • Implement forgejo/list_branches tool with JSON Schema input/output
  • Implement forgejo/create_branch tool with JSON Schema input/output
  • Register all tools in the built-in tool registry with correct capability metadata
  • Add forge.forgejo.pat and forge.forgejo.base_url config keys with validation
  • Create forgejo built-in skill composing all Forgejo tools
  • Tests (Behave): Add BDD scenarios for each tool's happy path and error cases
  • Tests (Robot): Add integration smoke tests for Forgejo tool invocation
  • Verify coverage ≥ 97% via nox -s coverage_report
  • Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

  • All subtasks above are completed and checked off.
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (feat(tool): add Forgejo built-in tool to the tool registry), followed by a blank line, then additional lines providing relevant details about the implementation.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (feature/forgejo-builtin-tool).
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
  • All nox stages pass.
  • Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: Unknown | Agent: ca-new-issue-creator

## Metadata - **Branch**: `feature/forgejo-builtin-tool` - **Commit Message**: `feat(tool): add Forgejo built-in tool to the tool registry` - **Milestone**: v3.2.0 - **Parent Epic**: #374 ## Background and Context CleverAgents currently supports MCP-sourced tools, Agent Skills tools, and custom Python tools registered via `agents tool add`. However, there is no first-class built-in tool for interacting with **Forgejo** (the project's self-hosted Git forge), despite the fact that many autonomous agent workflows — code review, issue triage, PR creation, branch management — require direct Forgejo API access. Per the specification, tools are the *atomic unit of execution* and are registered in the Tool Registry with JSON Schema inputs/outputs, capability metadata (`read_only`, `writes`, `checkpointable`), and a four-stage lifecycle (`discover` / `activate` / `execute` / `deactivate`). Adding a Forgejo built-in tool follows the same pattern as the existing file and git operation built-ins (see `feat(tool): add built-in file tools` and `feat(skill): add git operation skills`). ## Expected Behavior A new built-in tool (or small suite of tools) is registered in the Tool Registry under the `local/` namespace that exposes the most commonly needed Forgejo REST API operations to actors. Actors can then reference these tools in their skill definitions or actor YAML graphs to perform forge operations autonomously without requiring an external MCP server. ## Acceptance Criteria - [ ] A `ForgejoCient` (or equivalent) abstraction is implemented in the infrastructure layer, wrapping the Forgejo REST API with proper authentication (PAT via config key). - [ ] At minimum, the following operations are exposed as individually registered tools: - `forgejo/create_issue` — create a new issue in a given repo - `forgejo/list_issues` — list open/closed issues with optional label/milestone filters - `forgejo/get_issue` — retrieve a single issue by number - `forgejo/create_issue_comment` — post a comment on an issue - `forgejo/create_pull_request` — open a pull request from a head branch to a base branch - `forgejo/list_pull_requests` — list open/closed PRs - `forgejo/merge_pull_request` — merge a PR using a specified merge style - `forgejo/add_issue_labels` — apply labels to an issue - `forgejo/list_branches` — list branches in a repository - `forgejo/create_branch` — create a new branch from a source ref - [ ] Each tool declares correct capability metadata: `read_only` is `true` for list/get operations; `writes` is `true` for create/merge/label operations; `checkpointable` is `false` for all (forge state is external). - [ ] Authentication is configured via a `forge.forgejo.pat` config key (never hardcoded). - [ ] A `forgejo` built-in skill is added that composes all Forgejo tools into a single reusable skill, following the pattern of the existing `git` skill. - [ ] All tools are covered by BDD (Behave) unit scenarios and Robot Framework integration tests. - [ ] Static type checking passes with no suppressions. - [ ] Coverage remains ≥ 97%. - [ ] All nox sessions pass. ## Supporting Information - Specification: Tool abstraction — atomic unit of execution with JSON Schema I/O, capability metadata, and four-stage lifecycle. - Existing patterns: `feat(tool): add built-in file tools` (#276), `feat(skill): add git operation skills` (#300). - Forgejo REST API docs: https://git.cleverthis.com/api/swagger - Config key convention: follows `forge.forgejo.pat` pattern consistent with provider config keys. ## Subtasks - [ ] Design `ForgejoCient` infrastructure class with PAT-based auth and base URL from config - [ ] Implement `forgejo/create_issue` tool with JSON Schema input/output - [ ] Implement `forgejo/list_issues` tool with JSON Schema input/output - [ ] Implement `forgejo/get_issue` tool with JSON Schema input/output - [ ] Implement `forgejo/create_issue_comment` tool with JSON Schema input/output - [ ] Implement `forgejo/create_pull_request` tool with JSON Schema input/output - [ ] Implement `forgejo/list_pull_requests` tool with JSON Schema input/output - [ ] Implement `forgejo/merge_pull_request` tool with JSON Schema input/output - [ ] Implement `forgejo/add_issue_labels` tool with JSON Schema input/output - [ ] Implement `forgejo/list_branches` tool with JSON Schema input/output - [ ] Implement `forgejo/create_branch` tool with JSON Schema input/output - [ ] Register all tools in the built-in tool registry with correct capability metadata - [ ] Add `forge.forgejo.pat` and `forge.forgejo.base_url` config keys with validation - [ ] Create `forgejo` built-in skill composing all Forgejo tools - [ ] Tests (Behave): Add BDD scenarios for each tool's happy path and error cases - [ ] Tests (Robot): Add integration smoke tests for Forgejo tool invocation - [ ] Verify coverage ≥ 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`feat(tool): add Forgejo built-in tool to the tool registry`), followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`feature/forgejo-builtin-tool`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: Unknown | Agent: ca-new-issue-creator
freemo added this to the v3.2.0 milestone 2026-04-03 09:36:19 +00:00
Author
Owner

Transition plan: State/Unverified -> State/Verified.

Preconditions: Pre-transition checks indicate no blockers (not Paused; no Blocked label). No other blockers identified.

Actions:

  • Removed: State/Unverified
  • Added: State/Verified

Current labels after transition (desired): Priority/Backlog, State/Verified, Type/Feature

Status: Preconditions passed. Label update steps prepared. If you want me to also perform the actual label edits via Forgejo REST API, I can attempt once an endpoint for label manipulation is available in this environment. This comment serves as an auditable record of the intended transition.


Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-state-updater

Transition plan: State/Unverified -> State/Verified. Preconditions: Pre-transition checks indicate no blockers (not Paused; no Blocked label). No other blockers identified. Actions: - Removed: State/Unverified - Added: State/Verified Current labels after transition (desired): Priority/Backlog, State/Verified, Type/Feature Status: Preconditions passed. Label update steps prepared. If you want me to also perform the actual label edits via Forgejo REST API, I can attempt once an endpoint for label manipulation is available in this environment. This comment serves as an auditable record of the intended transition. --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-state-updater
freemo modified the milestone from v3.2.0 to v3.7.0 2026-04-05 06:41:55 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: Medium — useful for autonomous agent workflows but not blocking any current milestone
  • Milestone: v3.7.0 (moved from v3.2.0) — this is a new feature for tool extensibility, not part of the Decisions + Validations scope. v3.7.0 (TUI Implementation) is the appropriate home since autonomous agent workflows that need Forgejo tools are a TUI/server-era concern
  • MoSCoW: Could Have — the spec defines the tool abstraction pattern but does not mandate a Forgejo-specific built-in tool; agents can use MCP-sourced Forgejo tools in the meantime
  • Parent Epic: #399 (Post-MVP Server & Clients)

Reassigned from v3.2.0 to v3.7.0 because this feature does not belong in the Decisions + Validations milestone. Dependency link to parent Epic created.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — useful for autonomous agent workflows but not blocking any current milestone - **Milestone**: v3.7.0 (moved from v3.2.0) — this is a new feature for tool extensibility, not part of the Decisions + Validations scope. v3.7.0 (TUI Implementation) is the appropriate home since autonomous agent workflows that need Forgejo tools are a TUI/server-era concern - **MoSCoW**: Could Have — the spec defines the tool abstraction pattern but does not mandate a Forgejo-specific built-in tool; agents can use MCP-sourced Forgejo tools in the meantime - **Parent Epic**: #399 (Post-MVP Server & Clients) Reassigned from v3.2.0 to v3.7.0 because this feature does not belong in the Decisions + Validations milestone. Dependency link to parent Epic created. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
Reference
cleveragents/cleveragents-core#2215
No description provided.