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.
- checksums.yaml +4 -4
- data/LICENSE +2 -11
- data/README.md +265 -20
- data/lib/agentcat/adapters/base.rb +73 -0
- data/lib/agentcat/adapters/official.rb +194 -0
- data/lib/agentcat/client.rb +171 -0
- data/lib/agentcat/clock.rb +16 -0
- data/lib/agentcat/custom_event.rb +215 -0
- data/lib/agentcat/delivery.rb +58 -0
- data/lib/agentcat/diagnostics.rb +434 -0
- data/lib/agentcat/error_capture.rb +117 -0
- data/lib/agentcat/event_id.rb +19 -0
- data/lib/agentcat/event_pipeline.rb +82 -0
- data/lib/agentcat/event_queue.rb +151 -0
- data/lib/agentcat/exporters/base.rb +135 -0
- data/lib/agentcat/exporters/datadog.rb +137 -0
- data/lib/agentcat/exporters/otlp.rb +157 -0
- data/lib/agentcat/exporters/posthog.rb +185 -0
- data/lib/agentcat/exporters/sentry.rb +242 -0
- data/lib/agentcat/exporters/trace_context.rb +79 -0
- data/lib/agentcat/exporters.rb +108 -0
- data/lib/agentcat/fork_safety.rb +30 -0
- data/lib/agentcat/hooks.rb +190 -0
- data/lib/agentcat/http_post.rb +61 -0
- data/lib/agentcat/interceptor.rb +711 -0
- data/lib/agentcat/log.rb +80 -0
- data/lib/agentcat/options.rb +313 -0
- data/lib/agentcat/payload_limits.rb +71 -0
- data/lib/agentcat/private_members.rb +271 -0
- data/lib/agentcat/redaction.rb +115 -0
- data/lib/agentcat/rejected_calls.rb +147 -0
- data/lib/agentcat/request_context.rb +266 -0
- data/lib/agentcat/sanitization.rb +191 -0
- data/lib/agentcat/schema/prompts.rb +44 -0
- data/lib/agentcat/session_manager.rb +83 -0
- data/lib/agentcat/tags.rb +61 -0
- data/lib/agentcat/test_mode.rb +86 -0
- data/lib/agentcat/testing.rb +153 -0
- data/lib/agentcat/text.rb +68 -0
- data/lib/agentcat/token_estimate.rb +98 -0
- data/lib/agentcat/tool_call.rb +129 -0
- data/lib/agentcat/tool_handle.rb +289 -0
- data/lib/agentcat/tracker.rb +201 -0
- data/lib/agentcat/truncation.rb +265 -0
- data/lib/agentcat/unredacted_event.rb +155 -0
- data/lib/agentcat/user_identity.rb +11 -0
- data/lib/agentcat/version.rb +2 -2
- data/lib/agentcat.rb +391 -21
- metadata +193 -16
- 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
|