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.
- checksums.yaml +4 -4
- data/LICENSE +2 -11
- data/README.md +265 -20
- data/lib/agentcat/adapters/base.rb +98 -0
- data/lib/agentcat/adapters/official.rb +277 -0
- data/lib/agentcat/client.rb +189 -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 +728 -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 +286 -0
- data/lib/agentcat/redaction.rb +176 -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/server_info.rb +280 -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 +204 -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 +393 -21
- metadata +194 -16
- data/agentcat.gemspec +0 -30
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
# typed: true
|
|
2
|
+
|
|
3
|
+
require_relative "private_members"
|
|
4
|
+
|
|
5
|
+
module AgentCat
|
|
6
|
+
# The per-request HTTP metadata the published event carries under
|
|
7
|
+
# `parameters.extra` — the incoming request's headers and full URL, shaped as
|
|
8
|
+
# `{requestInfo: {headers: {...}, url: "..."}}` to match the TypeScript v1 and
|
|
9
|
+
# Python SDKs (`event.parameters.extra.requestInfo`).
|
|
10
|
+
#
|
|
11
|
+
# Why this exists: AgentCat reads client-identifying headers (User-Agent and
|
|
12
|
+
# friends) to tell which agent harness made a call — "Claude Code", "Codex",
|
|
13
|
+
# a bare Cursor, a browser — including on stateless HTTP servers where the
|
|
14
|
+
# client never declared itself in `_meta`. The reference SDKs get the headers
|
|
15
|
+
# for free because their MCP frameworks hand the request handler the transport
|
|
16
|
+
# request; the `mcp` gem does not, so `Server#handle` and `server_context`
|
|
17
|
+
# never see them. The only seam is the transport's own Rack entry point, so
|
|
18
|
+
# `TransportHook` (below) captures the env there and `capture`/`restore` make
|
|
19
|
+
# it ambient for exactly the duration of that request.
|
|
20
|
+
#
|
|
21
|
+
# `headers_from_env` mirrors Rack's own env->header rules (`HTTP_*` plus
|
|
22
|
+
# `CONTENT_TYPE`/`CONTENT_LENGTH`), so a Rack server's headers come out the same
|
|
23
|
+
# way every other Rack consumer reads them. Names are lower case and each value is
|
|
24
|
+
# one string: repeated values are joined with ", ", the way a web server joins
|
|
25
|
+
# repeated request headers.
|
|
26
|
+
#
|
|
27
|
+
# stdio has no request to read, so nothing is captured and the event's `extra`
|
|
28
|
+
# has no `requestInfo` — again matching the reference SDKs, which only populate
|
|
29
|
+
# `requestInfo` on HTTP transports.
|
|
30
|
+
module RequestContext
|
|
31
|
+
# Thread#[] is fiber-local, so a request handled on its own fiber (Falcon,
|
|
32
|
+
# async Puma) can never read another fiber's headers.
|
|
33
|
+
KEY = :agentcat_request_extra
|
|
34
|
+
# The Rack env of the same request, for `ToolCall#request`.
|
|
35
|
+
ENV_KEY = :agentcat_request_env
|
|
36
|
+
|
|
37
|
+
# Guards the one-time class patch. Module-level (its own singleton would be the
|
|
38
|
+
# wrong lock to reason about).
|
|
39
|
+
INSTALL_MUTEX = T.let(Mutex.new, Mutex)
|
|
40
|
+
|
|
41
|
+
class << self
|
|
42
|
+
extend T::Sig
|
|
43
|
+
|
|
44
|
+
# Prepends `TransportHook` to the streamable HTTP transport class. Idempotent
|
|
45
|
+
# and process-wide, with a fast path once it has succeeded. Called from
|
|
46
|
+
# `AgentCat.track` and retried on every dispatch, so a process that loads the
|
|
47
|
+
# HTTP transport *after* `track` still starts capturing headers (from the next
|
|
48
|
+
# request on). A no-op for a process without the class or without `rack`.
|
|
49
|
+
sig { void }
|
|
50
|
+
def install!
|
|
51
|
+
return if @installed
|
|
52
|
+
|
|
53
|
+
transport = transport_class
|
|
54
|
+
return if transport.nil?
|
|
55
|
+
return unless PrivateMembers.verify(PrivateMembers::STREAMABLE_HTTP_TRANSPORT_CALL)
|
|
56
|
+
|
|
57
|
+
INSTALL_MUTEX.synchronize do
|
|
58
|
+
transport.prepend(TransportHook) unless transport.ancestors.include?(TransportHook)
|
|
59
|
+
@installed = true
|
|
60
|
+
end
|
|
61
|
+
end
|
|
62
|
+
|
|
63
|
+
# The `parameters.extra` hash for one Rack env, or nil when there's nothing to
|
|
64
|
+
# report. Never raises: a malformed env (an older Rack, a non-Hash) is a miss,
|
|
65
|
+
# not a broken tool call.
|
|
66
|
+
sig { params(env: T.untyped).returns(T.nilable(T::Hash[String, T.untyped])) }
|
|
67
|
+
def extra_from_env(env)
|
|
68
|
+
return nil unless env.is_a?(Hash)
|
|
69
|
+
|
|
70
|
+
headers = headers_from_env(env)
|
|
71
|
+
url = url_from_env(env)
|
|
72
|
+
return nil if headers.empty? && url.nil?
|
|
73
|
+
|
|
74
|
+
info = T.let({"headers" => headers}, T::Hash[String, T.untyped])
|
|
75
|
+
info["url"] = url if url
|
|
76
|
+
{"requestInfo" => info}
|
|
77
|
+
end
|
|
78
|
+
|
|
79
|
+
# Makes `extra` (and the Rack `env` it came from) ambient and returns whatever was
|
|
80
|
+
# ambient before, so a nested or re-entrant dispatch restores correctly. Pass the
|
|
81
|
+
# return value to `restore`.
|
|
82
|
+
sig { params(extra: T.nilable(T::Hash[String, T.untyped]), env: T.untyped).returns(T.untyped) }
|
|
83
|
+
def capture(extra, env = nil)
|
|
84
|
+
previous = [Thread.current[KEY], Thread.current[ENV_KEY]]
|
|
85
|
+
Thread.current[KEY] = extra
|
|
86
|
+
Thread.current[ENV_KEY] = env
|
|
87
|
+
previous
|
|
88
|
+
end
|
|
89
|
+
|
|
90
|
+
sig { params(previous: T.untyped).void }
|
|
91
|
+
def restore(previous)
|
|
92
|
+
extra, env = previous.is_a?(Array) ? previous : [previous, nil]
|
|
93
|
+
Thread.current[KEY] = extra
|
|
94
|
+
Thread.current[ENV_KEY] = env
|
|
95
|
+
end
|
|
96
|
+
|
|
97
|
+
# The ambient `extra` for the request being handled on this fiber right now, or
|
|
98
|
+
# nil outside a captured HTTP request (stdio, a background call, tests).
|
|
99
|
+
sig { returns(T.nilable(T::Hash[String, T.untyped])) }
|
|
100
|
+
def current
|
|
101
|
+
value = Thread.current[KEY]
|
|
102
|
+
value.is_a?(Hash) ? value : nil
|
|
103
|
+
end
|
|
104
|
+
|
|
105
|
+
# The Rack env of the request being handled on this fiber right now, or nil
|
|
106
|
+
# outside a captured HTTP request.
|
|
107
|
+
sig { returns(T.untyped) }
|
|
108
|
+
def current_env
|
|
109
|
+
Thread.current[ENV_KEY]
|
|
110
|
+
end
|
|
111
|
+
|
|
112
|
+
# Wraps a deferred Rack body (`body.call(stream)`) so the request's `extra` is
|
|
113
|
+
# ambient for exactly the duration of that dispatch. Deliberately a plain `proc`,
|
|
114
|
+
# not a lambda or a delegator: the web server decides whether a response body is a
|
|
115
|
+
# streaming/callable one by `respond_to?(:call)`, so the wrapper has to look like
|
|
116
|
+
# the original body and nothing else.
|
|
117
|
+
sig { params(body: T.untyped, extra: T::Hash[String, T.untyped], env: T.untyped).returns(Proc) }
|
|
118
|
+
def scoped_body(body, extra, env = nil)
|
|
119
|
+
proc do |stream|
|
|
120
|
+
previous = capture(extra, env)
|
|
121
|
+
begin
|
|
122
|
+
body.call(stream)
|
|
123
|
+
ensure
|
|
124
|
+
restore(previous)
|
|
125
|
+
end
|
|
126
|
+
end
|
|
127
|
+
end
|
|
128
|
+
|
|
129
|
+
private
|
|
130
|
+
|
|
131
|
+
# The `mcp` gem autoloads the transport, and loading it raises LoadError when the
|
|
132
|
+
# bundle has no `rack` (the gem doesn't depend on it). A stdio server has no rack
|
|
133
|
+
# and no headers to capture, so that is a miss, not a reason for `track` to raise.
|
|
134
|
+
# The miss is remembered: a failed autoload would try to require rack again on
|
|
135
|
+
# every dispatch.
|
|
136
|
+
sig { returns(T.untyped) }
|
|
137
|
+
def transport_class
|
|
138
|
+
return nil if @transport_unloadable
|
|
139
|
+
return nil unless defined?(::MCP::Server::Transports::StreamableHTTPTransport)
|
|
140
|
+
|
|
141
|
+
::MCP::Server::Transports::StreamableHTTPTransport
|
|
142
|
+
rescue LoadError
|
|
143
|
+
@transport_unloadable = true
|
|
144
|
+
nil
|
|
145
|
+
end
|
|
146
|
+
|
|
147
|
+
sig { params(env: T::Hash[T.untyped, T.untyped]).returns(T::Hash[String, String]) }
|
|
148
|
+
def headers_from_env(env)
|
|
149
|
+
headers = T.let({}, T::Hash[String, String])
|
|
150
|
+
env.each do |raw_key, raw_value|
|
|
151
|
+
name = header_name(raw_key.to_s)
|
|
152
|
+
next if name.nil?
|
|
153
|
+
|
|
154
|
+
value = normalize_value(raw_value)
|
|
155
|
+
next if value.nil?
|
|
156
|
+
|
|
157
|
+
headers[name] = headers.key?(name) ? "#{headers[name]}, #{value}" : value
|
|
158
|
+
end
|
|
159
|
+
headers
|
|
160
|
+
end
|
|
161
|
+
|
|
162
|
+
# The full URL as the client asked for it, like PHP's `HttpContext::url`: the
|
|
163
|
+
# scheme, the `Host` header (else Rack's `SERVER_NAME`/`SERVER_PORT`) and the raw
|
|
164
|
+
# request URI, query as sent. nil without a host: no URL is made up.
|
|
165
|
+
sig { params(env: T::Hash[T.untyped, T.untyped]).returns(T.nilable(String)) }
|
|
166
|
+
def url_from_env(env)
|
|
167
|
+
scheme = url_scheme(env)
|
|
168
|
+
host = url_host(env, scheme)
|
|
169
|
+
return nil if host.nil?
|
|
170
|
+
|
|
171
|
+
"#{scheme}://#{host}#{request_uri(env)}"
|
|
172
|
+
rescue
|
|
173
|
+
nil
|
|
174
|
+
end
|
|
175
|
+
|
|
176
|
+
sig { params(env: T::Hash[T.untyped, T.untyped]).returns(String) }
|
|
177
|
+
def url_scheme(env)
|
|
178
|
+
scheme = env["rack.url_scheme"]
|
|
179
|
+
return scheme if scheme.is_a?(String) && !scheme.empty?
|
|
180
|
+
|
|
181
|
+
https = env["HTTPS"]
|
|
182
|
+
(https.is_a?(String) && !https.empty? && https.downcase != "off") ? "https" : "http"
|
|
183
|
+
end
|
|
184
|
+
|
|
185
|
+
sig { params(env: T::Hash[T.untyped, T.untyped], scheme: String).returns(T.nilable(String)) }
|
|
186
|
+
def url_host(env, scheme)
|
|
187
|
+
host = env["HTTP_HOST"]
|
|
188
|
+
return host if host.is_a?(String) && !host.empty?
|
|
189
|
+
|
|
190
|
+
name = env["SERVER_NAME"]
|
|
191
|
+
return nil unless name.is_a?(String) && !name.empty?
|
|
192
|
+
|
|
193
|
+
port = env["SERVER_PORT"].to_s
|
|
194
|
+
default_port = (scheme == "https") ? "443" : "80"
|
|
195
|
+
(port.empty? || port == default_port) ? name : "#{name}:#{port}"
|
|
196
|
+
end
|
|
197
|
+
|
|
198
|
+
# `REQUEST_URI` is not in the Rack spec, but Puma, WEBrick and Unicorn set it to
|
|
199
|
+
# the raw request target. Without it, Rack's own parts: script, path, query.
|
|
200
|
+
sig { params(env: T::Hash[T.untyped, T.untyped]).returns(String) }
|
|
201
|
+
def request_uri(env)
|
|
202
|
+
raw = env["REQUEST_URI"]
|
|
203
|
+
return raw if raw.is_a?(String) && raw.start_with?("/")
|
|
204
|
+
|
|
205
|
+
path = "#{env["SCRIPT_NAME"]}#{env["PATH_INFO"]}"
|
|
206
|
+
query = env["QUERY_STRING"].to_s
|
|
207
|
+
query.empty? ? path : "#{path}?#{query}"
|
|
208
|
+
end
|
|
209
|
+
|
|
210
|
+
# `HTTP_`-prefixed keys are the Rack convention for request headers; the two
|
|
211
|
+
# content keys are the non-prefixed exceptions Rack itself defines.
|
|
212
|
+
sig { params(key: String).returns(T.nilable(String)) }
|
|
213
|
+
def header_name(key)
|
|
214
|
+
return key.delete_prefix("HTTP_").downcase.tr("_", "-") if key.start_with?("HTTP_")
|
|
215
|
+
return "content-type" if key == "CONTENT_TYPE"
|
|
216
|
+
return "content-length" if key == "CONTENT_LENGTH"
|
|
217
|
+
|
|
218
|
+
nil
|
|
219
|
+
end
|
|
220
|
+
|
|
221
|
+
sig { params(value: T.untyped).returns(T.nilable(String)) }
|
|
222
|
+
def normalize_value(value)
|
|
223
|
+
case value
|
|
224
|
+
when nil then nil
|
|
225
|
+
when String then value
|
|
226
|
+
when Array then value.join(", ")
|
|
227
|
+
else value.to_s
|
|
228
|
+
end
|
|
229
|
+
end
|
|
230
|
+
end
|
|
231
|
+
|
|
232
|
+
# Prepended to `MCP::Server::Transports::StreamableHTTPTransport`. `call(env)` is the
|
|
233
|
+
# transport's Rack entry point; every HTTP path (stateless modern, `initialize`, plain
|
|
234
|
+
# JSON) dispatches inside it, so the ambient headers are in scope when the interceptor
|
|
235
|
+
# builds the event. The sessionful streamable path is the exception: it hands back a
|
|
236
|
+
# *callable* Rack body (`proc { |stream| ... }`) that the web server invokes only after
|
|
237
|
+
# `call` has returned, so the eager capture is already gone by the time the tool runs.
|
|
238
|
+
# For that shape we re-scope the ambient around the body's own invocation — the wrapper
|
|
239
|
+
# is a plain `proc` too, so the server keeps treating the body exactly as before.
|
|
240
|
+
module TransportHook
|
|
241
|
+
extend T::Sig
|
|
242
|
+
|
|
243
|
+
sig { params(env: T.untyped).returns(T.untyped) }
|
|
244
|
+
def call(env)
|
|
245
|
+
# Feature off at run time (`PrivateMembers`): the request goes through untouched.
|
|
246
|
+
return super unless PrivateMembers.enabled?(PrivateMembers::STREAMABLE_HTTP_TRANSPORT_CALL.feature)
|
|
247
|
+
|
|
248
|
+
extra = AgentCat::RequestContext.extra_from_env(env)
|
|
249
|
+
previous = AgentCat::RequestContext.capture(extra, env)
|
|
250
|
+
|
|
251
|
+
result = begin
|
|
252
|
+
super
|
|
253
|
+
ensure
|
|
254
|
+
AgentCat::RequestContext.restore(previous)
|
|
255
|
+
end
|
|
256
|
+
|
|
257
|
+
# Only ever reshape a plain Rack triple whose body is callable; anything else is
|
|
258
|
+
# handed back byte-for-byte, so the hook can't alter behavior on a gem version
|
|
259
|
+
# whose transport returns something we don't recognize.
|
|
260
|
+
return result if extra.nil? || !result.is_a?(Array) || result.size < 3 || !result[2].respond_to?(:call)
|
|
261
|
+
|
|
262
|
+
result.dup.tap { |rack_response| rack_response[2] = AgentCat::RequestContext.scoped_body(result[2], extra, env) }
|
|
263
|
+
end
|
|
264
|
+
end
|
|
265
|
+
end
|
|
266
|
+
end
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
# typed: true
|
|
2
|
+
|
|
3
|
+
require_relative "payload_limits"
|
|
4
|
+
require_relative "text"
|
|
5
|
+
|
|
6
|
+
module AgentCat
|
|
7
|
+
# Runs between the redaction hooks and truncation — same pipeline order as
|
|
8
|
+
# Go/Python/TS: redact_event -> per-string redact -> sanitize -> truncate -> deliver.
|
|
9
|
+
#
|
|
10
|
+
# Two things happen here, mirroring the Go SDK's internal/sanitization:
|
|
11
|
+
# 1. Content types AgentCat can't store (image, audio, binary resources) get
|
|
12
|
+
# swapped for explanatory text blocks.
|
|
13
|
+
# 2. Strings that look like base64 and are big enough to be an inline binary
|
|
14
|
+
# payload get replaced with a redaction marker. The scan is depth-capped
|
|
15
|
+
# and circular-safe so hostile input can't blow the stack.
|
|
16
|
+
#
|
|
17
|
+
# `scrub_event` is separate: it makes every string valid UTF-8 so JSON encoding can't
|
|
18
|
+
# fail. `EventPipeline` runs it before the redaction hooks and again before encoding.
|
|
19
|
+
#
|
|
20
|
+
# Mutates the event in place, never raises — a failure here just means the event
|
|
21
|
+
# ships unsanitized rather than not at all, same as Go/Python.
|
|
22
|
+
module Sanitization
|
|
23
|
+
extend T::Sig
|
|
24
|
+
|
|
25
|
+
IMAGE_REDACTED = "[image content redacted - not supported by AgentCat]"
|
|
26
|
+
AUDIO_REDACTED = "[audio content redacted - not supported by AgentCat]"
|
|
27
|
+
BINARY_RESOURCE_REDACTED = "[binary resource content redacted - not supported by AgentCat]"
|
|
28
|
+
BINARY_DATA_REDACTED = "[binary data redacted - not supported by AgentCat]"
|
|
29
|
+
UNSUPPORTED_TYPE_PATTERN = "[unsupported content type \"%s\" redacted - not supported by AgentCat]"
|
|
30
|
+
|
|
31
|
+
# Mirrors the Go/TS regex. Anchored, so it only matches a whole base64 payload.
|
|
32
|
+
BASE64_PATTERN = %r{\A[A-Za-z0-9+/\n\r]+=*\z}
|
|
33
|
+
|
|
34
|
+
sig { params(event: UnredactedEvent).void }
|
|
35
|
+
def self.sanitize_event(event)
|
|
36
|
+
event.response = sanitize_response(event.response) unless event.response.nil?
|
|
37
|
+
event.parameters = sanitize_value(event.parameters)
|
|
38
|
+
event.identify_data = sanitize_value(event.identify_data) if event.identify_data.is_a?(Hash)
|
|
39
|
+
event.error = sanitize_value(event.error) if event.error.is_a?(Hash)
|
|
40
|
+
event.properties = sanitize_value(event.properties) if event.properties.is_a?(Hash)
|
|
41
|
+
end
|
|
42
|
+
|
|
43
|
+
# Every string on the event (top-level fields, hash keys and values at any depth,
|
|
44
|
+
# tags, properties) becomes valid UTF-8: binary and malformed bytes turn into U+FFFD,
|
|
45
|
+
# so no string can make JSON encoding fail and lose the event. Containers are copied,
|
|
46
|
+
# never changed in place, so the caller's own objects stay as they were.
|
|
47
|
+
sig { params(event: UnredactedEvent).void }
|
|
48
|
+
def self.scrub_event(event)
|
|
49
|
+
UnredactedEvent.props.each_key do |name|
|
|
50
|
+
value = event.public_send(name)
|
|
51
|
+
next unless value.is_a?(String) || value.is_a?(Hash) || value.is_a?(Array)
|
|
52
|
+
|
|
53
|
+
event.public_send(:"#{name}=", scrub_value(value))
|
|
54
|
+
end
|
|
55
|
+
rescue => e
|
|
56
|
+
AgentCat.logger.debug { "UTF-8 scrub failed: #{e.class}: #{e.message}" }
|
|
57
|
+
end
|
|
58
|
+
|
|
59
|
+
sig do
|
|
60
|
+
params(
|
|
61
|
+
value: T.untyped,
|
|
62
|
+
depth: Integer,
|
|
63
|
+
seen: T.nilable(T::Set[Integer])
|
|
64
|
+
).returns(T.untyped)
|
|
65
|
+
end
|
|
66
|
+
def self.scrub_value(value, depth: 0, seen: nil)
|
|
67
|
+
seen ||= Set.new
|
|
68
|
+
case value
|
|
69
|
+
when String
|
|
70
|
+
Text.scrub(value)
|
|
71
|
+
when Hash
|
|
72
|
+
# A cycle or an absurd depth is left as is; `sanitize_value` marks it later.
|
|
73
|
+
return value if depth >= PayloadLimits::MAX_WALK_DEPTH || !seen.add?(value.object_id)
|
|
74
|
+
|
|
75
|
+
result = value.each_with_object({}) do |(key, item), acc|
|
|
76
|
+
acc[key.is_a?(String) ? Text.scrub(key) : key] = scrub_value(item, depth: depth + 1, seen: seen)
|
|
77
|
+
end
|
|
78
|
+
seen.delete(value.object_id)
|
|
79
|
+
result
|
|
80
|
+
when Array
|
|
81
|
+
return value if depth >= PayloadLimits::MAX_WALK_DEPTH || !seen.add?(value.object_id)
|
|
82
|
+
|
|
83
|
+
result = value.map { |item| scrub_value(item, depth: depth + 1, seen: seen) }
|
|
84
|
+
seen.delete(value.object_id)
|
|
85
|
+
result
|
|
86
|
+
else
|
|
87
|
+
value
|
|
88
|
+
end
|
|
89
|
+
end
|
|
90
|
+
|
|
91
|
+
sig { params(value: T.untyped).returns(T.untyped) }
|
|
92
|
+
def self.sanitize_response(value)
|
|
93
|
+
case value
|
|
94
|
+
when Hash
|
|
95
|
+
sanitize_response_hash(value)
|
|
96
|
+
when Array
|
|
97
|
+
value.map { |block| sanitize_content_block(block) }
|
|
98
|
+
else
|
|
99
|
+
value
|
|
100
|
+
end
|
|
101
|
+
end
|
|
102
|
+
|
|
103
|
+
sig { params(response: T::Hash[T.untyped, T.untyped]).returns(T::Hash[T.untyped, T.untyped]) }
|
|
104
|
+
def self.sanitize_response_hash(response)
|
|
105
|
+
content = response[:content] || response["content"]
|
|
106
|
+
if content.is_a?(Array)
|
|
107
|
+
response[:content] = content.map { |block| sanitize_content_block(block) }
|
|
108
|
+
response.delete("content") if response.key?("content")
|
|
109
|
+
end
|
|
110
|
+
structured = response[:structured_content] || response[:structuredContent] || response["structuredContent"]
|
|
111
|
+
if structured.is_a?(Hash)
|
|
112
|
+
response[:structuredContent] = sanitize_value(structured)
|
|
113
|
+
response.delete("structuredContent") if response.key?("structuredContent")
|
|
114
|
+
end
|
|
115
|
+
response
|
|
116
|
+
end
|
|
117
|
+
|
|
118
|
+
sig { params(block: T.untyped).returns(T.untyped) }
|
|
119
|
+
def self.sanitize_content_block(block)
|
|
120
|
+
return block unless block.is_a?(Hash)
|
|
121
|
+
|
|
122
|
+
type = block[:type] || block["type"]
|
|
123
|
+
case type
|
|
124
|
+
when "text", "resource_link"
|
|
125
|
+
block
|
|
126
|
+
when "image"
|
|
127
|
+
text_block(IMAGE_REDACTED)
|
|
128
|
+
when "audio"
|
|
129
|
+
text_block(AUDIO_REDACTED)
|
|
130
|
+
when "resource"
|
|
131
|
+
blob?(block) ? text_block(BINARY_RESOURCE_REDACTED) : block
|
|
132
|
+
else
|
|
133
|
+
text_block(format(UNSUPPORTED_TYPE_PATTERN, type.to_s))
|
|
134
|
+
end
|
|
135
|
+
end
|
|
136
|
+
|
|
137
|
+
# Depth- and identity-bounded so circular or absurdly deep structures still terminate.
|
|
138
|
+
sig do
|
|
139
|
+
params(
|
|
140
|
+
value: T.untyped,
|
|
141
|
+
depth: Integer,
|
|
142
|
+
seen: T.nilable(T::Set[Integer])
|
|
143
|
+
).returns(T.untyped)
|
|
144
|
+
end
|
|
145
|
+
def self.sanitize_value(value, depth: 0, seen: nil)
|
|
146
|
+
seen ||= Set.new
|
|
147
|
+
case value
|
|
148
|
+
when String
|
|
149
|
+
sanitize_string(value)
|
|
150
|
+
when Hash
|
|
151
|
+
return PayloadLimits::MAX_DEPTH_EXCEEDED_MARKER if depth >= AgentCat::PayloadLimits::MAX_WALK_DEPTH
|
|
152
|
+
return PayloadLimits::CIRCULAR_MARKER unless seen.add?(value.object_id)
|
|
153
|
+
|
|
154
|
+
value.each_with_object({}) do |(key, item), acc|
|
|
155
|
+
acc[key] = sanitize_value(item, depth: depth + 1, seen: seen)
|
|
156
|
+
end
|
|
157
|
+
when Array
|
|
158
|
+
return PayloadLimits::MAX_DEPTH_EXCEEDED_MARKER if depth >= AgentCat::PayloadLimits::MAX_WALK_DEPTH
|
|
159
|
+
return PayloadLimits::CIRCULAR_MARKER unless seen.add?(value.object_id)
|
|
160
|
+
|
|
161
|
+
value.map { |item| sanitize_value(item, depth: depth + 1, seen: seen) }
|
|
162
|
+
else
|
|
163
|
+
value
|
|
164
|
+
end
|
|
165
|
+
end
|
|
166
|
+
|
|
167
|
+
sig { params(string: String).returns(String) }
|
|
168
|
+
def self.sanitize_string(string)
|
|
169
|
+
return string if string.bytesize < AgentCat::PayloadLimits::BASE64_SIZE_GATE
|
|
170
|
+
|
|
171
|
+
BASE64_PATTERN.match?(string) ? BINARY_DATA_REDACTED : string
|
|
172
|
+
end
|
|
173
|
+
|
|
174
|
+
sig { params(text: String).returns(T::Hash[Symbol, String]) }
|
|
175
|
+
def self.text_block(text)
|
|
176
|
+
{type: "text", text: text}
|
|
177
|
+
end
|
|
178
|
+
|
|
179
|
+
# A "resource" content block wraps an `EmbeddedResourceContent`: {type: "resource",
|
|
180
|
+
# resource: {uri:, blob:|text:, mimeType:}}. `blob` lives two levels down, not on the
|
|
181
|
+
# block itself — checking `block[:blob]` directly never matches a real MCP resource
|
|
182
|
+
# block (only the pre-fix test's flattened, non-spec fixture), so binary resource data
|
|
183
|
+
# was never actually redacted on the real path.
|
|
184
|
+
sig { params(block: T::Hash[T.untyped, T.untyped]).returns(T::Boolean) }
|
|
185
|
+
def self.blob?(block)
|
|
186
|
+
resource = block[:resource] || block["resource"]
|
|
187
|
+
!!(resource.is_a?(Hash) && (resource.key?(:blob) || resource.key?("blob")))
|
|
188
|
+
end
|
|
189
|
+
private_class_method :blob?
|
|
190
|
+
end
|
|
191
|
+
end
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# typed: true
|
|
2
|
+
|
|
3
|
+
module AgentCat
|
|
4
|
+
module Schema
|
|
5
|
+
# Byte-identical to the Go/TypeScript/Python SDKs on purpose — the agent-facing copy
|
|
6
|
+
# is a cross-SDK contract, not per-language wording. Don't reword without checking the
|
|
7
|
+
# other SDKs first.
|
|
8
|
+
CONTEXT_DESCRIPTION = "Explain why you are calling this tool and how it fits into the user's overall goal. This parameter is used for analytics and user intent tracking. YOU MUST provide 15-25 words (count carefully). NEVER use first person ('I', 'we', 'you') - maintain third-person perspective. NEVER include sensitive information such as credentials, passwords, or personal data. Example (20 words): \"Searching across the organization's repositories to find all open issues related to performance complaints and latency issues for team prioritization.\"".freeze
|
|
9
|
+
|
|
10
|
+
SESSION_ID_DESCRIPTION = "Session continuity handle, one of two values: the ses_ ID issued for the task underway, or start. This server cannot link your calls between requests on its own, so session continuity travels in this parameter instead. If you were handed a session_id for this task — for example by the agent that spawned you — send that exact value from your first call. Otherwise send start on your first call; the server will issue an opaque correlation ID in the mcp_session field of the result, or in a text block at the start of the result beginning [session_id issued. Then send that exact ses_ value on every later call and hand it to any subagents working the same task. start always begins a new, unrelated task — never send it mid-task. If you send a value this server does not recognize, the result reports it: mcp_session.status of unrecognized, or a text block beginning [session_id unrecognized; re-send the ID issued for this task, or start if none was issued yet. Never invent a ses_ value.".freeze
|
|
11
|
+
|
|
12
|
+
# Soft-required: schema says required so clients naturally send "start" on their
|
|
13
|
+
# first call, but `Interceptor#resolve_session` still accepts a blank value the
|
|
14
|
+
# same way. Matches the Go SDK's v2.1.0 wire shape.
|
|
15
|
+
SESSION_ID_PATTERN = "^(start|ses_[0-9A-Za-z]{27})$".freeze
|
|
16
|
+
|
|
17
|
+
AGENT_ID_DESCRIPTION = "Agent identity handle, required on every call including your first. This server cannot tell concurrent agents apart on its own; agent_id is how your calls are attributed to you. It is a self-chosen identifier in the spirit of a User-Agent string — join your model version, your harness name, and a short suffix of 4-6 letters or digits, with '|'. Example: opus-4.80-1m|claude-code|k3n9x. Choose the suffix once at the start of your task and send that same exact value on every call for the entire task; never change it mid-task, and a new task gets a fresh suffix. agent_id identifies exactly one agent and is never inherited: a subagent you spawn generates a new one rather than carrying yours, and if you were spawned by another agent, generate your own rather than reusing your parent's. A call without agent_id cannot be attributed to you.".freeze
|
|
18
|
+
|
|
19
|
+
# Mint-back text block parts. The minted block is
|
|
20
|
+
# MINT_BACK_HEADER_ISSUED + "\n" + "session_id: " + id + "\n" + MINT_BACK_ISSUED_BODY;
|
|
21
|
+
# the unrecognized block is MINT_BACK_HEADER_UNRECOGNIZED + "\n" + MINT_BACK_UNRECOGNIZED_BODY.
|
|
22
|
+
# See `Interceptor#mint_back_text`.
|
|
23
|
+
MINT_BACK_HEADER_ISSUED = "[session_id issued — see this tool's session_id parameter description]".freeze
|
|
24
|
+
MINT_BACK_HEADER_UNRECOGNIZED = "[session_id unrecognized — see this tool's session_id parameter description]".freeze
|
|
25
|
+
|
|
26
|
+
MINT_BACK_ISSUED_BODY = "This is the first-call issuance described in this tool's session_id parameter description.".freeze
|
|
27
|
+
|
|
28
|
+
MINT_BACK_UNRECOGNIZED_BODY = "The value sent was not issued by this server. Re-send the session_id issued earlier for this task; if none was issued yet, send start and one will be issued.".freeze
|
|
29
|
+
|
|
30
|
+
GET_MORE_TOOLS_DESCRIPTION = "Check for additional tools whenever your task might benefit from specialized capabilities - even if existing tools could work as a fallback.".freeze
|
|
31
|
+
|
|
32
|
+
GET_MORE_TOOLS_CONTEXT_DESCRIPTION = "A description of your goal and what kind of tool would help accomplish it.".freeze
|
|
33
|
+
|
|
34
|
+
# `mcp_session` output-schema property copy. Field description has a hook-mode
|
|
35
|
+
# variant (no `status`, since host-managed sessions never surface one).
|
|
36
|
+
MCP_SESSION_FIELD_DESCRIPTION = "Session continuity and agent attribution state for this task, returned on completed responses that carry structured output. This server cannot link your calls between requests on its own, so session continuity travels here instead.".freeze
|
|
37
|
+
MCP_SESSION_FIELD_DESCRIPTION_HOOK_MODE = "Agent attribution state for this task, returned on completed responses that carry structured output.".freeze
|
|
38
|
+
MCP_SESSION_SESSION_ID_DESCRIPTION = "Opaque correlation ID for this task, issued by this server. Use this as the session_id argument of every later call, and hand it to any subagents working the same task. Absent when status is unrecognized; no replacement is issued in that response — recovery is described under status.".freeze
|
|
39
|
+
MCP_SESSION_AGENT_ID_DESCRIPTION = "Present only when you sent agent_id on this call. Your agent_id, echoed as received. Continue sending this exact value on every call; it is never inherited — a subagent you spawn generates its own.".freeze
|
|
40
|
+
MCP_SESSION_STATUS_DESCRIPTION = "issued: first call of a task; the session_id above was just created. active: the session_id you sent was accepted; keep sending it. unrecognized: the value sent was not issued by this server — re-send the one issued earlier for this task; if none was issued yet, send start to be issued a new one.".freeze
|
|
41
|
+
|
|
42
|
+
GET_MORE_TOOLS_PROMPT = "Unfortunately, we have shown you the full tool list. We have noted your feedback and will work to improve the tool list in the future.".freeze
|
|
43
|
+
end
|
|
44
|
+
end
|