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,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
@@ -0,0 +1,201 @@
1
+ # typed: true
2
+
3
+ require_relative "interceptor"
4
+ require_relative "schema/prompts"
5
+
6
+ module AgentCat
7
+ # Installs AgentCat instrumentation on one server through its adapter:
8
+ # registers the `get_more_tools` helper, injects the AgentCat parameters into
9
+ # every tool schema and intercepts every tool call.
10
+ class Tracker
11
+ extend T::Sig
12
+
13
+ GET_MORE_TOOLS = "get_more_tools"
14
+
15
+ sig { returns(T.untyped) }
16
+ attr_reader :adapter
17
+
18
+ sig { returns(T.nilable(String)) }
19
+ attr_reader :project_id
20
+
21
+ sig { returns(AgentCat::Options) }
22
+ attr_reader :options
23
+
24
+ sig { params(adapter: T.untyped, project_id: T.nilable(String), options: AgentCat::Options).void }
25
+ def initialize(adapter:, project_id:, options:)
26
+ @adapter = adapter
27
+ @project_id = project_id
28
+ @options = options
29
+ @reported_collisions = T.let(Set.new, T::Set[[String, String]])
30
+ # handle => its Interceptor, for the calls the gem rejects before the handle runs.
31
+ @interceptors = T.let({}.compare_by_identity, T::Hash[AgentCat::ToolHandle, Interceptor])
32
+ @interceptors_mutex = T.let(Mutex.new, Mutex)
33
+ end
34
+
35
+ sig { returns(T.self_type) }
36
+ def install!
37
+ warn_if_stateless_without_identify
38
+ if options.enable_report_missing
39
+ # A host-defined get_more_tools keeps its own params, so we need to know
40
+ # ownership before registering, not just match by name afterward.
41
+ @registered_get_more_tools = T.let(adapter.tool_handles.none? { |handle| handle.name == GET_MORE_TOOLS }, T.nilable(T::Boolean))
42
+ register_get_more_tools
43
+ end
44
+ sync!
45
+ adapter.before_dispatch { sync! }
46
+ adapter.watch_rejected_calls
47
+ self
48
+ end
49
+
50
+ sig { returns(T::Hash[Symbol, T.untyped]) }
51
+ def server_info
52
+ @server_info ||= adapter.server_info
53
+ end
54
+
55
+ # `[name, description, schema_opts]` triples added to every tool schema and stripped
56
+ # before the tool runs. Same order and requiredness as the Go/TS SDKs: handles first
57
+ # (`session_id`, `agent_id`), then `context`, all three listed as required.
58
+ # `enable_tracing: false` drops the handles, `enable_tool_call_context: false` drops
59
+ # `context`. Required
60
+ # is soft (see `ToolHandle#add_input_parameter`): it nudges the agent to fill them in,
61
+ # but a call without them still runs. `placeholder` is what the `mcp` gem's own
62
+ # required check gets in place of a missing one - `start` for `session_id` so it
63
+ # also passes the pattern.
64
+ sig { returns(T::Array[[String, String, T::Hash[Symbol, T.untyped]]]) }
65
+ def injected_parameters
66
+ @injected_parameters ||= begin
67
+ params = T.let([], T::Array[[String, String, T::Hash[Symbol, T.untyped]]])
68
+ if options.enable_tracing
69
+ unless options.host_managed_sessions? || options.stateless?
70
+ params << ["session_id", Schema::SESSION_ID_DESCRIPTION, {required: true, pattern: Schema::SESSION_ID_PATTERN, placeholder: "start"}]
71
+ end
72
+ params << ["agent_id", Schema::AGENT_ID_DESCRIPTION, {required: true}] if options.enable_agent_tracking
73
+ end
74
+ params << ["context", options.context_description, {required: true}] if options.enable_tool_call_context
75
+ params
76
+ end
77
+ end
78
+
79
+ sig { returns(T::Array[String]) }
80
+ def injected_parameter_names
81
+ @injected_parameter_names ||= injected_parameters.map(&:first)
82
+ end
83
+
84
+ # The interceptor that records a call to `tool` the gem rejected before it ran: the
85
+ # handle's own, or for no tool at all (an unknown name) a new one that owns every
86
+ # injected parameter, like TS. nil for a tool AgentCat hasn't instrumented.
87
+ sig { params(tool: T.untyped, name: T.untyped).returns(T.nilable(Interceptor)) }
88
+ def interceptor_for(tool, name)
89
+ return Interceptor.new(handle: nil, tracker: self, tool_name: name.is_a?(String) ? name : nil) if tool.nil?
90
+ return nil unless tool.is_a?(AgentCat::ToolHandle)
91
+
92
+ @interceptors_mutex.synchronize { @interceptors[tool] }
93
+ end
94
+
95
+ private
96
+
97
+ # Instruments every tool the adapter currently knows about. `instrument` is a no-op on
98
+ # a handle it has already wrapped, so calling this again after the host registers more
99
+ # tools only picks up the new ones. Run once at `install!` time and again right before
100
+ # any request that needs it (`adapter.before_dispatch`), so a tool the host defines
101
+ # after `track()` is instrumented by the time an agent discovers or calls it — even on
102
+ # a server instance built fresh per request, whose first request is a direct
103
+ # `tools/call` with no `tools/list` before it.
104
+ sig { void }
105
+ def sync!
106
+ adapter.tool_handles.each { |handle| instrument(handle) }
107
+ end
108
+
109
+ sig { params(handle: AgentCat::ToolHandle).void }
110
+ def instrument(handle)
111
+ return if handle.intercepted?
112
+
113
+ owned = owned_parameters_for(handle)
114
+ injected_parameters.each do |name, description, schema_opts|
115
+ handle.add_input_parameter(name, description: description, **T.unsafe(schema_opts)) if owned.include?(name)
116
+ end
117
+ # Nothing ever fills `mcp_session` with tracing off, so don't advertise it.
118
+ handle.add_output_parameter(:mcp_session, mcp_session_output_schema) if options.enable_tracing
119
+ interceptor = Interceptor.new(handle: handle, tracker: self, owned_parameters: owned)
120
+ @interceptors_mutex.synchronize { @interceptors[handle] = interceptor }
121
+ handle.intercept { |arguments, server_context, original| interceptor.call(arguments, server_context, original) }
122
+ end
123
+
124
+ # What `Interceptor` actually puts in `structuredContent.mcp_session` at runtime,
125
+ # declared up front so a client validating against the output schema doesn't see an
126
+ # undeclared field. Hook mode drops `status` — a host-managed session never gets one.
127
+ sig { returns(T::Hash[Symbol, T.untyped]) }
128
+ def mcp_session_output_schema
129
+ hook_mode = options.host_managed_sessions?
130
+ properties = {}
131
+ properties[:session_id] = {type: "string", description: Schema::MCP_SESSION_SESSION_ID_DESCRIPTION} unless hook_mode
132
+ properties[:agent_id] = {type: "string", description: Schema::MCP_SESSION_AGENT_ID_DESCRIPTION}
133
+ properties[:status] = {type: "string", enum: %w[issued active unrecognized], description: Schema::MCP_SESSION_STATUS_DESCRIPTION} unless hook_mode
134
+
135
+ {
136
+ type: "object",
137
+ description: hook_mode ? Schema::MCP_SESSION_FIELD_DESCRIPTION_HOOK_MODE : Schema::MCP_SESSION_FIELD_DESCRIPTION,
138
+ properties: properties
139
+ }
140
+ end
141
+
142
+ # A tool that already declares a parameter under one of our names owns it outright:
143
+ # AgentCat neither injects its own copy, reads the value, nor strips it from the call,
144
+ # so the host's argument reaches the host's handler untouched. The `get_more_tools` we
145
+ # registered ourselves is the exception — the `context` in its schema is ours.
146
+ #
147
+ # A `oneOf`/`allOf`/`anyOf` schema gets nothing injected at all, silently: there's no
148
+ # single `properties` object to add to, and no per-parameter "collision" to report,
149
+ # since the tool never declared these names - injection is just structurally
150
+ # impossible here, matching the Python SDK.
151
+ sig { params(handle: AgentCat::ToolHandle).returns(T::Array[String]) }
152
+ def owned_parameters_for(handle)
153
+ # Its `context` is the whole point of the tool, so it stays ours (read into the event,
154
+ # stripped before the handler) even with `enable_tool_call_context: false`.
155
+ return injected_parameter_names | ["context"] if @registered_get_more_tools && handle.name == GET_MORE_TOOLS
156
+ return [] if handle.composed_input_schema?
157
+
158
+ collided, owned = injected_parameter_names.partition { |name| handle.input_parameter?(name) }
159
+ collided.each { |name| report_collision(handle.name, name) }
160
+ owned
161
+ end
162
+
163
+ # Once per tool and parameter (and, through `Log`, once a minute across the servers of
164
+ # a per-request `track`). A `session_id` collision costs correlation for every call
165
+ # to that tool, the others cost one attribute, hence the different levels.
166
+ sig { params(tool_name: String, parameter: String).void }
167
+ def report_collision(tool_name, parameter)
168
+ return unless @reported_collisions.add?([tool_name, parameter])
169
+
170
+ preamble = "tool #{tool_name.inspect} already declares a #{parameter.inspect} parameter, so AgentCat left it to the tool"
171
+ if parameter == "session_id"
172
+ Log.error("#{preamble}; its calls publish without a session id. Set the resolve_session_id option to keep them correlated.")
173
+ else
174
+ Log.warn("#{preamble}; its calls publish without #{parameter}.")
175
+ end
176
+ end
177
+
178
+ sig { void }
179
+ def warn_if_stateless_without_identify
180
+ return unless options.stateless? && options.identify.nil?
181
+
182
+ Log.warn("stateless mode is enabled without an identify hook; every event will be its own anonymous session")
183
+ end
184
+
185
+ sig { void }
186
+ def register_get_more_tools
187
+ adapter.register_tool(
188
+ name: GET_MORE_TOOLS,
189
+ description: Schema::GET_MORE_TOOLS_DESCRIPTION,
190
+ input_schema: {
191
+ type: "object",
192
+ properties: {context: {type: "string", description: Schema::GET_MORE_TOOLS_CONTEXT_DESCRIPTION}},
193
+ required: ["context"]
194
+ },
195
+ # Read-only like the Go/Python SDKs: it only reports a gap, never changes server state.
196
+ annotations: {read_only_hint: true},
197
+ call_fn: ->(_arguments, _server_context) { {content: [{type: "text", text: Schema::GET_MORE_TOOLS_PROMPT}]} }
198
+ )
199
+ end
200
+ end
201
+ end