agentcat 0.0.1 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. checksums.yaml +4 -4
  2. data/LICENSE +2 -11
  3. data/README.md +265 -20
  4. data/lib/agentcat/adapters/base.rb +98 -0
  5. data/lib/agentcat/adapters/official.rb +277 -0
  6. data/lib/agentcat/client.rb +189 -0
  7. data/lib/agentcat/clock.rb +16 -0
  8. data/lib/agentcat/custom_event.rb +215 -0
  9. data/lib/agentcat/delivery.rb +58 -0
  10. data/lib/agentcat/diagnostics.rb +434 -0
  11. data/lib/agentcat/error_capture.rb +117 -0
  12. data/lib/agentcat/event_id.rb +19 -0
  13. data/lib/agentcat/event_pipeline.rb +82 -0
  14. data/lib/agentcat/event_queue.rb +151 -0
  15. data/lib/agentcat/exporters/base.rb +135 -0
  16. data/lib/agentcat/exporters/datadog.rb +137 -0
  17. data/lib/agentcat/exporters/otlp.rb +157 -0
  18. data/lib/agentcat/exporters/posthog.rb +185 -0
  19. data/lib/agentcat/exporters/sentry.rb +242 -0
  20. data/lib/agentcat/exporters/trace_context.rb +79 -0
  21. data/lib/agentcat/exporters.rb +108 -0
  22. data/lib/agentcat/fork_safety.rb +30 -0
  23. data/lib/agentcat/hooks.rb +190 -0
  24. data/lib/agentcat/http_post.rb +61 -0
  25. data/lib/agentcat/interceptor.rb +728 -0
  26. data/lib/agentcat/log.rb +80 -0
  27. data/lib/agentcat/options.rb +313 -0
  28. data/lib/agentcat/payload_limits.rb +71 -0
  29. data/lib/agentcat/private_members.rb +286 -0
  30. data/lib/agentcat/redaction.rb +176 -0
  31. data/lib/agentcat/rejected_calls.rb +147 -0
  32. data/lib/agentcat/request_context.rb +266 -0
  33. data/lib/agentcat/sanitization.rb +191 -0
  34. data/lib/agentcat/schema/prompts.rb +44 -0
  35. data/lib/agentcat/server_info.rb +280 -0
  36. data/lib/agentcat/session_manager.rb +83 -0
  37. data/lib/agentcat/tags.rb +61 -0
  38. data/lib/agentcat/test_mode.rb +86 -0
  39. data/lib/agentcat/testing.rb +153 -0
  40. data/lib/agentcat/text.rb +68 -0
  41. data/lib/agentcat/token_estimate.rb +98 -0
  42. data/lib/agentcat/tool_call.rb +129 -0
  43. data/lib/agentcat/tool_handle.rb +289 -0
  44. data/lib/agentcat/tracker.rb +204 -0
  45. data/lib/agentcat/truncation.rb +265 -0
  46. data/lib/agentcat/unredacted_event.rb +155 -0
  47. data/lib/agentcat/user_identity.rb +11 -0
  48. data/lib/agentcat/version.rb +2 -2
  49. data/lib/agentcat.rb +393 -21
  50. metadata +194 -16
  51. data/agentcat.gemspec +0 -30
@@ -0,0 +1,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