agentcat 0.0.1 → 1.0.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 (50) 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 +73 -0
  5. data/lib/agentcat/adapters/official.rb +194 -0
  6. data/lib/agentcat/client.rb +171 -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 +711 -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 +271 -0
  30. data/lib/agentcat/redaction.rb +115 -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/session_manager.rb +83 -0
  36. data/lib/agentcat/tags.rb +61 -0
  37. data/lib/agentcat/test_mode.rb +86 -0
  38. data/lib/agentcat/testing.rb +153 -0
  39. data/lib/agentcat/text.rb +68 -0
  40. data/lib/agentcat/token_estimate.rb +98 -0
  41. data/lib/agentcat/tool_call.rb +129 -0
  42. data/lib/agentcat/tool_handle.rb +289 -0
  43. data/lib/agentcat/tracker.rb +201 -0
  44. data/lib/agentcat/truncation.rb +265 -0
  45. data/lib/agentcat/unredacted_event.rb +155 -0
  46. data/lib/agentcat/user_identity.rb +11 -0
  47. data/lib/agentcat/version.rb +2 -2
  48. data/lib/agentcat.rb +391 -21
  49. metadata +193 -16
  50. data/agentcat.gemspec +0 -30
@@ -0,0 +1,271 @@
1
+ # typed: strict
2
+
3
+ require_relative "log"
4
+
5
+ module AgentCat
6
+ # The manifest of `mcp` gem internals AgentCat depends on:
7
+ # instance variables it reads, private methods it overrides, and public methods or
8
+ # hashes it patches in a way the gem never promised to support. Each use site names
9
+ # its member through a constant here, never a literal, so this file is the whole list.
10
+ #
11
+ # `check!` (run once per process by `AgentCat.track`) verifies every member against the
12
+ # `mcp` gem that is loaded. A missing member logs one ERROR line naming it and the gem
13
+ # version, and turns off the one feature that depends on it. Nothing here ever raises
14
+ # into the host. A use site that finds its member gone at run time calls `missing!`
15
+ # too, with the same effect.
16
+ #
17
+ # `test/test_private_members.rb` checks the manifest against the installed gem and
18
+ # fails with the member's name; CONTRIBUTING.md says how to update it.
19
+ module PrivateMembers
20
+ extend T::Sig
21
+
22
+ class Member < T::Struct
23
+ extend T::Sig
24
+
25
+ # The class that holds the member, as a constant string, so this file loads (and
26
+ # the SDK runs) without the `mcp` gem.
27
+ const :owner, String
28
+ const :name, String
29
+ # :ivar - an instance variable AgentCat reads
30
+ # :private_method - a private method AgentCat overrides with a prepended module
31
+ # :method - a method AgentCat overrides (subclass, prepend) or wraps per instance
32
+ # :internal_hash - a Hash the gem keeps internally that AgentCat writes into
33
+ const :kind, Symbol
34
+ const :feature, Symbol
35
+
36
+ sig { returns(String) }
37
+ def label
38
+ (kind == :ivar) ? "#{owner}#{name}" : "#{owner}##{name}"
39
+ end
40
+ end
41
+
42
+ # What each feature does, for the log line that turns it off.
43
+ FEATURES = T.let({
44
+ tool_instrumentation: "tool call tracking",
45
+ late_tool_sync: "tracking of tools defined after track",
46
+ soft_required: "optional AgentCat parameters (they are not listed as required)",
47
+ request_headers: "HTTP headers and URL in events",
48
+ request_id: "requestId in events",
49
+ legacy_client_info: "the client name and version in events",
50
+ rejected_calls: "events for calls the mcp gem rejects (unknown tool, invalid arguments)"
51
+ }.freeze, T::Hash[Symbol, String])
52
+
53
+ # `MCP::Server#tools` is public, but AgentCat replaces its entries in place with
54
+ # `AgentCat::ToolHandle`s (adapters/official.rb).
55
+ SERVER_TOOLS = Member.new(owner: "MCP::Server", name: "tools", kind: :internal_hash, feature: :tool_instrumentation)
56
+ # Wrapped per server, so a tool defined after `track` is instrumented before its first
57
+ # listing or call (adapters/official.rb).
58
+ SERVER_HANDLE = Member.new(owner: "MCP::Server", name: "handle", kind: :method, feature: :late_tool_sync)
59
+ SERVER_HANDLE_JSON = Member.new(owner: "MCP::Server", name: "handle_json", kind: :method, feature: :late_tool_sync)
60
+ # Overridden in a subclass, so the injected parameters are required in `tools/list`
61
+ # but a call without them still reaches AgentCat (tool_handle.rb, `SoftRequired`).
62
+ INPUT_SCHEMA_MISSING_REQUIRED_ARGUMENTS = Member.new(owner: "MCP::Tool::InputSchema", name: "missing_required_arguments", kind: :method, feature: :soft_required)
63
+ INPUT_SCHEMA_VALIDATE_ARGUMENTS = Member.new(owner: "MCP::Tool::InputSchema", name: "validate_arguments", kind: :method, feature: :soft_required)
64
+ # Prepended, so the request's headers are in scope when the event is built
65
+ # (request_context.rb, `TransportHook`).
66
+ STREAMABLE_HTTP_TRANSPORT_CALL = Member.new(owner: "MCP::Server::Transports::StreamableHTTPTransport", name: "call", kind: :method, feature: :request_headers)
67
+ # Private; prepended per server, so a call the gem rejects before the tool runs (no
68
+ # such tool, invalid arguments) still gets an event (rejected_calls.rb).
69
+ SERVER_CALL_TOOL = Member.new(owner: "MCP::Server", name: "call_tool", kind: :private_method, feature: :rejected_calls)
70
+ # The JSON-RPC id of the `tools/call`; no reader (interceptor.rb, `request_id`).
71
+ SERVER_CONTEXT_RELATED_REQUEST_ID = Member.new(owner: "MCP::ServerContext", name: "@related_request_id", kind: :ivar, feature: :request_id)
72
+ # The session, for its clientInfo on gems without `ServerContext#client_info`
73
+ # (interceptor.rb, `legacy_session_client`).
74
+ SERVER_CONTEXT_NOTIFICATION_TARGET = Member.new(owner: "MCP::ServerContext", name: "@notification_target", kind: :ivar, feature: :legacy_client_info)
75
+
76
+ ALL = T.let([
77
+ SERVER_TOOLS,
78
+ SERVER_HANDLE,
79
+ SERVER_HANDLE_JSON,
80
+ SERVER_CALL_TOOL,
81
+ INPUT_SCHEMA_MISSING_REQUIRED_ARGUMENTS,
82
+ INPUT_SCHEMA_VALIDATE_ARGUMENTS,
83
+ STREAMABLE_HTTP_TRANSPORT_CALL,
84
+ SERVER_CONTEXT_RELATED_REQUEST_ID,
85
+ SERVER_CONTEXT_NOTIFICATION_TARGET
86
+ ].freeze, T::Array[Member])
87
+
88
+ @mutex = T.let(Mutex.new, Mutex)
89
+ @checked = T.let(false, T::Boolean)
90
+ # member => true (present) or false (missing); a member whose class is not loaded yet
91
+ # has no entry and is probed again on the next `verify`.
92
+ @results = T.let({}, T::Hash[Member, T::Boolean])
93
+ @disabled = T.let({}, T::Hash[Symbol, T::Boolean])
94
+ @reported = T.let({}, T::Hash[Member, T::Boolean])
95
+
96
+ class << self
97
+ extend T::Sig
98
+
99
+ # Verifies every member once per process. A no-op without the `mcp` gem.
100
+ sig { void }
101
+ def check!
102
+ return if @checked
103
+ return unless Object.const_defined?(:MCP)
104
+
105
+ @checked = true
106
+ ALL.each { |member| verify(member) }
107
+ rescue
108
+ nil
109
+ end
110
+
111
+ # true when `member` is on the loaded gem. Probes it the first time (and again
112
+ # later while its class can't be loaded); a missing member is reported and its
113
+ # feature turned off.
114
+ sig { params(member: Member).returns(T::Boolean) }
115
+ def verify(member)
116
+ known = @mutex.synchronize { @results[member] }
117
+ return known && enabled?(member.feature) unless known.nil?
118
+
119
+ found = probe(member)
120
+ return false if found.nil?
121
+
122
+ @mutex.synchronize { @results[member] = found }
123
+ missing!(member) unless found
124
+ found && enabled?(member.feature)
125
+ end
126
+
127
+ sig { params(feature: Symbol).returns(T::Boolean) }
128
+ def enabled?(feature)
129
+ !@disabled.key?(feature)
130
+ end
131
+
132
+ # Turns the member's feature off and logs one line, once per member. Called by
133
+ # `check!` and by a use site that finds its member gone at run time.
134
+ sig { params(member: Member).void }
135
+ def missing!(member)
136
+ first = @mutex.synchronize do
137
+ @results[member] = false
138
+ @disabled[member.feature] = true
139
+ !@reported.key?(member) && (@reported[member] = true)
140
+ end
141
+ return unless first
142
+
143
+ Log.error("AgentCat cannot find #{member.label} in mcp #{mcp_version}, so #{FEATURES.fetch(member.feature)} is off")
144
+ rescue
145
+ nil
146
+ end
147
+
148
+ # true when `object` is an instance of the member's class: a use site only reports
149
+ # a member missing from the gem's own objects, not from a host's stand-in.
150
+ sig { params(object: T.untyped, member: Member).returns(T::Boolean) }
151
+ def owner_instance?(object, member)
152
+ object.class.ancestors.any? { |ancestor| ancestor.name == member.owner }
153
+ rescue
154
+ false
155
+ end
156
+
157
+ sig { returns(String) }
158
+ def mcp_version
159
+ T.unsafe(Object.const_get("MCP::VERSION")).to_s
160
+ rescue NameError
161
+ "unknown"
162
+ end
163
+
164
+ # true (present), false (missing) or nil (its class can't be loaded, as with the
165
+ # HTTP transport in a process without Rack).
166
+ sig { params(member: Member).returns(T.nilable(T::Boolean)) }
167
+ def probe(member)
168
+ owner = resolve(member.owner)
169
+ return nil if owner.nil?
170
+
171
+ case member
172
+ when SERVER_TOOLS then server_tools_hash?(owner)
173
+ when SERVER_HANDLE, SERVER_HANDLE_JSON then public_method?(owner, member.name)
174
+ when INPUT_SCHEMA_MISSING_REQUIRED_ARGUMENTS then soft_missing_required?(owner)
175
+ when INPUT_SCHEMA_VALIDATE_ARGUMENTS then soft_validate?(owner)
176
+ when STREAMABLE_HTTP_TRANSPORT_CALL, SERVER_CALL_TOOL then own_method?(owner, member.name)
177
+ else ivar_on_server_context?(owner, member.name)
178
+ end
179
+ rescue
180
+ false
181
+ end
182
+
183
+ # Forgets every result and turns every feature back on, for `AgentCat.reset!`.
184
+ sig { void }
185
+ def reset!
186
+ @mutex.synchronize do
187
+ @checked = false
188
+ @results.clear
189
+ @disabled.clear
190
+ @reported.clear
191
+ end
192
+ end
193
+
194
+ private
195
+
196
+ sig { params(name: String).returns(T.untyped) }
197
+ def resolve(name)
198
+ # `mcp` autoloads MCP::Server, and only mcp/server.rb requires mcp/server_context:
199
+ # MCP::ServerContext has no autoload of its own. Load the server first, so that a
200
+ # probe does not depend on what the process happened to load before it.
201
+ Object.const_get("MCP::Server") if name.start_with?("MCP::")
202
+ Object.const_get(name)
203
+ rescue NameError, LoadError
204
+ nil
205
+ end
206
+
207
+ sig { params(server_class: T.untyped).returns(T::Boolean) }
208
+ def server_tools_hash?(server_class)
209
+ server_class.new(name: "agentcat_probe").tools.is_a?(Hash)
210
+ end
211
+
212
+ # A method the class itself defines (a prepended module of ours doesn't count),
213
+ # taking the request (or Rack env) as its first argument.
214
+ sig { params(klass: T.untyped, name: String).returns(T::Boolean) }
215
+ def own_method?(klass, name)
216
+ return false unless klass.method_defined?(name.to_sym) || klass.private_method_defined?(name.to_sym)
217
+
218
+ method = klass.instance_method(name.to_sym)
219
+ method = method.super_method while method && method.owner != klass
220
+ first_argument?(method)
221
+ end
222
+
223
+ sig { params(klass: T.untyped, name: String).returns(T::Boolean) }
224
+ def public_method?(klass, name)
225
+ return false unless klass.public_method_defined?(name.to_sym)
226
+
227
+ first_argument?(klass.instance_method(name.to_sym))
228
+ end
229
+
230
+ sig { params(method: T.untyped).returns(T::Boolean) }
231
+ def first_argument?(method)
232
+ return false if method.nil?
233
+
234
+ type, = method.parameters.first
235
+ type == :req
236
+ end
237
+
238
+ # The gem's `missing_required_arguments?` has to go through the overridden
239
+ # `missing_required_arguments`, or a soft name would still be enforced.
240
+ sig { params(schema_class: T.untyped).returns(T::Boolean) }
241
+ def soft_missing_required?(schema_class)
242
+ return false unless schema_class.method_defined?(:missing_required_arguments)
243
+
244
+ !probe_schema(schema_class).missing_required_arguments?({})
245
+ end
246
+
247
+ sig { params(schema_class: T.untyped).returns(T::Boolean) }
248
+ def soft_validate?(schema_class)
249
+ return false unless schema_class.method_defined?(:validate_arguments)
250
+
251
+ probe_schema(schema_class).validate_arguments({})
252
+ true
253
+ end
254
+
255
+ sig { params(schema_class: T.untyped).returns(T.untyped) }
256
+ def probe_schema(schema_class)
257
+ hash = {type: "object", properties: {agentcat_probe: {type: "string"}}, required: ["agentcat_probe"]}
258
+ SoftRequired.build(schema_class, hash, {"agentcat_probe" => ""})
259
+ end
260
+
261
+ # Checked on a real instance: the gem may still accept the keyword but stop
262
+ # keeping it under this name.
263
+ sig { params(context_class: T.untyped, ivar: String).returns(T::Boolean) }
264
+ def ivar_on_server_context?(context_class, ivar)
265
+ accepted = context_class.instance_method(:initialize).parameters.map { |_type, name| name }
266
+ keywords = {progress: nil, notification_target: nil, related_request_id: 1}.slice(*accepted)
267
+ context_class.new(nil, **keywords).instance_variable_defined?(ivar.to_sym)
268
+ end
269
+ end
270
+ end
271
+ end
@@ -0,0 +1,115 @@
1
+ # typed: true
2
+
3
+ require_relative "hooks"
4
+
5
+ module AgentCat
6
+ # Applies `Options#redact_event`/`#redact_sensitive_information` to an event. Shared
7
+ # by `Interceptor` (every tool-call event) and `AgentCat.publish_custom_event` (events
8
+ # built outside any tool call). Runs on the queue's worker thread, via `EventPipeline`.
9
+ module Redaction
10
+ extend T::Sig
11
+
12
+ # Not the hook's to change: these decide where and how the event gets ingested. Same
13
+ # five fields TS (`RESTORED_FIELDS`) and Go (`ApplyEventRedaction`) put back.
14
+ RESTORED_FIELDS = T.let(%i[id session_id project_id event_type timestamp].freeze, T::Array[Symbol])
15
+
16
+ sig { params(event: UnredactedEvent, options: AgentCat::Options).returns(T.nilable(UnredactedEvent)).checked(:tests) }
17
+ def self.apply_redact_event(event, options)
18
+ hook = options.redact_event
19
+ return event unless hook
20
+
21
+ # Snapshot first - a hook that mutates in place has already changed `event` by
22
+ # the time it returns.
23
+ original = RESTORED_FIELDS.to_h { |field| [field, event.public_send(field)] }
24
+ result = Hooks.run(hook, event, timeout: options.hook_timeout, name: "redact_event")
25
+ return nil if result.nil?
26
+
27
+ kept = if !result.is_a?(UnredactedEvent)
28
+ Log.warn("redact_event hook returned #{result.class}, not the event or nil; its result is ignored")
29
+ event
30
+ elsif result.equal?(event)
31
+ event
32
+ else
33
+ warn_detached(result)
34
+ end
35
+ restore(kept, original)
36
+ end
37
+
38
+ # Raised when the string hook didn't hand back a string for some value.
39
+ class StringRedactionFailed < StandardError; end
40
+
41
+ # nil drops the event: if the hook raised, timed out or returned a non-String for
42
+ # any one value, we can't tell what's still unredacted, so nothing goes out.
43
+ #
44
+ # Same fields as TS's `redactEvent`: everything an actor or a tool put on the event
45
+ # (parameters, user_intent, response, identify_data, and the whole error - message,
46
+ # stack, frames, chained errors). TS's `PROTECTED_FIELDS` leaves `properties` and
47
+ # `tags` alone: they are the customer's own metadata, not captured traffic.
48
+ sig { params(event: UnredactedEvent, options: AgentCat::Options).returns(T.nilable(UnredactedEvent)).checked(:tests) }
49
+ def self.apply_sensitive_redaction(event, options)
50
+ hook = options.redact_sensitive_information
51
+ return event unless hook
52
+
53
+ worker = Hooks::Worker.new(hook, timeout: options.hook_timeout)
54
+ redacter = ->(value) { value.is_a?(String) ? redact_string(worker, value) : value }
55
+ event.parameters = deep_map(event.parameters, &redacter)
56
+ unless event.user_intent.nil?
57
+ event.user_intent = redact_string(worker, T.must(event.user_intent))
58
+ end
59
+ event.response = deep_map(event.response, &redacter)
60
+ event.identify_data = deep_map(event.identify_data, &redacter)
61
+ event.error = deep_map(event.error, &redacter)
62
+ event
63
+ rescue StringRedactionFailed
64
+ Log.warn(
65
+ "redact_sensitive_information raised, timed out or returned a non-String; " \
66
+ "event dropped so nothing goes out unredacted"
67
+ )
68
+ nil
69
+ ensure
70
+ worker&.close
71
+ end
72
+
73
+ sig { params(worker: Hooks::Worker, string: String).returns(String).checked(:tests) }
74
+ def self.redact_string(worker, string)
75
+ result = worker.call(string)
76
+ raise StringRedactionFailed unless result.is_a?(String)
77
+
78
+ result
79
+ end
80
+ private_class_method :redact_string
81
+
82
+ sig { params(value: T.untyped, block: T.proc.params(arg: String).returns(String)).returns(T.untyped).checked(:tests) }
83
+ def self.deep_map(value, &block)
84
+ case value
85
+ when Hash
86
+ value.each_with_object({}) { |(k, v), acc| acc[k] = deep_map(v, &block) }
87
+ when Array
88
+ value.map { |v| deep_map(v, &block) }
89
+ when String
90
+ block.call(value)
91
+ else
92
+ value
93
+ end
94
+ end
95
+ private_class_method :deep_map
96
+ private_constant :StringRedactionFailed
97
+
98
+ sig { params(event: UnredactedEvent, original: T::Hash[Symbol, T.untyped]).returns(UnredactedEvent) }
99
+ def self.restore(event, original)
100
+ original.each { |field, value| event.public_send(:"#{field}=", value) }
101
+ event
102
+ end
103
+ private_class_method :restore
104
+
105
+ sig { params(event: UnredactedEvent).returns(UnredactedEvent) }
106
+ def self.warn_detached(event)
107
+ Log.warn(
108
+ "redact_event hook returned a new object instead of mutating and returning the event it was " \
109
+ "given. Every field it did not set was dropped. Mutate and return the same UnredactedEvent."
110
+ )
111
+ event
112
+ end
113
+ private_class_method :warn_detached
114
+ end
115
+ end
@@ -0,0 +1,147 @@
1
+ # typed: true
2
+
3
+ require_relative "clock"
4
+ require_relative "log"
5
+ require_relative "private_members"
6
+
7
+ module AgentCat
8
+ # Events for `tools/call` requests the `mcp` gem answers before the tool runs (as in
9
+ # TS): a name no tool has ("Tool not found", a JSON-RPC error) and arguments
10
+ # that fail its required or schema check (an isError result). The TS SDK sees these
11
+ # because it wraps the whole `tools/call` handler; the gem has no public seam for that,
12
+ # so `ServerHook` is prepended to the server's singleton class over its private
13
+ # `call_tool` (`PrivateMembers::SERVER_CALL_TOOL`).
14
+ #
15
+ # A call AgentCat's interceptor ran for is left alone: that call has its event already.
16
+ module RejectedCalls
17
+ extend T::Sig
18
+
19
+ # One `tools/call` being watched.
20
+ Watch = Struct.new(:interceptor, :tool, :request, :options, :server, :started_at)
21
+
22
+ module ServerHook
23
+ private
24
+
25
+ # Same signature as the gem's `call_tool(request, session:, related_request_id:, ...)`;
26
+ # the keywords differ by gem version, so they pass through untouched.
27
+ def call_tool(request, **options)
28
+ AgentCat::RejectedCalls.around(self, request, options) { super(request, **options) }
29
+ end
30
+ end
31
+
32
+ class << self
33
+ extend T::Sig
34
+
35
+ # Prepends `ServerHook` once per server. false when the gem has no `call_tool`.
36
+ sig { params(server: T.untyped).returns(T::Boolean) }
37
+ def install(server)
38
+ return false unless PrivateMembers.verify(PrivateMembers::SERVER_CALL_TOOL)
39
+
40
+ singleton = server.singleton_class
41
+ singleton.prepend(ServerHook) unless singleton.ancestors.include?(ServerHook)
42
+ true
43
+ rescue => e
44
+ Log.warn("AgentCat cannot watch the calls the mcp gem rejects: #{e.class}")
45
+ false
46
+ end
47
+
48
+ # Runs the gem's `call_tool` and records the call when the gem turned it away. The
49
+ # gem's result and exception always reach the client as the gem made them, apart
50
+ # from the mint-back on an isError result.
51
+ sig { params(server: T.untyped, request: T.untyped, options: T::Hash[Symbol, T.untyped], block: T.proc.returns(T.untyped)).returns(T.untyped) }
52
+ def around(server, request, options, &block)
53
+ watch = watch(server, request, options)
54
+ return yield if watch.nil?
55
+
56
+ previous = Thread.current[Interceptor::RAN_KEY]
57
+ Thread.current[Interceptor::RAN_KEY] = false
58
+ ran = T.let(nil, T.nilable(T::Boolean))
59
+ begin
60
+ result = yield
61
+ rescue => e
62
+ ran = !!Thread.current[Interceptor::RAN_KEY]
63
+ record(watch, error: e) unless ran || cancelled?(e)
64
+ raise
65
+ ensure
66
+ ran = !!Thread.current[Interceptor::RAN_KEY] if ran.nil?
67
+ Thread.current[Interceptor::RAN_KEY] = previous
68
+ end
69
+ return result if ran || ErrorCapture.capture_result(result).nil?
70
+
71
+ record(watch, result: result)
72
+ end
73
+
74
+ private
75
+
76
+ # nil when this call isn't AgentCat's to record: tracing off, the feature off, the
77
+ # server not tracked, or a tool AgentCat hasn't instrumented.
78
+ sig { params(server: T.untyped, request: T.untyped, options: T::Hash[Symbol, T.untyped]).returns(T.nilable(Watch)) }
79
+ def watch(server, request, options)
80
+ return nil unless PrivateMembers.enabled?(PrivateMembers::SERVER_CALL_TOOL.feature)
81
+
82
+ tracker = AgentCat.tracker_for(server)
83
+ return nil if tracker.nil? || !tracker.options.enable_tracing
84
+ return nil unless request.is_a?(Hash)
85
+
86
+ name = request.key?(:name) ? request[:name] : request["name"]
87
+ tool = tracker.adapter.tool_named(name)
88
+ interceptor = tracker.interceptor_for(tool, name)
89
+ return nil if interceptor.nil?
90
+
91
+ Watch.new(interceptor, tool, request, options, server, Clock.monotonic_now)
92
+ rescue => e
93
+ AgentCat.logger.debug { "RejectedCalls.watch failed: #{e.class}: #{e.message}" }
94
+ nil
95
+ end
96
+
97
+ # Never raises: a failure here costs the event, never the gem's answer.
98
+ sig { params(watch: Watch, result: T.untyped, error: T.nilable(StandardError)).returns(T.untyped) }
99
+ def record(watch, result: nil, error: nil)
100
+ request = watch.request
101
+ arguments = request.key?(:arguments) ? request[:arguments] : request["arguments"]
102
+ watch.interceptor.record_rejected(arguments || {}, server_context(watch), started_at: watch.started_at, result: result, error: error)
103
+ rescue => e
104
+ Log.error("could not record the rejected call of a tool: #{e.class}; the event is lost")
105
+ AgentCat.logger.debug { "RejectedCalls.record failed: #{e.class}: #{e.message}" }
106
+ result
107
+ end
108
+
109
+ # A real `MCP::ServerContext`, built like the gem builds the tool's own (its
110
+ # `server_context_with_meta`), so the event reads the client, protocol version,
111
+ # request id and `_meta` the same way. Only the keywords this gem version takes.
112
+ sig { params(watch: Watch).returns(T.untyped) }
113
+ def server_context(watch)
114
+ context_class = Object.const_get("MCP::ServerContext")
115
+ accepted = context_class.instance_method(:initialize).parameters.map { |_type, name| name }
116
+ options = watch.options
117
+ keywords = {
118
+ progress: nil,
119
+ notification_target: options[:session],
120
+ related_request_id: options[:related_request_id],
121
+ cancellation: options[:cancellation],
122
+ envelope: options[:envelope]
123
+ }.slice(*accepted)
124
+ context_class.new(context_with_meta(watch.server.server_context, watch.request), **keywords)
125
+ end
126
+
127
+ sig { params(base: T.untyped, request: T::Hash[T.untyped, T.untyped]).returns(T.untyped) }
128
+ def context_with_meta(base, request)
129
+ meta = request[:_meta]
130
+ if meta && base.is_a?(Hash)
131
+ base.merge(_meta: meta)
132
+ elsif meta && base.nil?
133
+ {_meta: meta}
134
+ else
135
+ base
136
+ end
137
+ end
138
+
139
+ # The gem's cancellation signal answers nothing (MCP cancellation spec), so it is
140
+ # not a rejection.
141
+ sig { params(error: StandardError).returns(T::Boolean) }
142
+ def cancelled?(error)
143
+ error.class.ancestors.any? { |ancestor| ancestor.name == "MCP::CancelledError" }
144
+ end
145
+ end
146
+ end
147
+ end