textus 0.54.0 → 0.54.1

data/lib/textus/surfaces/mcp/catalog.rb

@@ -1,11 +1,10 @@
 module Textus
   module Surfaces
     module MCP
-      # Derives the entire MCP tool surface from the per-verb contracts
-      # (ADR 0039). `tool_schemas` feeds tools/list; `call` is the generic
-      # tools/call dispatch: map JSON args -> (positional, keyword) per the
-      # contract, invoke the verb through the role scope, then shape the
-      # return value with the contract's default view. No per-tool code.
+      # Derives the entire MCP tool surface from the per-verb contracts (ADR 0039).
+      # `build_tools` builds MCP::Tool instances for the SDK; `call` is the generic
+      # dispatch: map JSON args -> (positional, keyword) per the contract, invoke
+      # the verb through the role scope, then shape the return value. No per-tool code.
       module Catalog
         module_function
 
@@ -24,14 +23,27 @@ module Textus
                                .map(&:contract)
         end
 
-        def tool_schemas
-          specs.map do |s|
-            { name: s.verb.to_s, description: s.summary, inputSchema: s.input_schema }
-          end.freeze
+        # Builds MCP::Tool instances for the SDK, bound to mcp_server.dispatch.
+        def build_tools(mcp_server)
+          Textus::Action::VERBS
+            .select { |_, klass| mcp_surfaced?(klass) }
+            .map do |name, action|
+              schema = action.contract.input_schema
+              schema = schema.reject { |k, v| k == :required && Array(v).empty? }
+              ::MCP::Tool.define(
+                name: name.to_s,
+                description: action.contract.summary,
+                input_schema: schema,
+              ) do |server_context:, **args|
+                mcp_server.dispatch(name, args, server_context)
+              end
+            end
         end
 
         def names
-          specs.map { |s| s.verb.to_s }
+          Textus::Action::VERBS
+            .select { |_, klass| mcp_surfaced?(klass) }
+            .keys.map(&:to_s)
         end
 
         # MCP-surfaced read verbs, by Dispatcher class namespace — the agent's

data/lib/textus/surfaces/mcp/server.rb

@@ -1,161 +1,108 @@
-require "json"
-require_relative "routing"
+# frozen_string_literal: true
+
+require "mcp"
 
 module Textus
   module Surfaces
     module MCP
-      # Stdio JSON-RPC 2.0 server speaking MCP draft 2024-11-05. One line per
-      # message (NDJSON). Holds a single Session for the lifetime of stdin.
+      # MCP stdio server backed by the official mcp gem. The SDK owns protocol
+      # negotiation, tool dispatch, and JSON-RPC framing. This class owns the
+      # textus Session lifecycle (built lazily on first tool call) and delegates
+      # execution to Catalog.
       class Server
-        include Routing
-
-        PROTOCOL_VERSION = "2024-11-05"
-        SERVER_INFO      = { "name" => "textus", "version" => Textus::VERSION }.freeze
-        MAX_LINE_BYTES   = 1_048_576 # 1 MB — protects against OOM from oversized tool calls
-
-        def initialize(store:, stdin: $stdin, stdout: $stdout, role: Textus::Role::DEFAULT)
-          @store   = store
-          @stdin   = stdin
-          @stdout  = stdout
-          @role    = role
-          @session = nil
-        end
-
-        def run
-          @stdin.each_line do |line|
-            line = line.strip
-            next if line.empty?
-
-            handle_line(line)
-          end
-        end
-
-        private
-
-        def handle_line(line)
-          return reject_oversized(line) if line.bytesize > MAX_LINE_BYTES
-
-          parse_and_dispatch(line)
-        end
-
-        def reject_oversized(line)
-          emit_error(nil, -32_700, "message too large (#{line.bytesize} bytes, limit #{MAX_LINE_BYTES})")
-        end
-
-        def parse_and_dispatch(line)
-          dispatch(JSON.parse(line))
-        rescue JSON::ParserError => e
-          emit_error(nil, -32_700, "parse error: #{e.message}")
-        end
-
-        def handle_initialize(rid, _params)
-          @session = build_session
-          emit_result(rid, {
-                        "protocolVersion" => PROTOCOL_VERSION,
-                        "serverInfo" => SERVER_INFO,
-                        "capabilities" => { "tools" => {}, "resources" => {} },
-                      })
-        end
-
-        def build_session
-          # The acting role IS the resolved connection role (ADR 0040): the MCP
-          # transport defaults to `agent`, which can write the queue, so its
-          # propose_lane resolves directly. If a connection's role cannot propose,
-          # propose_lane is nil and the `propose` tool reports that honestly.
-          Session.new(
+        def initialize(store:, role: Textus::Role::DEFAULT, stdin: $stdin, stdout: $stdout)
+          @store  = store
+          @role   = role
+          @stdin  = stdin
+          @stdout = stdout
+          # Session built eagerly so the contract_etag is captured at server start.
+          # Changes to manifest/hooks/schemas after this point are detected as drift.
+          @session = Textus::Session.new(
             role: @role,
             cursor: @store.audit_log.latest_seq,
             propose_lane: @store.manifest.policy.propose_lane_for(@role),
-            contract_etag: contract_etag,
+            contract_etag: contract_etag_now,
           )
-        end
-
-        def handle_tools_list(rid)
-          emit_result(rid, { "tools" => Catalog.tool_schemas })
-        end
-
-        def handle_tools_call(rid, params)
-          return unless session_ready?(rid)
 
-          invoke_tool(rid, params["name"], params["arguments"] || {})
-        rescue Textus::ContractDrift, CursorExpired, ToolError => e
-          emit_error(rid, e.class::JSONRPC_CODE, e.message)
-        rescue StandardError => e
-          emit_error(rid, -32_603, "internal: #{e.class}: #{e.message}")
+          @sdk = ::MCP::Server.new(
+            name: "textus",
+            version: Textus::VERSION,
+            tools: Catalog.build_tools(self),
+            resources: build_resources,
+            server_context: { mcp_server: self },
+          )
+          @sdk.resources_read_handler { |params, server_context:| handle_resource_read(params[:uri].to_s, server_context) }
         end
 
-        def session_ready?(rid)
-          return true if @session
+        # Runs the stdio line loop; delegates each JSON line to the SDK.
+        def run
+          @stdin.each_line do |line|
+            line = line.strip
+            next if line.empty?
 
-          emit_error(rid, -32_002, "session not initialized; call 'initialize' first")
-          false
-        end
+            response = @sdk.handle_json(line)
+            next unless response
 
-        def invoke_tool(rid, name, args)
-          # ADR 0083: contract-drift guard gates mutating verbs only
-          @session.check_etag!(contract_etag) unless Catalog.read_verbs.include?(name)
-          result = Catalog.call(name, session: @session, store: @store, args: args)
-          update_session_for(name)
-          emit_tool_result(rid, result)
+            @stdout.puts(response)
+            @stdout.flush
+          end
         end
 
-        def update_session_for(name)
-          @session = @session.advance_cursor(@store.audit_log.latest_seq) if name == "pulse"
-          @session = @session.with(contract_etag: contract_etag) if name == "boot"
+        # Called from every MCP::Tool handler block in Catalog.
+        # The SDK parses JSON with symbolize_names: true — all nested keys are symbols.
+        # Deep-stringify so Catalog.call receives the string-key format it expects.
+        def dispatch(verb_name, args, _server_context)
+          str_args = deep_stringify_keys(args)
+          @session.check_etag!(contract_etag_now) unless Catalog.read_verbs.include?(verb_name.to_s)
+          result = Catalog.call(verb_name.to_s, session: @session, store: @store, args: str_args)
+          update_session_for(verb_name.to_s)
+          ::MCP::Tool::Response.new([{ type: "text", text: JSON.dump(result) }])
+        rescue Textus::ContractDrift => e
+          raise_handler_error(e.message, Textus::ContractDrift::JSONRPC_CODE)
+        rescue CursorExpired => e
+          raise_handler_error(e.message, CursorExpired::JSONRPC_CODE)
+        rescue Textus::Surfaces::MCP::ToolError => e
+          raise_handler_error(e.message, ToolError::JSONRPC_CODE)
+        rescue StandardError => e
+          raise_handler_error("internal: #{e.class}: #{e.message}", -32_603)
         end
 
-        def emit_tool_result(rid, result)
-          emit_result(rid, {
-                        "content" => [{ "type" => "text", "text" => JSON.dump(result) }],
-                        "isError" => false,
-                      })
-        end
+        private
 
-        def handle_resources_list(rid)
-          emit_result(rid, { "resources" => machine_resources })
+        def update_session_for(verb_name)
+          @session = @session.advance_cursor(@store.audit_log.latest_seq) if verb_name == "pulse"
+          @session = @session.with(contract_etag: contract_etag_now)      if verb_name == "boot"
         end
 
-        def machine_resources
+        def build_resources
           machine_lane = @store.manifest.policy.machine_lane
           return [] unless machine_lane
 
-          produced_entries(machine_lane).map { |e| resource_descriptor(e) }
-        end
-
-        def produced_entries(machine_lane)
           @store.manifest.data.entries
                 .select { |e| e.lane == machine_lane && e.is_a?(Textus::Manifest::Entry::Produced) }
+                .map { |e| ::MCP::Resource.new(uri: "textus://#{e.key.tr(".", "/")}", name: e.key, mime_type: mime_for_format(e.format)) }
         end
 
-        def resource_descriptor(entry)
-          {
-            "uri" => "textus://#{entry.key.tr(".", "/")}",
-            "name" => entry.key,
-            "mimeType" => mime_for_format(entry.format),
-          }
-        end
-
-        def handle_resources_read(rid, params)
-          uri = params["uri"].to_s
+        def handle_resource_read(uri, _server_context)
           key = uri.delete_prefix("textus://").tr("/", ".")
-          emit_result(rid, resource_contents(uri, key))
-        rescue Textus::Error => e
-          emit_error(rid, ToolError::JSONRPC_CODE, "resource read failed: #{e.message}")
-        end
-
-        def resource_contents(uri, key)
           env  = @store.as(@role).get(key)
-          text = resource_text(env.content || env.body || "")
+          text = env.content.is_a?(Hash) ? JSON.dump(env.content) : (env.body || "").to_s
           mime = mime_for_format(@store.manifest.resolver.resolve(key).entry.format)
-          { "contents" => [{ "uri" => uri, "mimeType" => mime, "text" => text }] }
+          [{ uri: uri, mimeType: mime, text: text }]
+        rescue Textus::Error => e
+          raise_handler_error("resource read failed: #{e.message}", -32_603)
         end
 
-        def resource_text(content)
-          content.is_a?(Hash) ? JSON.dump(content) : content.to_s
-        end
+        def contract_etag_now = Textus::Etag.for_contract(@store.root)
 
-        def contract_etag
-          Textus::Etag.for_contract(@store.root)
+        # The SDK parses JSON with symbolize_names:true, making all nested hash keys symbols.
+        # Recursively stringify so Catalog.call receives string-keyed hashes throughout.
+        def deep_stringify_keys(obj)
+          case obj
+          when Hash  then obj.transform_keys(&:to_s).transform_values { |v| deep_stringify_keys(v) }
+          when Array then obj.map { |v| deep_stringify_keys(v) }
+          else obj
+          end
         end
 
         def mime_for_format(format)
@@ -166,17 +113,8 @@ module Textus
           end
         end
 
-        def emit_result(rid, result)
-          write({ "jsonrpc" => "2.0", "id" => rid, "result" => result })
-        end
-
-        def emit_error(rid, code, message)
-          write({ "jsonrpc" => "2.0", "id" => rid, "error" => { "code" => code, "message" => message } })
-        end
-
-        def write(obj)
-          @stdout.puts(JSON.dump(obj))
-          @stdout.flush
+        def raise_handler_error(message, code)
+          raise ::MCP::Server::RequestHandlerError.new(message, nil, error_code: code)
         end
       end
     end

data/lib/textus/types.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "dry/types"
+
+module Textus
+  module Types
+    include Dry.Types()
+
+    RoleName   = Types::String.constrained(included_in: Textus::Role::NAMES)
+    Cursor     = Types::Integer.constrained(gteq: 0)
+    FormatName = Types::String.constrained(
+      included_in: %w[markdown json yaml text], # must match Format::STRATEGIES.keys
+    )
+  end
+end

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.54.0"
-  PROTOCOL = "textus/3"
+  VERSION = "0.54.1"
+  PROTOCOL = "textus/4"
 end

data/lib/textus/workflow/runner.rb

@@ -64,6 +64,21 @@ module Textus
           mentry: ctx.entry,
           payload: Envelope::Writer::Payload.new(**normalized),
         )
+        publish_external(key, ctx)
+      end
+
+      def publish_external(key, ctx)
+        entry = ctx.entry
+        return unless entry.publish_tree || !Array(entry.publish_to).empty?
+
+        entry_path = @container.manifest.resolver.resolve(key).path
+        return unless entry.publish_tree || File.exist?(entry_path)
+
+        reader = Textus::Envelope::Reader.from(container: @container)
+        pctx   = Textus::Manifest::Entry::Base::PublishContext.new(
+          container: @container, call: @call, reader: reader.method(:read),
+        )
+        entry.publish_via(pctx)
       end
 
       def normalize(data, format)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.54.0
+  version: 0.54.1
 platform: ruby
 authors:
 - Patrick
@@ -24,19 +24,47 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
-  name: mustache
+  name: dry-schema
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '1.13'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: dry-struct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.20'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.20'
 - !ruby/object:Gem::Dependency
   name: psych
   requirement: !ruby/object:Gem::Requirement
@@ -191,6 +219,7 @@ files:
 - lib/textus/doctor/check/schema_violations.rb
 - lib/textus/doctor/check/schemas.rb
 - lib/textus/doctor/check/sentinels.rb
+- lib/textus/doctor/check/stale_reviewed_stamp.rb
 - lib/textus/doctor/check/templates.rb
 - lib/textus/doctor/check/unowned_schema_fields.rb
 - lib/textus/doctor/validator.rb
@@ -251,7 +280,9 @@ files:
 - lib/textus/manifest/resolver.rb
 - lib/textus/manifest/rules.rb
 - lib/textus/manifest/schema.rb
+- lib/textus/manifest/schema/contract.rb
 - lib/textus/manifest/schema/keys.rb
+- lib/textus/manifest/schema/semantics.rb
 - lib/textus/manifest/schema/validator.rb
 - lib/textus/manifest/schema/vocabulary.rb
 - lib/textus/ports/audit_log.rb
@@ -293,12 +324,10 @@ files:
 - lib/textus/surfaces/mcp.rb
 - lib/textus/surfaces/mcp/catalog.rb
 - lib/textus/surfaces/mcp/errors.rb
-- lib/textus/surfaces/mcp/routing.rb
 - lib/textus/surfaces/mcp/server.rb
-- lib/textus/surfaces/mcp/session.rb
-- lib/textus/surfaces/mcp/tool_schemas.rb
 - lib/textus/surfaces/role_scope.rb
 - lib/textus/surfaces/watcher.rb
+- lib/textus/types.rb
 - lib/textus/uid.rb
 - lib/textus/version.rb
 - lib/textus/workflow.rb

data/lib/textus/surfaces/mcp/routing.rb

@@ -1,51 +0,0 @@
-module Textus
-  module Surfaces
-    module MCP
-      # Protocol routing for the MCP JSON-RPC server. Mixed into Server so all
-      # handle_* and emit_* methods are in scope without exposing them publicly.
-      module Routing
-        TOOL_METHODS     = %w[initialize tools/list tools/call].freeze
-        RESOURCE_METHODS = %w[resources/list resources/read].freeze
-
-        def dispatch(msg)
-          rid    = msg["id"]
-          params = msg["params"] || {}
-          route(msg["method"], rid, params)
-        end
-
-        private
-
-        def route(method, rid, params)
-          return route_tool(method, rid, params)     if TOOL_METHODS.include?(method)
-          return route_resource(method, rid, params) if RESOURCE_METHODS.include?(method)
-
-          route_protocol(method, rid)
-        end
-
-        def route_tool(method, rid, params)
-          case method
-          when "initialize" then handle_initialize(rid, params)
-          when "tools/list" then handle_tools_list(rid)
-          when "tools/call" then handle_tools_call(rid, params)
-          end
-        end
-
-        def route_resource(method, rid, params)
-          case method
-          when "resources/list" then handle_resources_list(rid)
-          when "resources/read" then handle_resources_read(rid, params)
-          end
-        end
-
-        def route_protocol(method, rid)
-          case method
-          when "ping"                      then emit_result(rid, {})
-          when "shutdown"                  then emit_result(rid, nil)
-          when "notifications/initialized" then nil
-          else emit_error(rid, -32_601, "method not found: #{method}")
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/surfaces/mcp/session.rb

@@ -1,9 +0,0 @@
-module Textus
-  module Surfaces
-    module MCP
-      # The session value now lives in core (ADR 0036); retained here as an
-      # alias so existing MCP references keep resolving.
-      Session = Textus::Session
-    end
-  end
-end

data/lib/textus/surfaces/mcp/tool_schemas.rb

@@ -1,17 +0,0 @@
-module Textus
-  module Surfaces
-    module MCP
-      # Kept for name stability (ADR 0039). The JSON schemas are DERIVED from
-      # per-verb contracts; this delegates to MCP::Catalog. The hand-written
-      # array is gone — a kwarg rename now updates the schema automatically (and
-      # the signature guard fails if the contract lags the use-case).
-      module ToolSchemas
-        module_function
-
-        def all
-          Catalog.tool_schemas
-        end
-      end
-    end
-  end
-end