agentcat 0.0.1 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. checksums.yaml +4 -4
  2. data/LICENSE +2 -11
  3. data/README.md +265 -20
  4. data/lib/agentcat/adapters/base.rb +98 -0
  5. data/lib/agentcat/adapters/official.rb +277 -0
  6. data/lib/agentcat/client.rb +189 -0
  7. data/lib/agentcat/clock.rb +16 -0
  8. data/lib/agentcat/custom_event.rb +215 -0
  9. data/lib/agentcat/delivery.rb +58 -0
  10. data/lib/agentcat/diagnostics.rb +434 -0
  11. data/lib/agentcat/error_capture.rb +117 -0
  12. data/lib/agentcat/event_id.rb +19 -0
  13. data/lib/agentcat/event_pipeline.rb +82 -0
  14. data/lib/agentcat/event_queue.rb +151 -0
  15. data/lib/agentcat/exporters/base.rb +135 -0
  16. data/lib/agentcat/exporters/datadog.rb +137 -0
  17. data/lib/agentcat/exporters/otlp.rb +157 -0
  18. data/lib/agentcat/exporters/posthog.rb +185 -0
  19. data/lib/agentcat/exporters/sentry.rb +242 -0
  20. data/lib/agentcat/exporters/trace_context.rb +79 -0
  21. data/lib/agentcat/exporters.rb +108 -0
  22. data/lib/agentcat/fork_safety.rb +30 -0
  23. data/lib/agentcat/hooks.rb +190 -0
  24. data/lib/agentcat/http_post.rb +61 -0
  25. data/lib/agentcat/interceptor.rb +728 -0
  26. data/lib/agentcat/log.rb +80 -0
  27. data/lib/agentcat/options.rb +313 -0
  28. data/lib/agentcat/payload_limits.rb +71 -0
  29. data/lib/agentcat/private_members.rb +286 -0
  30. data/lib/agentcat/redaction.rb +176 -0
  31. data/lib/agentcat/rejected_calls.rb +147 -0
  32. data/lib/agentcat/request_context.rb +266 -0
  33. data/lib/agentcat/sanitization.rb +191 -0
  34. data/lib/agentcat/schema/prompts.rb +44 -0
  35. data/lib/agentcat/server_info.rb +280 -0
  36. data/lib/agentcat/session_manager.rb +83 -0
  37. data/lib/agentcat/tags.rb +61 -0
  38. data/lib/agentcat/test_mode.rb +86 -0
  39. data/lib/agentcat/testing.rb +153 -0
  40. data/lib/agentcat/text.rb +68 -0
  41. data/lib/agentcat/token_estimate.rb +98 -0
  42. data/lib/agentcat/tool_call.rb +129 -0
  43. data/lib/agentcat/tool_handle.rb +289 -0
  44. data/lib/agentcat/tracker.rb +204 -0
  45. data/lib/agentcat/truncation.rb +265 -0
  46. data/lib/agentcat/unredacted_event.rb +155 -0
  47. data/lib/agentcat/user_identity.rb +11 -0
  48. data/lib/agentcat/version.rb +2 -2
  49. data/lib/agentcat.rb +393 -21
  50. metadata +194 -16
  51. data/agentcat.gemspec +0 -30
@@ -0,0 +1,68 @@
1
+ # typed: strict
2
+
3
+ module AgentCat
4
+ # String helpers that count the way the TypeScript SDK does. Every string length limit
5
+ # (field caps, the 32K normalize cap, tag keys and values) is in UTF-16 code units, the
6
+ # unit of JavaScript's `String#length`, so a limit means the same thing in every SDK.
7
+ module Text
8
+ extend T::Sig
9
+
10
+ REPLACEMENT = "\uFFFD"
11
+
12
+ # Valid UTF-8 for any string, so JSON encoding can never fail on it. Binary
13
+ # (ASCII-8BIT) strings are read as UTF-8 bytes; every invalid byte becomes U+FFFD,
14
+ # like the PHP SDK. Other encodings are converted. Valid UTF-8 comes back as is.
15
+ sig { params(value: String).returns(String) }
16
+ def self.scrub(value)
17
+ return value if value.encoding == Encoding::UTF_8 && value.valid_encoding?
18
+
19
+ utf8 = if [Encoding::BINARY, Encoding::US_ASCII, Encoding::UTF_8].include?(value.encoding)
20
+ value.dup.force_encoding(Encoding::UTF_8)
21
+ else
22
+ begin
23
+ value.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: REPLACEMENT)
24
+ rescue EncodingError
25
+ value.dup.force_encoding(Encoding::UTF_8)
26
+ end
27
+ end
28
+ utf8.scrub(REPLACEMENT)
29
+ end
30
+
31
+ # Length in UTF-16 code units: one per code point, two for code points above U+FFFF.
32
+ sig { params(value: String).returns(Integer) }
33
+ def self.utf16_length(value)
34
+ value = scrub(value)
35
+ return value.bytesize if value.ascii_only?
36
+
37
+ value.length + value.each_codepoint.count { |code| code > 0xFFFF }
38
+ end
39
+
40
+ # True when `value` is longer than `max` UTF-16 code units. A string never has more
41
+ # UTF-16 code units (after scrubbing) than bytes, so the byte size rules most strings
42
+ # out cheaply.
43
+ sig { params(value: String, max: Integer).returns(T::Boolean) }
44
+ def self.exceeds_utf16?(value, max)
45
+ value.bytesize > max && utf16_length(value) > max
46
+ end
47
+
48
+ # The first `max` UTF-16 code units. A character that would be split in half at the
49
+ # cut (a surrogate pair) is dropped whole, like the PHP SDK, so the result is always
50
+ # valid UTF-8 and can be JSON encoded.
51
+ sig { params(value: String, max: Integer).returns(String) }
52
+ def self.utf16_slice(value, max)
53
+ value = scrub(value)
54
+ return T.must(value[0, max]) if value.ascii_only?
55
+
56
+ units = 0
57
+ chars = 0
58
+ value.each_codepoint do |code|
59
+ width = (code > 0xFFFF) ? 2 : 1
60
+ break if units + width > max
61
+
62
+ units += width
63
+ chars += 1
64
+ end
65
+ T.must(value[0, chars])
66
+ end
67
+ end
68
+ end
@@ -0,0 +1,98 @@
1
+ # typed: strict
2
+
3
+ require "json"
4
+
5
+ module AgentCat
6
+ # Rough token counts for the `input_tokens`/`output_tokens` fields on tool-call events.
7
+ #
8
+ # Same formula as the Go/TS/Python SDKs, byte for byte: ceil(utf8_bytes / 3.5), clamped
9
+ # to int32 (the server's columns). 3.5 sits between what OpenAI's tokenizers (~3.7
10
+ # bytes/token) and Claude's (~3.15) do on real MCP responses.
11
+ #
12
+ # Input is the raw arguments the agent sent, injected params included, as compact JSON.
13
+ # Output is the text of the content blocks the agent reads back - images, blobs and
14
+ # `structuredContent` don't count unless there's nothing else to go on (see
15
+ # `output_tokens`).
16
+ #
17
+ # Never raises: this runs on the tool call's own path, so a value that won't encode
18
+ # costs the field, not the call.
19
+ module TokenEstimate
20
+ extend T::Sig
21
+
22
+ BYTES_PER_TOKEN = 3.5
23
+ MAX_TOKEN_COUNT = 2_147_483_647
24
+
25
+ sig { params(byte_count: Integer).returns(Integer) }
26
+ def self.estimate(byte_count)
27
+ return 0 if byte_count <= 0
28
+
29
+ [(byte_count / BYTES_PER_TOKEN).ceil, MAX_TOKEN_COUNT].min
30
+ end
31
+
32
+ # nil when there are no arguments at all; `{}` counts as `{}`.
33
+ sig { params(arguments: T.untyped).returns(T.nilable(Integer)) }
34
+ def self.input_tokens(arguments)
35
+ return nil if arguments.nil?
36
+
37
+ bytes = compact_json_bytes(arguments)
38
+ bytes && estimate(bytes)
39
+ end
40
+
41
+ # nil when there's no response (the tool raised). A response with no `content` list
42
+ # is counted whole; an empty `content` list falls back to `structuredContent`.
43
+ sig { params(response: T.untyped).returns(T.nilable(Integer)) }
44
+ def self.output_tokens(response)
45
+ return nil unless response.is_a?(Hash)
46
+
47
+ content = fetch(response, :content)
48
+ unless content.is_a?(Array)
49
+ bytes = compact_json_bytes(response)
50
+ return bytes && estimate(bytes)
51
+ end
52
+
53
+ if content.empty?
54
+ structured = fetch(response, :structuredContent)
55
+ return 0 if structured.nil?
56
+
57
+ bytes = compact_json_bytes(structured)
58
+ return bytes && estimate(bytes)
59
+ end
60
+
61
+ estimate(content.sum { |block| content_block_bytes(block) })
62
+ rescue
63
+ nil
64
+ end
65
+
66
+ # Text blocks and embedded text resources are what the agent actually reads.
67
+ sig { params(block: T.untyped).returns(Integer) }
68
+ def self.content_block_bytes(block)
69
+ return 0 unless block.is_a?(Hash)
70
+
71
+ text = case fetch(block, :type).to_s
72
+ when "text" then fetch(block, :text)
73
+ when "resource"
74
+ resource = fetch(block, :resource)
75
+ resource.is_a?(Hash) ? fetch(resource, :text) : nil
76
+ end
77
+ text.is_a?(String) ? text.bytesize : 0
78
+ end
79
+
80
+ # Ruby's JSON doesn't escape `<`, `>`, `&` or non-ASCII, so this matches what
81
+ # `JSON.stringify` produces in the TS SDK.
82
+ sig { params(value: T.untyped).returns(T.nilable(Integer)) }
83
+ def self.compact_json_bytes(value)
84
+ JSON.generate(value).bytesize
85
+ rescue
86
+ nil
87
+ end
88
+
89
+ # Results come back symbol-keyed from `MCP::Tool::Response#to_h`, string-keyed from a
90
+ # tool that returns a plain Hash.
91
+ sig { params(hash: T::Hash[T.untyped, T.untyped], key: Symbol).returns(T.untyped) }
92
+ def self.fetch(hash, key)
93
+ hash.key?(key) ? hash[key] : hash[key.to_s]
94
+ end
95
+
96
+ private_class_method :content_block_bytes, :compact_json_bytes, :fetch
97
+ end
98
+ end
@@ -0,0 +1,129 @@
1
+ # typed: strict
2
+
3
+ module AgentCat
4
+ # One tool call, as the hooks in `Options` (`identify`, `resolve_session_id`,
5
+ # `event_tags`, `event_properties`) see it. Every hook gets this one argument.
6
+ #
7
+ # AgentCat builds it on the request thread before any hook runs, so it holds the
8
+ # HTTP headers of the request even though the hook itself runs on its own thread.
9
+ # It is frozen all the way down: `arguments`, `meta` and `headers` are deep copies,
10
+ # and changing them raises `FrozenError`. A hook cannot change what your tool gets
11
+ # or what the event records.
12
+ #
13
+ # * `tool_name` — name of the tool the client called.
14
+ # * `arguments` — the raw call arguments (String keys), including the parameters
15
+ # AgentCat injects (`session_id`, `agent_id`, `context`).
16
+ # * `meta` — the raw `_meta` of the call (String keys); empty when there is none.
17
+ # * `headers` — HTTP request headers with lower-case names, one String each
18
+ # (repeated values joined with ", "); empty on stdio.
19
+ # * `client_name`, `client_version` — the MCP client, when it is known: from the
20
+ # `initialize` handshake, or from the SEP-2575 `_meta` clientInfo on a stateless call.
21
+ # * `protocol_version` — the MCP protocol version the call itself claims (the
22
+ # SEP-2575 envelope or `_meta`), when it is known. nil after a plain `initialize`
23
+ # handshake, where the version belongs to the session, not the call.
24
+ # * `transport_session_id` — the `Mcp-Session-Id` of the transport session; never the
25
+ # AgentCat session ID. nil on stdio and on stateless HTTP.
26
+ # * `request` — the Rack env of the HTTP request, for details this class does not
27
+ # expose; nil on stdio. Not copied or frozen: treat it as read-only.
28
+ # * `server_context` — the `mcp` gem's server context of the call. Not copied or
29
+ # frozen: treat it as read-only.
30
+ class ToolCall
31
+ extend T::Sig
32
+
33
+ sig { returns(String) }
34
+ attr_reader :tool_name
35
+
36
+ sig { returns(T::Hash[String, T.untyped]) }
37
+ attr_reader :arguments
38
+
39
+ sig { returns(T::Hash[String, T.untyped]) }
40
+ attr_reader :meta
41
+
42
+ sig { returns(T::Hash[String, String]) }
43
+ attr_reader :headers
44
+
45
+ sig { returns(T.nilable(String)) }
46
+ attr_reader :client_name
47
+
48
+ sig { returns(T.nilable(String)) }
49
+ attr_reader :client_version
50
+
51
+ sig { returns(T.nilable(String)) }
52
+ attr_reader :protocol_version
53
+
54
+ sig { returns(T.nilable(String)) }
55
+ attr_reader :transport_session_id
56
+
57
+ sig { returns(T.untyped) }
58
+ attr_reader :request
59
+
60
+ sig { returns(T.untyped) }
61
+ attr_reader :server_context
62
+
63
+ sig do
64
+ params(
65
+ tool_name: String,
66
+ arguments: T::Hash[T.untyped, T.untyped],
67
+ meta: T::Hash[T.untyped, T.untyped],
68
+ headers: T::Hash[T.untyped, T.untyped],
69
+ client_name: T.nilable(String),
70
+ client_version: T.nilable(String),
71
+ protocol_version: T.nilable(String),
72
+ transport_session_id: T.nilable(String),
73
+ request: T.untyped,
74
+ server_context: T.untyped
75
+ ).void
76
+ end
77
+ def initialize(
78
+ tool_name:,
79
+ arguments:,
80
+ meta: {},
81
+ headers: {},
82
+ client_name: nil,
83
+ client_version: nil,
84
+ protocol_version: nil,
85
+ transport_session_id: nil,
86
+ request: nil,
87
+ server_context: nil
88
+ )
89
+ @tool_name = T.let(frozen_copy(tool_name), String)
90
+ @arguments = T.let(frozen_copy(arguments.transform_keys(&:to_s)), T::Hash[String, T.untyped])
91
+ @meta = T.let(frozen_copy(meta.transform_keys(&:to_s)), T::Hash[String, T.untyped])
92
+ @headers = T.let(frozen_copy(headers.to_h { |name, value| [name.to_s.downcase, value.to_s] }), T::Hash[String, String])
93
+ @client_name = T.let(frozen_copy(client_name), T.nilable(String))
94
+ @client_version = T.let(frozen_copy(client_version), T.nilable(String))
95
+ @protocol_version = T.let(frozen_copy(protocol_version), T.nilable(String))
96
+ @transport_session_id = T.let(frozen_copy(transport_session_id), T.nilable(String))
97
+ @request = request
98
+ @server_context = server_context
99
+ freeze
100
+ end
101
+
102
+ private
103
+
104
+ # A frozen deep copy of the Hash/Array/String structure. Other leaves (numbers, true,
105
+ # false, nil, symbols) are immutable already; any other object is kept as is.
106
+ # `copies` keeps a cyclic structure from looping and shared sub-objects shared.
107
+ sig { params(value: T.untyped, copies: T::Hash[Integer, T.untyped]).returns(T.untyped) }
108
+ def frozen_copy(value, copies = {})
109
+ case value
110
+ when Hash
111
+ copies.fetch(value.object_id) do
112
+ copy = copies[value.object_id] = {}
113
+ value.each { |key, item| copy[frozen_copy(key, copies)] = frozen_copy(item, copies) }
114
+ copy.freeze
115
+ end
116
+ when Array
117
+ copies.fetch(value.object_id) do
118
+ copy = copies[value.object_id] = []
119
+ value.each { |item| copy << frozen_copy(item, copies) }
120
+ copy.freeze
121
+ end
122
+ when String
123
+ value.frozen? ? value : value.dup.freeze
124
+ else
125
+ value
126
+ end
127
+ end
128
+ end
129
+ end
@@ -0,0 +1,289 @@
1
+ # typed: true
2
+
3
+ require "json"
4
+
5
+ module AgentCat
6
+ # Wraps a tool registered on an MCP server.
7
+ #
8
+ # Exposes the same surface `MCP::Tool` does (`name_value`, `input_schema`, `title`,
9
+ # `annotations`, `to_h`, `call`, ...), so `MCP::Server` can list, validate and dispatch
10
+ # it with no idea it's wrapped.
11
+ class ToolHandle
12
+ extend T::Sig
13
+
14
+ sig { returns(String) }
15
+ attr_reader :name
16
+
17
+ sig { returns(T.nilable(String)) }
18
+ attr_reader :title
19
+
20
+ sig { returns(T.nilable(String)) }
21
+ attr_reader :description
22
+
23
+ sig { returns(T.untyped) }
24
+ attr_reader :icons
25
+
26
+ sig { returns(T.untyped) }
27
+ attr_reader :annotations
28
+
29
+ sig { returns(T.untyped) }
30
+ attr_reader :meta
31
+
32
+ sig { returns(T.untyped) }
33
+ attr_reader :input_schema
34
+
35
+ sig { returns(T.untyped) }
36
+ attr_reader :output_schema
37
+
38
+ alias_method :name_value, :name
39
+ alias_method :title_value, :title
40
+ alias_method :description_value, :description
41
+ alias_method :icons_value, :icons
42
+ alias_method :annotations_value, :annotations
43
+ alias_method :meta_value, :meta
44
+ alias_method :input_schema_value, :input_schema
45
+ alias_method :output_schema_value, :output_schema
46
+
47
+ # `call_fn` receives `(arguments, server_context)` where `arguments` is a string-keyed Hash.
48
+ sig do
49
+ params(
50
+ name: String,
51
+ call_fn: T.untyped,
52
+ input_schema: T.untyped,
53
+ output_schema: T.untyped,
54
+ title: T.nilable(String),
55
+ description: T.nilable(String),
56
+ icons: T.untyped,
57
+ annotations: T.untyped,
58
+ meta: T.untyped
59
+ ).void
60
+ end
61
+ def initialize(name:, call_fn:, input_schema: nil, output_schema: nil, title: nil, description: nil, icons: nil, annotations: nil, meta: nil)
62
+ @name = name
63
+ @call_fn = call_fn
64
+ @input_schema = input_schema || {type: "object", properties: {}}
65
+ @output_schema = output_schema
66
+ @title = title
67
+ @description = description
68
+ @icons = icons
69
+ @annotations = annotations
70
+ @meta = meta
71
+ @interceptor = T.let(nil, T.untyped)
72
+ @soft_required = T.let({}, T::Hash[String, String])
73
+ end
74
+
75
+ sig { returns(T::Hash[Symbol, T.untyped]) }
76
+ def to_h
77
+ {
78
+ name: name,
79
+ title: title,
80
+ description: description,
81
+ icons: icons_to_h,
82
+ inputSchema: schema_to_h(input_schema),
83
+ outputSchema: schema_to_h(output_schema),
84
+ annotations: annotations&.to_h,
85
+ _meta: meta
86
+ }.compact
87
+ end
88
+
89
+ # Whether the input schema is a `oneOf`/`allOf`/`anyOf` composition rather than a
90
+ # plain object schema. `properties`/`required` have no defined meaning as a sibling
91
+ # of these keywords, so injecting into one would either do nothing or corrupt it -
92
+ # safer to leave composed schemas alone entirely.
93
+ sig { returns(T::Boolean) }
94
+ def composed_input_schema?
95
+ composed?(schema_to_h(input_schema))
96
+ end
97
+
98
+ sig { returns(T::Boolean) }
99
+ def composed_output_schema?
100
+ composed?(schema_to_h(output_schema))
101
+ end
102
+
103
+ # Adds a string property to the input schema, optionally `required` and/or with a
104
+ # `pattern`, unless that name is already there. Keeps the schema's original class
105
+ # (Hash stays Hash, `MCP::Tool::InputSchema` gets rebuilt). Safe to call twice. No-op
106
+ # on a composed schema - see `composed_input_schema?`.
107
+ #
108
+ # `required` here is soft, like the TS SDK's: `tools/list` shows the name under
109
+ # `required` so schema-aware clients fill it in, but a call that leaves it out still
110
+ # gets through to the interceptor instead of being bounced by the `mcp` gem's own
111
+ # required check (see `SoftRequired`). `placeholder` is what that check is handed in
112
+ # place of a missing value - it never reaches the handler or the event.
113
+ sig { params(name: T.any(String, Symbol), description: T.nilable(String), type: String, required: T::Boolean, pattern: T.nilable(String), placeholder: String).returns(T.self_type) }
114
+ def add_input_parameter(name, description: nil, type: "string", required: false, pattern: nil, placeholder: "")
115
+ return self if composed_input_schema?
116
+
117
+ key = name.to_sym
118
+ schema = T.must(schema_to_h(input_schema))
119
+ properties = (schema[:properties] ||= {})
120
+ declared = properties.key?(key)
121
+ properties[key] = {type: type, description: description, pattern: pattern}.compact unless declared
122
+
123
+ # Without the gem internals that make it soft (`PrivateMembers`), a required name
124
+ # would turn away every call that leaves it out, so it is only listed, not required.
125
+ required = false if required && !declared && !soft_required_supported?
126
+ if required
127
+ required_list = T.let(schema[:required] ||= [], T::Array[T.untyped])
128
+ required_list << key.to_s unless required_list.include?(key.to_s)
129
+ # Only soften what we added - a name the tool declared itself stays as strict as
130
+ # the tool made it (our own `get_more_tools` declares its `context`).
131
+ @soft_required[key.to_s] = placeholder unless declared
132
+ end
133
+
134
+ @input_schema = rebuild_input_schema(input_schema, schema)
135
+ self
136
+ end
137
+
138
+ # Adds a property to the output schema unless one with that name exists, the tool
139
+ # declares no output schema at all (nothing to extend), or that schema is composed -
140
+ # see `composed_output_schema?`. `schema` is a full JSON Schema property hash (type,
141
+ # description, nested properties, ...).
142
+ sig { params(name: T.any(String, Symbol), schema: T::Hash[Symbol, T.untyped]).returns(T.self_type) }
143
+ def add_output_parameter(name, schema)
144
+ return self if output_schema.nil? || composed_output_schema?
145
+
146
+ key = name.to_sym
147
+ hash = T.must(schema_to_h(output_schema))
148
+ properties = (hash[:properties] ||= {})
149
+ return self if properties.key?(key)
150
+
151
+ properties[key] = schema
152
+ @output_schema = rebuild_schema(output_schema, hash)
153
+ self
154
+ end
155
+
156
+ sig { params(name: T.any(String, Symbol)).returns(T::Boolean) }
157
+ def input_parameter?(name)
158
+ properties = T.must(schema_to_h(input_schema))[:properties] || {}
159
+ properties.key?(name.to_sym)
160
+ end
161
+
162
+ sig { params(interceptor: T.untyped).returns(T.self_type) }
163
+ def intercept(&interceptor)
164
+ @interceptor = interceptor
165
+ self
166
+ end
167
+
168
+ sig { returns(T::Boolean) }
169
+ def intercepted?
170
+ !@interceptor.nil?
171
+ end
172
+
173
+ # Entry point used by `MCP::Server` (`tool.call(**arguments, server_context: ctx)`).
174
+ # A positional Hash is accepted for direct invocation.
175
+ sig { params(arguments: T.nilable(T::Hash[T.untyped, T.untyped]), server_context: T.untyped, keyword_arguments: T.untyped).returns(T.untyped).checked(:tests) }
176
+ def call(arguments = nil, server_context: nil, **keyword_arguments)
177
+ arguments = keyword_arguments if arguments.nil?
178
+ return invoke_original(arguments, server_context) unless @interceptor
179
+
180
+ @interceptor.call(arguments, server_context, method(:invoke_original))
181
+ end
182
+
183
+ sig { params(arguments: T.nilable(T::Hash[T.untyped, T.untyped]), server_context: T.untyped).returns(T.untyped).checked(:tests) }
184
+ def invoke_original(arguments, server_context)
185
+ @call_fn.call((arguments || {}).transform_keys(&:to_s), server_context)
186
+ end
187
+
188
+ private
189
+
190
+ sig { returns(T::Boolean) }
191
+ def soft_required_supported?
192
+ input_schema.is_a?(Hash) || PrivateMembers.enabled?(PrivateMembers::INPUT_SCHEMA_MISSING_REQUIRED_ARGUMENTS.feature)
193
+ end
194
+
195
+ sig { returns(T.nilable(T::Array[T.untyped])) }
196
+ def icons_to_h
197
+ return nil if icons.nil? || icons.empty?
198
+
199
+ icons.map { |icon| icon.respond_to?(:to_h) ? icon.to_h : icon }
200
+ end
201
+
202
+ # Deep copy of a schema as a symbol-keyed Hash.
203
+ sig { params(schema: T.untyped).returns(T.nilable(T::Hash[Symbol, T.untyped])) }
204
+ def schema_to_h(schema)
205
+ return nil if schema.nil?
206
+
207
+ hash = schema.is_a?(Hash) ? schema : schema.to_h
208
+ JSON.parse(JSON.generate(hash), symbolize_names: true)
209
+ end
210
+
211
+ sig { params(schema: T.nilable(T::Hash[Symbol, T.untyped])).returns(T::Boolean) }
212
+ def composed?(schema)
213
+ !!(schema && (schema.key?(:oneOf) || schema.key?(:allOf) || schema.key?(:anyOf)))
214
+ end
215
+
216
+ # Same as `rebuild_schema`, but an `MCP::Tool::InputSchema` comes back soft about the
217
+ # names in `@soft_required`. A plain Hash can't carry that, so it stays as it is.
218
+ sig { params(original: T.untyped, hash: T::Hash[Symbol, T.untyped]).returns(T.untyped) }
219
+ def rebuild_input_schema(original, hash)
220
+ return hash if original.is_a?(Hash)
221
+ return rebuild_schema(original, hash) if @soft_required.empty? || !original.respond_to?(:missing_required_arguments)
222
+
223
+ SoftRequired.build(original.class, hash, @soft_required)
224
+ end
225
+
226
+ # Hash stays Hash; anything else (`MCP::Tool::InputSchema`/`OutputSchema`) gets
227
+ # reconstructed from the mutated hash so the original wrapper class survives.
228
+ sig { params(original: T.untyped, hash: T::Hash[Symbol, T.untyped]).returns(T.untyped) }
229
+ def rebuild_schema(original, hash)
230
+ original.is_a?(Hash) ? hash : original.class.new(hash)
231
+ end
232
+ end
233
+
234
+ # Makes some `required` names advisory on an `MCP::Tool::InputSchema`, by overriding two
235
+ # of its methods (`PrivateMembers::INPUT_SCHEMA_*`). `to_h` (what
236
+ # `tools/list` sends) is untouched, so those names still show as required. The two
237
+ # checks the `mcp` gem runs before calling a tool skip them: `missing_required_arguments`
238
+ # leaves them out, and `validate_arguments` (only on with `validate_tool_call_arguments`)
239
+ # validates as if the missing ones had their placeholder. The arguments themselves
240
+ # aren't touched, so the interceptor sees exactly what the agent sent.
241
+ module SoftRequired
242
+ extend T::Sig
243
+
244
+ SUBCLASSES = T.let({}, T::Hash[T.untyped, T.untyped])
245
+ SUBCLASSES_MUTEX = T.let(Mutex.new, Mutex)
246
+
247
+ sig { params(base: T.untyped, hash: T::Hash[Symbol, T.untyped], placeholders: T::Hash[String, String]).returns(T.untyped) }
248
+ def self.build(base, hash, placeholders)
249
+ schema = class_for(base).new(hash)
250
+ schema.soft_placeholders = placeholders.dup.freeze
251
+ schema
252
+ end
253
+
254
+ # One subclass per schema class, made on first use — `mcp` may not even be loaded
255
+ # when agentcat is. A schema that's already soft keeps its class.
256
+ sig { params(base: T.untyped).returns(T.untyped) }
257
+ def self.class_for(base)
258
+ return base if base < SchemaMethods
259
+
260
+ SUBCLASSES_MUTEX.synchronize do
261
+ SUBCLASSES[base] ||= Class.new(base) { include SchemaMethods }
262
+ end
263
+ end
264
+
265
+ module SchemaMethods
266
+ attr_accessor :soft_placeholders
267
+
268
+ def missing_required_arguments(arguments)
269
+ super - soft_placeholders.keys
270
+ rescue NoMethodError => e
271
+ Kernel.raise unless e.name == :missing_required_arguments && e.receiver.equal?(self)
272
+
273
+ AgentCat::PrivateMembers.missing!(AgentCat::PrivateMembers::INPUT_SCHEMA_MISSING_REQUIRED_ARGUMENTS)
274
+ []
275
+ end
276
+
277
+ def validate_arguments(arguments)
278
+ given = arguments.keys.map(&:to_s)
279
+ filler = soft_placeholders.except(*given).transform_keys(&:to_sym)
280
+ super(filler.merge(arguments))
281
+ rescue NoMethodError => e
282
+ Kernel.raise unless e.name == :validate_arguments && e.receiver.equal?(self)
283
+
284
+ AgentCat::PrivateMembers.missing!(AgentCat::PrivateMembers::INPUT_SCHEMA_VALIDATE_ARGUMENTS)
285
+ nil
286
+ end
287
+ end
288
+ end
289
+ end