fosm-rails-coding-agent 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a86e08a22e13276222b43f30f800f409ce3bfe8452c2ef9c51a7d3c1d8379b60
+  data.tar.gz: 8a0272687e4df3142c3cf229709ee10af544ac7d325822a5d9cc87bad936bc7a
+SHA512:
+  metadata.gz: 470c6fdb093d724f40f96aaabdd021842ba448c40b4a2b269544237cdc58fedac0355cedab53199b76b4b1c689bb89c64c308dc6b84903ad1742912c04bfd33b
+  data.tar.gz: fcd04b3eb16daf0116d5c7ef806daa701d0fd82422ca6fe8014f1ddb091f8cc27e0439f8734cac52fe40264810fa2d191779d42cd166667933689b685ebb7bb0

data/AGENTS.md

@@ -0,0 +1,77 @@
+# Agents Guide — fosm-rails-coding-agent
+
+Instructions for AI coding agents contributing to this codebase.
+
+## Project Structure
+
+```
+lib/fosm_rails_coding_agent.rb                        # Main entrypoint, FosmRailsCodingAgent.fosm_available?
+lib/fosm_rails_coding_agent/
+  version.rb                          # Gem version
+  configuration.rb                    # Configuration class (MCP + ACP settings)
+  transport.rb                        # MCP Streamable HTTP transport
+  middleware.rb                       # Rack middleware, tool registration
+  quiet_middleware.rb                 # Silence request log noise
+  exceptions_middleware.rb            # Inject exception context for agents
+  railtie.rb                          # Rails integration
+  acp_agent.rb                        # ACP agent (AgentClientProtocol)
+  tools/
+    base.rb                           # Base class < FastMcp::Tool
+    execute_sql.rb                    # SQL query tool
+    get_logs.rb                       # Log tail tool
+    project_eval.rb                   # Ruby eval tool
+    get_models.rb                     # ActiveRecord model lister
+    get_source_location.rb            # Source location finder
+    get_docs.rb                       # Documentation extractor
+    fosm/                             # FOSM-aware tools (conditional)
+      model_resolver.rb               # Shared model name resolution
+      list_lifecycles.rb              # List all FOSM lifecycles
+      inspect_lifecycle.rb            # Deep lifecycle introspection
+      fire_event.rb                   # Fire lifecycle events
+      transition_history.rb           # Audit trail
+      available_events.rb             # Current available events
+      why_blocked.rb                  # Diagnostic: why can't event fire
+bin/
+  fosm-coding-agent                   # ACP agent executable (stdio)
+```
+
+## Code Conventions
+
+- `frozen_string_literal: true` on every `.rb` file
+- One class per file, clear single responsibility
+- Ruby 3.1+ features where they improve clarity
+- Comment block on every class explaining what it does
+- No trailing whitespace
+- Tools follow the FastMcp::Tool DSL: `tool_name`, `description`, `arguments do`, `def call`
+
+## Key Design Decisions
+
+1. **FOSM tools are conditional** — only registered when `FosmRailsCodingAgent.fosm_available?` is true (checks `defined?(Fosm::Lifecycle)`)
+2. **All tools inherit from `FosmRailsCodingAgent::Tools::Base`** which inherits from `FastMcp::Tool`
+3. **FOSM tools live under `FosmRailsCodingAgent::Tools::Fosm` namespace** — the middleware filters by module ancestry
+4. **ACP agent pushes context proactively** — the `new_session` hook sends FOSM lifecycle summaries
+5. **Development only** — the Railtie raises if `config.enable_reloading` is false
+6. **ModelResolver mixin** — shared across all FOSM tools to resolve model names (direct, Fosm:: prefix, or Registry lookup)
+
+## Adding a New Tool
+
+1. Create `lib/fosm_rails_coding_agent/tools/your_tool.rb`
+2. Inherit from `FosmRailsCodingAgent::Tools::Base`
+3. Define `tool_name`, `description`, `arguments`, and `def call`
+4. The tool auto-registers via `Base.descendants` in the middleware
+
+For FOSM-specific tools, place under `lib/fosm_rails_coding_agent/tools/fosm/` and namespace under `FosmRailsCodingAgent::Tools::Fosm`.
+
+## Testing
+
+```
+bundle exec rake spec
+```
+
+## Dependencies
+
+- `rails >= 7.1` — framework integration
+- `fast-mcp ~> 1.6` — MCP server protocol
+- `rack >= 2.0` — middleware
+- `acp_ruby ~> 0.1` — Agent Client Protocol
+- `fosm-rails` — optional, for FOSM lifecycle introspection

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to fosm-rails-coding-agent will be documented in this file.
+
+## [0.0.1] - 2026-03-29
+
+### Added
+
+- Initial release
+- MCP server with core tools: execute_sql, get_logs, project_eval, get_models, get_source_location, get_docs
+- Conditional FOSM tools: fosm_list_lifecycles, fosm_inspect_lifecycle, fosm_fire_event, fosm_transition_history, fosm_available_events, fosm_why_blocked
+- ACP agent with proactive FOSM context push on session start
+- Rack middleware with localhost-only access control
+- Rails Railtie for automatic development environment setup
+- Exception interception middleware for agent-readable error context
+- Quiet middleware to suppress request logging

data/LICENSE

@@ -0,0 +1,127 @@
+# Functional Source License, Version 1.1, Apache 2.0 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 Abhishek Parolkar and INLOOP.STUDIO PTE LTD
+
+## Change Date
+
+Three years from the release date of each version of the Software and Content.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+Abhishek Parolkar, INLOOP.STUDIO PTE LTD, and their affiliated entities, the party offering the Software and Content under these Terms and Conditions.
+
+### Succession of Rights
+
+All rights, title and interest of Abhishek Parolkar ("Original Author") under
+this License — including but not limited to copyright ownership, the right to
+grant licenses, the right to enforce these Terms and Conditions, and the right
+to receive any royalties or consideration arising from the Software and
+Content — shall, upon the Original Author's death or permanent incapacity,
+pass to and vest in the Original Author's next-of-kin as determined by
+applicable law of succession. The next-of-kin shall hold and may exercise all
+such rights to the same extent as the Original Author, including the right to
+modify the terms of future releases.
+
+### The Software and Content
+
+The "Software and Content" refers to each version of the software, documentation, approaches, strategies, methodologies, and all other materials that we make available under these Terms and Conditions, as indicated by our inclusion of these Terms and Conditions with the Software and Content.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software and Content for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software and Content available to others in a commercial product or
+service that:
+
+1. substitutes for the Software and Content;
+
+2. substitutes for any other product or service we offer using the Software and Content
+   that exists as of the date we make the Software and Content available; or
+
+3. offers the same or substantially similar functionality as the Software and Content,
+   including making the Software and Content available as a hosted or managed service
+   (e.g., software-as-a-service, platform-as-a-service, or any other on-demand service)
+   where third parties access the functionality of the Software and Content.
+
+Permitted Purposes specifically include using the Software and Content:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software and Content in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software and Content infringes or contributes to
+the infringement of any patent, then your patent license to the Software and Content ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software and Content.
+
+If you redistribute any copies, modifications or derivatives of the Software and Content,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software and Content.
+
+### Disclaimer
+
+THE SOFTWARE AND CONTENT IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE AND CONTENT, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks and Domain Names
+
+Except for displaying the License Details and identifying us as the origin of
+the Software and Content, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+The name "FOSM-RAILS" is exclusive
+property of Abhishek Parolkar with unlimited license to INLOOP.STUDIO PTE LTD. No right or license is granted
+to use these names or domains in any manner whatsoever without the express written
+permission of Abhishek Parolkar. Any unauthorized use of these names or domains is
+strictly prohibited.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software and Content under
+the Apache License, Version 2.0 that is effective on the Change Date (as defined above —
+three years from the release date of each version of the Software and Content).
+On or after the Change Date, you may use the Software and Content under the Apache
+License, Version 2.0, in which case the following will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

data/README.md

@@ -0,0 +1,135 @@
+# fosm-rails-coding-agent
+
+**FOSM-aware runtime intelligence for Rails — MCP server + ACP agent for coding agents.**
+
+Gives coding agents (Claude Code, Codex, Copilot, OpenCode) runtime access to your Rails application: database queries, logs, code evaluation, and — when [fosm-rails](https://github.com/inloopstudio/fosm-rails) is present — deep introspection of FOSM lifecycle state machines, transitions, guards, and audit trails.
+
+## Architecture: MCP + ACP
+
+This gem exposes two complementary protocols:
+
+```
+┌─────────────────────────────────────────────────┐
+│              Rails Application                   │
+│                                                  │
+│  ┌──────────┐    ┌───────────────────────────┐  │
+│  │ fosm-rails│    │  fosm-rails-coding-agent  │  │
+│  │ lifecycles│◄──►│                           │  │
+│  └──────────┘    │  ┌─────────┐ ┌──────────┐ │  │
+│                  │  │MCP Tools│ │ACP Agent  │ │  │
+│                  │  │(pull)   │ │(push)     │ │  │
+│                  │  └────┬────┘ └─────┬─────┘ │  │
+│                  └───────┼────────────┼───────┘  │
+└──────────────────────────┼────────────┼──────────┘
+                           │            │
+                    ┌──────┴────────────┴───────┐
+                    │   Claude Code / Codex /    │
+                    │   Copilot / OpenCode       │
+                    └───────────────────────────┘
+```
+
+### MCP Server (pull-based)
+
+An MCP server embedded as Rack middleware at `/fosm-agent/mcp`. Coding agents query it on demand via standard MCP tool calls. Built on [fast-mcp](https://github.com/yjacquin/fast-mcp).
+
+### ACP Agent (push-based)
+
+An ACP agent (`bin/fosm-coding-agent`) that implements the [Agent Client Protocol](https://agentclientprotocol.com/). When a session starts, it proactively pushes FOSM lifecycle context — state definitions, events, guards, recent transitions — so the coding agent starts with full situational awareness.
+
+The most powerful developer tooling doesn't wait for agents to discover context through trial and error — it **pushes** the right context at the right time. When your coding agent opens a PR that touches an `Invoice` model, it should already know that `Invoice` has a lifecycle with states `draft → sent → paid`, a guard requiring line items before sending, and that the last three transitions were all `pay` events. MCP lets the agent pull when it needs to; ACP lets the application push when it knows the agent should care.
+
+Inspired by the thinking in [The future of coding agents is vertical integration](https://tidewave.ai/blog/the-future-of-coding-agents-is-vertical-integration).
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "fosm-rails-coding-agent"
+
+# Optional: for FOSM lifecycle introspection
+gem "fosm-rails"
+```
+
+Run:
+
+```
+bundle install
+```
+
+Auto-activates in development via its Railtie. No configuration needed for basic use.
+
+## Configuration
+
+In `config/environments/development.rb`:
+
+```ruby
+config.fosm_coding_agent.allow_remote_access   = false     # default: localhost only
+config.fosm_coding_agent.sql_row_limit         = 50        # max rows from execute_sql
+config.fosm_coding_agent.eval_timeout_ms       = 30_000    # project_eval timeout
+config.fosm_coding_agent.log_tail_default      = 100       # default log lines
+config.fosm_coding_agent.acp_enabled           = true      # enable ACP agent
+config.fosm_coding_agent.acp_push_fosm_context = true      # push FOSM context on session start
+```
+
+## MCP Tools
+
+### Core Tools (always available)
+
+| Tool | Description |
+|------|-------------|
+| `execute_sql` | Run SQL queries against the app database (50 row limit) |
+| `get_logs` | Tail the Rails log with optional regex filter |
+| `project_eval` | Evaluate Ruby code in the running app context |
+| `get_models` | List all ActiveRecord models with source locations |
+| `get_source_location` | Find source location of any Ruby constant/method |
+| `get_docs` | Extract documentation comments from source |
+
+### FOSM Tools (when fosm-rails is detected)
+
+| Tool | Description |
+|------|-------------|
+| `fosm_list_lifecycles` | List all FOSM lifecycle models with states/events |
+| `fosm_inspect_lifecycle` | Deep introspection of one lifecycle |
+| `fosm_fire_event` | Fire a lifecycle event (actor: :agent) |
+| `fosm_transition_history` | Audit trail for a FOSM record |
+| `fosm_available_events` | Events that can fire from current state |
+| `fosm_why_blocked` | Explain why an event can't fire |
+
+## ACP Agent
+
+The ACP agent runs as a subprocess over stdio:
+
+```
+fosm-coding-agent
+```
+
+Or point your ACP client at the binary:
+
+```json
+{
+  "agent": {
+    "command": "bundle",
+    "args": ["exec", "fosm-coding-agent"]
+  }
+}
+```
+
+## Philosophy
+
+Coding agents need **runtime intelligence**, not just static code analysis. A state machine definition in source code tells you the *structure*; runtime introspection tells you the *situation*.
+
+FOSM (Finite Object State Machine) is a paradigm where business entities have explicit, enforced lifecycles — with guards that explain why they block, transitions that log who did what, and access controls that make autonomous agent actions safe and auditable. This gem is the bridge between FOSM's runtime observability and the coding agents that need it.
+
+Read the FOSM paper: [Implementing Human+AI Collaboration Using Finite Object State Machine](https://www.parolkar.com/fosm)
+
+## Development
+
+```
+bundle install
+bundle exec rake spec
+```
+
+## License
+
+FSL-1.1-Apache-2.0 (Functional Source License, Version 1.1, Apache 2.0 Future License). See [LICENSE](LICENSE).

data/bin/fosm-coding-agent

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# FOSM Rails Coding Agent — ACP agent over stdio.
+# Spawned by ACP clients (Claude Code, Codex, etc.) to provide
+# FOSM-aware runtime intelligence for Rails applications.
+#
+# Usage: fosm-coding-agent
+
+require "bundler/setup" if File.exist?(File.expand_path("../../Gemfile", __FILE__))
+require "fosm_rails_coding_agent"
+require "fosm_rails_coding_agent/acp_agent"
+
+AgentClientProtocol.run_agent(FosmRailsCodingAgent::AcpAgent.new)

data/lib/fosm_rails_coding_agent/acp_agent.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "agent_client_protocol"
+require "json"
+require "securerandom"
+
+module FosmRailsCodingAgent
+  # ACP agent that implements the Agent Client Protocol.
+  # Provides push-based FOSM lifecycle context to coding agents.
+  #
+  # When a session starts, the agent proactively pushes:
+  # - All FOSM lifecycle definitions in the project
+  # - Available events for key records
+  # - Recent transition activity
+  #
+  # This is the José Valim insight: don't wait for the agent to ask,
+  # PUSH context so the coding agent starts with full situational awareness.
+  class AcpAgent
+    include AgentClientProtocol::AgentInterface
+    include AgentClientProtocol::Helpers
+
+    def on_connect(conn)
+      @conn = conn
+    end
+
+    def initialize_agent(protocol_version:, **)
+      AgentClientProtocol::Schema::InitializeResponse.new(
+        protocol_version: AgentClientProtocol::PROTOCOL_VERSION,
+        agent_info: AgentClientProtocol::Schema::Implementation.new(
+          name: "fosm-rails-coding-agent",
+          version: FosmRailsCodingAgent::VERSION
+        ),
+        capabilities: AgentClientProtocol::Schema::AgentCapabilities.new
+      )
+    end
+
+    def new_session(cwd:, **)
+      session_id = "fosm-agent-#{SecureRandom.uuid}"
+
+      # Proactively push FOSM context if available
+      push_fosm_context(session_id) if FosmRailsCodingAgent.fosm_available?
+
+      AgentClientProtocol::Schema::NewSessionResponse.new(
+        session_id: session_id
+      )
+    end
+
+    def prompt(prompt:, session_id:, **)
+      prompt.each do |block|
+        text = case block
+               when AgentClientProtocol::Schema::TextContent then block.text
+               when Hash then block["text"] || block.inspect
+               else block.inspect
+               end
+
+        response = handle_prompt_text(text, session_id)
+
+        @conn.session_update(
+          session_id: session_id,
+          update: update_agent_message_text(response)
+        )
+      end
+
+      AgentClientProtocol::Schema::PromptResponse.new(
+        stop_reason: AgentClientProtocol::Schema::StopReason::END_TURN
+      )
+    end
+
+    def authenticate(method_id:, **)
+      AgentClientProtocol::Schema::AuthenticateResponse.new
+    end
+
+    private
+
+    # Push FOSM lifecycle context at session start so the coding agent
+    # has full awareness of the state machines in the project.
+    def push_fosm_context(session_id)
+      context = build_fosm_context
+      return if context.empty?
+
+      @conn.session_update(
+        session_id: session_id,
+        update: update_agent_message_text(
+          "## FOSM Lifecycle Context\n\n" \
+          "This Rails application uses FOSM (Finite Observable State Machine) " \
+          "lifecycles. Here are the registered state machines:\n\n#{context}"
+        )
+      )
+    end
+
+    def build_fosm_context
+      return "" unless defined?(::Fosm::Registry)
+
+      models = ::Fosm::Registry.model_classes
+      return "" if models.empty?
+
+      models.filter_map do |klass|
+        lifecycle = klass.fosm_lifecycle
+        next unless lifecycle
+
+        states = lifecycle.states.map do |s|
+          label = s.name.to_s
+          label += " (initial)" if s.initial?
+          label += " (terminal)" if s.terminal?
+          label
+        end
+
+        events = lifecycle.events.map do |e|
+          "  #{e.name}: #{e.from_states.join(", ")} → #{e.to_state}"
+        end
+
+        "### #{klass.name}\n" \
+        "States: #{states.join(", ")}\n" \
+        "Events:\n#{events.join("\n")}\n"
+      end.join("\n")
+    end
+
+    def handle_prompt_text(text, session_id)
+      case text.downcase.strip
+      when /lifecycles?/
+        build_fosm_context.presence || "No FOSM lifecycles found in this project."
+      when /help/
+        "FosmRailsCodingAgent ACP agent provides FOSM-aware runtime intelligence.\n" \
+        "FOSM tools are available via the MCP server at /fosm-agent/mcp.\n" \
+        "Ask about lifecycles, states, events, or transitions."
+      else
+        "FosmRailsCodingAgent is listening. Use the MCP tools at /fosm-agent/mcp for " \
+        "SQL queries, logs, code evaluation, and FOSM introspection."
+      end
+    end
+  end
+end

data/lib/fosm_rails_coding_agent/configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module FosmRailsCodingAgent
+  # Central configuration for FosmRailsCodingAgent's MCP server and ACP agent.
+  # Set via config.fosm_coding_agent in your Rails application.
+  class Configuration
+    attr_accessor :logger,
+                  :allow_remote_access,
+                  :sql_row_limit,
+                  :eval_timeout_ms,
+                  :log_tail_default,
+                  :acp_enabled,
+                  :acp_agent_name,
+                  :acp_push_fosm_context
+
+    def initialize
+      @logger              = nil
+      @allow_remote_access = false
+      @sql_row_limit       = 50
+      @eval_timeout_ms     = 30_000
+      @log_tail_default    = 100
+      @acp_enabled         = true
+      @acp_agent_name      = "fosm-rails-coding-agent"
+      @acp_push_fosm_context = true
+    end
+  end
+end

data/lib/fosm_rails_coding_agent/exceptions_middleware.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module FosmRailsCodingAgent
+  # Intercepts Rails exception pages and injects structured error context
+  # as a hidden textarea — coding agents can parse this to understand
+  # stacktraces, controller context, and request metadata.
+  class ExceptionsMiddleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      request = ActionDispatch::Request.new(env)
+      status, headers, body = @app.call(env)
+
+      if (exception = request.get_header("fosm_agent.exception"))
+        formatted = format_exception(exception, request)
+        body, headers = inject_into_body(body, headers, formatted)
+      end
+
+      [status, headers, body]
+    rescue => error
+      Rails.logger.error("[FosmRailsCodingAgent] ExceptionsMiddleware failure: #{error.message}")
+      raise
+    end
+
+    private
+
+    def format_exception(exception, request)
+      backtrace  = Rails.backtrace_cleaner.clean(exception.backtrace)
+      params     = safe_params(request)
+      controller = params["controller"]&.camelize
+      action     = params["action"]
+
+      text = exception.class.name.dup
+      text << " in #{controller}Controller" if controller
+      text << "##{action}" if action
+      text << "\n\n## Message\n\n#{exception.message}"
+      text << "\n\n## Backtrace\n\n#{backtrace.join("\n")}" if backtrace.any?
+      text << "\n\n## Request\n\n  * URI: #{request.base_url}#{request.path}"
+      text << "\n  * Query: #{request.query_string}"
+
+      %(<textarea style="display:none;" data-fosm-agent-exception>#{ERB::Util.html_escape(text)}</textarea>)
+    end
+
+    def safe_params(request)
+      request.parameters
+    rescue ActionController::BadRequest
+      {}
+    end
+
+    def inject_into_body(body, headers, content)
+      html = "".dup
+      body.each { |part| html << part }
+      body.close if body.respond_to?(:close)
+
+      if (pos = html.rindex("</body>"))
+        html.insert(pos, content)
+      else
+        html << content
+      end
+
+      headers[Rack::CONTENT_LENGTH] = html.bytesize.to_s if headers[Rack::CONTENT_LENGTH]
+      [[html], headers]
+    end
+  end
+end