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
data/lib/agentcat/log.rb
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# typed: strict
|
|
2
|
+
|
|
3
|
+
require_relative "clock"
|
|
4
|
+
|
|
5
|
+
module AgentCat
|
|
6
|
+
# Problem lines that can repeat once per event: a delivery that keeps failing, a full
|
|
7
|
+
# queue, an exporter that is down, a hook that always raises, a tag the customer
|
|
8
|
+
# always gets wrong. Each distinct line logs at most once per WINDOW seconds; the next
|
|
9
|
+
# time it logs, it says how many repeats it held back. PHP collapses the same lines
|
|
10
|
+
# per delivery (RepeatedLines); a Ruby server runs for days, so this uses a window.
|
|
11
|
+
#
|
|
12
|
+
# Levels: ERROR for lost events and exporter setup failures, WARN for hook
|
|
13
|
+
# failures and customer data that AgentCat ignores. These lines name things (a tool,
|
|
14
|
+
# an exporter class, an exception class), never payload values: details that can
|
|
15
|
+
# carry them (an exception message) go to `AgentCat.logger.debug` at the call site.
|
|
16
|
+
module Log
|
|
17
|
+
extend T::Sig
|
|
18
|
+
|
|
19
|
+
WINDOW = 60
|
|
20
|
+
# Distinct lines remembered at once. Past it, the oldest is forgotten.
|
|
21
|
+
MAX_LINES = 1000
|
|
22
|
+
|
|
23
|
+
@mutex = T.let(Mutex.new, Mutex)
|
|
24
|
+
# line => [monotonic time it last logged, repeats held back since]
|
|
25
|
+
@lines = T.let({}, T::Hash[String, [Float, Integer]])
|
|
26
|
+
|
|
27
|
+
class << self
|
|
28
|
+
extend T::Sig
|
|
29
|
+
|
|
30
|
+
sig { params(line: String).void }
|
|
31
|
+
def error(line)
|
|
32
|
+
write(:error, line)
|
|
33
|
+
end
|
|
34
|
+
|
|
35
|
+
sig { params(line: String).void }
|
|
36
|
+
def warn(line)
|
|
37
|
+
write(:warn, line)
|
|
38
|
+
end
|
|
39
|
+
|
|
40
|
+
# Forgets every line, for `AgentCat.reset!`.
|
|
41
|
+
sig { void }
|
|
42
|
+
def reset!
|
|
43
|
+
@mutex.synchronize { @lines.clear }
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
private
|
|
47
|
+
|
|
48
|
+
sig { params(level: Symbol, line: String).void }
|
|
49
|
+
def write(level, line)
|
|
50
|
+
held_back = admit(line)
|
|
51
|
+
return if held_back.nil?
|
|
52
|
+
|
|
53
|
+
text = held_back.zero? ? line : "#{line} (#{held_back} more since this was last logged)"
|
|
54
|
+
logger = AgentCat.logger
|
|
55
|
+
(level == :error) ? logger.error(text) : logger.warn(text)
|
|
56
|
+
rescue
|
|
57
|
+
# Logging must never cost the caller anything.
|
|
58
|
+
nil
|
|
59
|
+
end
|
|
60
|
+
|
|
61
|
+
# nil when the line logged less than WINDOW seconds ago, else the repeats it held back.
|
|
62
|
+
sig { params(line: String).returns(T.nilable(Integer)) }
|
|
63
|
+
def admit(line)
|
|
64
|
+
now = Clock.monotonic_now
|
|
65
|
+
@mutex.synchronize do
|
|
66
|
+
last = @lines[line]
|
|
67
|
+
if last && now - last[0] < WINDOW
|
|
68
|
+
@lines[line] = [last[0], last[1] + 1]
|
|
69
|
+
return nil
|
|
70
|
+
end
|
|
71
|
+
|
|
72
|
+
@lines.delete(line)
|
|
73
|
+
@lines.shift while @lines.size >= MAX_LINES
|
|
74
|
+
@lines[line] = [now, 0]
|
|
75
|
+
last ? last[1] : 0
|
|
76
|
+
end
|
|
77
|
+
end
|
|
78
|
+
end
|
|
79
|
+
end
|
|
80
|
+
end
|
|
@@ -0,0 +1,313 @@
|
|
|
1
|
+
# typed: true
|
|
2
|
+
|
|
3
|
+
require "uri"
|
|
4
|
+
require_relative "hooks"
|
|
5
|
+
require_relative "log"
|
|
6
|
+
|
|
7
|
+
module AgentCat
|
|
8
|
+
# Per-server configuration passed to `AgentCat.track`.
|
|
9
|
+
#
|
|
10
|
+
# * `enable_agent_tracking` — also inject `agent_id` and report it as the event actor.
|
|
11
|
+
# * `enable_report_missing` — on by default. Set `false` to skip registering
|
|
12
|
+
# `get_more_tools` (matches Python/Go's `enable_report_missing`/`DisableReportMissing`).
|
|
13
|
+
# A host that already defines its own keeps it either way.
|
|
14
|
+
# * `resolve_session_id` — `(tool_call) -> String | nil`. Set this and the
|
|
15
|
+
# host owns session identity: no `session_id` in the schema, and whatever correlation id
|
|
16
|
+
# you return gets derived into a `ses_` KSUID (SHA-256, never reported verbatim) the same
|
|
17
|
+
# way the Go/TypeScript SDKs do it.
|
|
18
|
+
# * `stateless` — deprecated, logs a warning if set. No per-connection session; grouping
|
|
19
|
+
# falls back to identified user + client + a 30-minute window, which needs `identify` to
|
|
20
|
+
# work at all. MCP is stateless by default now, so this doesn't do anything the rest of
|
|
21
|
+
# the SDK doesn't already handle — use `resolve_session_id` or `identify` instead.
|
|
22
|
+
# * `identify` — `(tool_call) -> UserIdentity | nil`, run on every call.
|
|
23
|
+
# `user_id` becomes the event's actor.
|
|
24
|
+
# * `redact_sensitive_information` — `(string) -> String`, applied to every string leaving
|
|
25
|
+
# the process. Runs after `redact_event`, on top of whatever the server already redacts.
|
|
26
|
+
# * `redact_event` — `(UnredactedEvent) -> UnredactedEvent | nil`. Mutate and return the
|
|
27
|
+
# event, or return `nil` to drop it. Runs before `redact_sensitive_information`, so it
|
|
28
|
+
# sees raw values. Don't build a fresh event to return — the result replaces the whole
|
|
29
|
+
# thing, and anything you didn't set is gone.
|
|
30
|
+
# * `event_tags` — `(tool_call) -> Hash[String, String]`, filterable tags.
|
|
31
|
+
# * `event_properties` — `(tool_call) -> Hash`, arbitrary metadata merged
|
|
32
|
+
# into every event.
|
|
33
|
+
#
|
|
34
|
+
# `tool_call` is a frozen `AgentCat::ToolCall` (tool name, arguments, `_meta`, HTTP
|
|
35
|
+
# headers, client name and version, protocol version, `Mcp-Session-Id`, the Rack env
|
|
36
|
+
# and the server context), built before any hook runs. Changing its arguments raises
|
|
37
|
+
# `FrozenError` and never reaches the tool or the event. Earlier releases passed these four hooks
|
|
38
|
+
# `(arguments, server_context)`; a hook that still takes two arguments logs one
|
|
39
|
+
# WARN line at `track`.
|
|
40
|
+
# * `hook_timeout` — wall-clock cap per hook, default 1s, max 5s. Go/Python/TS hardcode
|
|
41
|
+
# this; Ruby exposes it so you can tune it without a code change.
|
|
42
|
+
# * `client` — anything with `post_event(event)`. Defaults to `AgentCat::Client`.
|
|
43
|
+
# * `queue_size` — events kept before the oldest gets dropped (default 10,000, same as
|
|
44
|
+
# the reference SDKs). Applies to the process-wide queue the first time it's used.
|
|
45
|
+
# * `max_retries` — retries past the first attempt (default 3), exponential backoff.
|
|
46
|
+
# `retry_base_delay` is the first backoff in seconds (default 1), doubling each time
|
|
47
|
+
# (~1s, 2s, 4s) plus jitter.
|
|
48
|
+
# * `request_timeout` — per-attempt HTTP timeout for the default client (default 10s; the
|
|
49
|
+
# connect timeout is fixed at 1s). First `track` call wins, same as the queue.
|
|
50
|
+
# * `api_base_url` — overrides the default client's endpoint (scheme + host, optional
|
|
51
|
+
# port/path prefix), for pointing a non-default environment at your own stage/test
|
|
52
|
+
# API without exporting AGENTCAT_API_URL. Takes precedence over that env var when
|
|
53
|
+
# both are set. First `track` call wins, same as `request_timeout`. No effect with a
|
|
54
|
+
# custom `client:`.
|
|
55
|
+
# * `exporters` — objects responding to `#export(event)` or `#call`, or TS's hash form
|
|
56
|
+
# (`{type: "datadog", api_key: "...", site: "...", service: "..."}`, see
|
|
57
|
+
# `Exporters.resolve`). Each one runs asynchronously; one failing doesn't touch the
|
|
58
|
+
# others or the tool call. Works fine with `project_id: nil` if you just want telemetry
|
|
59
|
+
# forwarded somewhere. Otlp/Datadog/Sentry/PostHog ship built in — subclass
|
|
60
|
+
# `Exporters::Base` for anything else. An entry that is neither logs one line and is
|
|
61
|
+
# skipped.
|
|
62
|
+
# * `disable_diagnostics` — opt out of the diagnostics beacon (see `Diagnostics`). On by
|
|
63
|
+
# default; `DISABLE_DIAGNOSTICS` and the test-env auto-disable still apply on top.
|
|
64
|
+
#
|
|
65
|
+
# A bad value never raises: a hook that doesn't respond to `#call` is dropped,
|
|
66
|
+
# and a number out of range or a malformed `api_base_url` falls back to the default.
|
|
67
|
+
# Each logs one WARN line. A value of the wrong Ruby type (a String `queue_size`) still
|
|
68
|
+
# fails fast in the Sorbet sig, like PHP's own type errors.
|
|
69
|
+
class Options
|
|
70
|
+
extend T::Sig
|
|
71
|
+
|
|
72
|
+
Hook = T.type_alias { T.untyped }
|
|
73
|
+
StringHook = T.type_alias { T.untyped }
|
|
74
|
+
EventHook = T.type_alias { T.untyped }
|
|
75
|
+
|
|
76
|
+
DEFAULT_HOOK_TIMEOUT = 1
|
|
77
|
+
MAX_HOOK_TIMEOUT = 5
|
|
78
|
+
DEFAULT_QUEUE_SIZE = 10_000
|
|
79
|
+
DEFAULT_MAX_RETRIES = 3
|
|
80
|
+
DEFAULT_RETRY_BASE_DELAY = 1.0
|
|
81
|
+
DEFAULT_REQUEST_TIMEOUT = 10
|
|
82
|
+
|
|
83
|
+
sig { returns(T::Boolean) }
|
|
84
|
+
attr_accessor :enable_agent_tracking
|
|
85
|
+
|
|
86
|
+
# Off: no session_id/agent_id injected, no mint-back, no events published (tool calls
|
|
87
|
+
# or custom events on this server). `context` and `get_more_tools` keep following
|
|
88
|
+
# their own flags. Same as `enableTracing` (TS/Python) / `DisableTracing` (Go).
|
|
89
|
+
sig { returns(T::Boolean) }
|
|
90
|
+
attr_accessor :enable_tracing
|
|
91
|
+
|
|
92
|
+
# Off: no `context` parameter injected into your tools. `get_more_tools` keeps its own.
|
|
93
|
+
sig { returns(T::Boolean) }
|
|
94
|
+
attr_accessor :enable_tool_call_context
|
|
95
|
+
|
|
96
|
+
# Replaces the default description of the injected `context` parameter, e.g. to tell
|
|
97
|
+
# agents what kind of intent matters for your domain. nil or blank means the default.
|
|
98
|
+
sig { returns(T.nilable(String)) }
|
|
99
|
+
attr_accessor :custom_context_description
|
|
100
|
+
|
|
101
|
+
sig { returns(T::Boolean) }
|
|
102
|
+
attr_accessor :enable_report_missing
|
|
103
|
+
|
|
104
|
+
sig { returns(T::Array[T.untyped]) }
|
|
105
|
+
attr_accessor :exporters
|
|
106
|
+
|
|
107
|
+
sig { returns(T::Boolean) }
|
|
108
|
+
attr_accessor :disable_diagnostics
|
|
109
|
+
|
|
110
|
+
sig { returns(T.nilable(Hook)) }
|
|
111
|
+
attr_accessor :resolve_session_id
|
|
112
|
+
|
|
113
|
+
sig { returns(T::Boolean) }
|
|
114
|
+
attr_accessor :stateless
|
|
115
|
+
|
|
116
|
+
sig { returns(T.nilable(Hook)) }
|
|
117
|
+
attr_accessor :identify
|
|
118
|
+
|
|
119
|
+
sig { returns(T.nilable(StringHook)) }
|
|
120
|
+
attr_accessor :redact_sensitive_information
|
|
121
|
+
|
|
122
|
+
sig { returns(T.nilable(EventHook)) }
|
|
123
|
+
attr_accessor :redact_event
|
|
124
|
+
|
|
125
|
+
sig { returns(T.nilable(Hook)) }
|
|
126
|
+
attr_accessor :event_tags
|
|
127
|
+
|
|
128
|
+
sig { returns(T.nilable(Hook)) }
|
|
129
|
+
attr_accessor :event_properties
|
|
130
|
+
|
|
131
|
+
sig { returns(Float) }
|
|
132
|
+
attr_reader :hook_timeout
|
|
133
|
+
|
|
134
|
+
sig { returns(Integer) }
|
|
135
|
+
attr_reader :queue_size
|
|
136
|
+
|
|
137
|
+
sig { returns(Integer) }
|
|
138
|
+
attr_reader :max_retries
|
|
139
|
+
|
|
140
|
+
sig { returns(Float) }
|
|
141
|
+
attr_reader :retry_base_delay
|
|
142
|
+
|
|
143
|
+
sig { returns(Float) }
|
|
144
|
+
attr_reader :request_timeout
|
|
145
|
+
|
|
146
|
+
sig { returns(T.nilable(String)) }
|
|
147
|
+
attr_reader :api_base_url
|
|
148
|
+
|
|
149
|
+
sig { params(client: T.untyped).void }
|
|
150
|
+
attr_writer :client
|
|
151
|
+
|
|
152
|
+
sig do
|
|
153
|
+
params(
|
|
154
|
+
enable_agent_tracking: T::Boolean,
|
|
155
|
+
enable_tracing: T::Boolean,
|
|
156
|
+
enable_tool_call_context: T::Boolean,
|
|
157
|
+
custom_context_description: T.nilable(String),
|
|
158
|
+
enable_report_missing: T::Boolean,
|
|
159
|
+
exporters: T::Array[T.untyped],
|
|
160
|
+
disable_diagnostics: T::Boolean,
|
|
161
|
+
resolve_session_id: T.nilable(Hook),
|
|
162
|
+
stateless: T::Boolean,
|
|
163
|
+
identify: T.nilable(Hook),
|
|
164
|
+
redact_sensitive_information: T.nilable(StringHook),
|
|
165
|
+
redact_event: T.nilable(EventHook),
|
|
166
|
+
event_tags: T.nilable(Hook),
|
|
167
|
+
event_properties: T.nilable(Hook),
|
|
168
|
+
hook_timeout: Numeric,
|
|
169
|
+
client: T.untyped,
|
|
170
|
+
queue_size: Integer,
|
|
171
|
+
max_retries: Integer,
|
|
172
|
+
retry_base_delay: Numeric,
|
|
173
|
+
request_timeout: Numeric,
|
|
174
|
+
api_base_url: T.nilable(String)
|
|
175
|
+
).void
|
|
176
|
+
end
|
|
177
|
+
def initialize(
|
|
178
|
+
enable_agent_tracking: false,
|
|
179
|
+
enable_tracing: true,
|
|
180
|
+
enable_tool_call_context: true,
|
|
181
|
+
custom_context_description: nil,
|
|
182
|
+
enable_report_missing: true,
|
|
183
|
+
exporters: [],
|
|
184
|
+
disable_diagnostics: false,
|
|
185
|
+
resolve_session_id: nil,
|
|
186
|
+
stateless: false,
|
|
187
|
+
identify: nil,
|
|
188
|
+
redact_sensitive_information: nil,
|
|
189
|
+
redact_event: nil,
|
|
190
|
+
event_tags: nil,
|
|
191
|
+
event_properties: nil,
|
|
192
|
+
hook_timeout: DEFAULT_HOOK_TIMEOUT,
|
|
193
|
+
client: nil,
|
|
194
|
+
queue_size: DEFAULT_QUEUE_SIZE,
|
|
195
|
+
max_retries: DEFAULT_MAX_RETRIES,
|
|
196
|
+
retry_base_delay: DEFAULT_RETRY_BASE_DELAY,
|
|
197
|
+
request_timeout: DEFAULT_REQUEST_TIMEOUT,
|
|
198
|
+
api_base_url: nil
|
|
199
|
+
)
|
|
200
|
+
warn_if_stateless_deprecated!(stateless)
|
|
201
|
+
|
|
202
|
+
@enable_agent_tracking = enable_agent_tracking
|
|
203
|
+
@enable_tracing = enable_tracing
|
|
204
|
+
@enable_tool_call_context = enable_tool_call_context
|
|
205
|
+
@custom_context_description = custom_context_description
|
|
206
|
+
@enable_report_missing = enable_report_missing
|
|
207
|
+
@exporters = Exporters.resolve(exporters)
|
|
208
|
+
@disable_diagnostics = disable_diagnostics
|
|
209
|
+
@resolve_session_id = callable_or_nil(resolve_session_id, "resolve_session_id")
|
|
210
|
+
@stateless = stateless
|
|
211
|
+
@identify = callable_or_nil(identify, "identify")
|
|
212
|
+
@redact_sensitive_information = callable_or_nil(redact_sensitive_information, "redact_sensitive_information")
|
|
213
|
+
@redact_event = callable_or_nil(redact_event, "redact_event")
|
|
214
|
+
@event_tags = callable_or_nil(event_tags, "event_tags")
|
|
215
|
+
@event_properties = callable_or_nil(event_properties, "event_properties")
|
|
216
|
+
@hook_timeout = [positive_float_or_default(hook_timeout, "hook_timeout", DEFAULT_HOOK_TIMEOUT), MAX_HOOK_TIMEOUT.to_f].min
|
|
217
|
+
@client = client
|
|
218
|
+
@queue_size = int_or_default(queue_size, "queue_size", DEFAULT_QUEUE_SIZE, min: 1)
|
|
219
|
+
@max_retries = int_or_default(max_retries, "max_retries", DEFAULT_MAX_RETRIES, min: 0)
|
|
220
|
+
@retry_base_delay = positive_float_or_default(retry_base_delay, "retry_base_delay", DEFAULT_RETRY_BASE_DELAY)
|
|
221
|
+
@request_timeout = positive_float_or_default(request_timeout, "request_timeout", DEFAULT_REQUEST_TIMEOUT)
|
|
222
|
+
@api_base_url = http_url_or_nil(api_base_url)
|
|
223
|
+
end
|
|
224
|
+
|
|
225
|
+
sig { returns(T.untyped) }
|
|
226
|
+
def client
|
|
227
|
+
@client || AgentCat::Client
|
|
228
|
+
end
|
|
229
|
+
|
|
230
|
+
sig { returns(T::Boolean) }
|
|
231
|
+
def default_client?
|
|
232
|
+
@client.nil?
|
|
233
|
+
end
|
|
234
|
+
|
|
235
|
+
sig { returns(String) }
|
|
236
|
+
def context_description
|
|
237
|
+
custom = custom_context_description
|
|
238
|
+
(custom.nil? || custom.strip.empty?) ? Schema::CONTEXT_DESCRIPTION : custom
|
|
239
|
+
end
|
|
240
|
+
|
|
241
|
+
sig { returns(T::Boolean) }
|
|
242
|
+
def host_managed_sessions?
|
|
243
|
+
!resolve_session_id.nil?
|
|
244
|
+
end
|
|
245
|
+
|
|
246
|
+
sig { returns(T::Boolean) }
|
|
247
|
+
def stateless?
|
|
248
|
+
!!stateless
|
|
249
|
+
end
|
|
250
|
+
|
|
251
|
+
private
|
|
252
|
+
|
|
253
|
+
sig { params(stateless: T::Boolean).void }
|
|
254
|
+
def warn_if_stateless_deprecated!(stateless)
|
|
255
|
+
return unless stateless
|
|
256
|
+
|
|
257
|
+
Log.warn(
|
|
258
|
+
"Options#stateless is deprecated and will be removed in a future release. MCP " \
|
|
259
|
+
"itself is stateless by default now (the 2026-07-28 spec), so every call already " \
|
|
260
|
+
"resolves session identity per request regardless of this option. Use " \
|
|
261
|
+
"resolve_session_id for host-managed sessions, or identify alone to attribute " \
|
|
262
|
+
"actors with no session concept at all."
|
|
263
|
+
)
|
|
264
|
+
end
|
|
265
|
+
|
|
266
|
+
sig { params(message: String).void }
|
|
267
|
+
def warn_bad_value(message)
|
|
268
|
+
# Rate-limited: an app that builds its Options per request logs this once a minute.
|
|
269
|
+
Log.warn("Options##{message}")
|
|
270
|
+
end
|
|
271
|
+
|
|
272
|
+
sig { params(hook: T.untyped, name: String).returns(T.untyped) }
|
|
273
|
+
def callable_or_nil(hook, name)
|
|
274
|
+
return hook if hook.nil? || hook.respond_to?(:call)
|
|
275
|
+
|
|
276
|
+
warn_bad_value("#{name} must respond to #call, got #{hook.class}; the hook is ignored")
|
|
277
|
+
nil
|
|
278
|
+
end
|
|
279
|
+
|
|
280
|
+
sig { params(value: Integer, name: String, default: Integer, min: Integer).returns(Integer) }
|
|
281
|
+
def int_or_default(value, name, default, min:)
|
|
282
|
+
return value if value >= min
|
|
283
|
+
|
|
284
|
+
warn_bad_value("#{name} must be #{(min == 1) ? "at least 1" : "#{min} or more"}, got #{value}; using the default #{default}")
|
|
285
|
+
default
|
|
286
|
+
end
|
|
287
|
+
|
|
288
|
+
# NaN fails `> 0` too.
|
|
289
|
+
sig { params(value: Numeric, name: String, default: Numeric).returns(Float) }
|
|
290
|
+
def positive_float_or_default(value, name, default)
|
|
291
|
+
float = value.to_f
|
|
292
|
+
return float if float > 0
|
|
293
|
+
|
|
294
|
+
warn_bad_value("#{name} must be a positive number, got #{value.inspect}; using the default #{default.to_f}")
|
|
295
|
+
default.to_f
|
|
296
|
+
end
|
|
297
|
+
|
|
298
|
+
sig { params(url: T.nilable(String)).returns(T.nilable(String)) }
|
|
299
|
+
def http_url_or_nil(url)
|
|
300
|
+
return nil if url.nil?
|
|
301
|
+
|
|
302
|
+
uri = begin
|
|
303
|
+
URI.parse(url)
|
|
304
|
+
rescue URI::InvalidURIError
|
|
305
|
+
nil
|
|
306
|
+
end
|
|
307
|
+
return url if uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
|
|
308
|
+
|
|
309
|
+
warn_bad_value("api_base_url must be an absolute http(s) URL, got #{url.inspect}; using the default endpoint")
|
|
310
|
+
nil
|
|
311
|
+
end
|
|
312
|
+
end
|
|
313
|
+
end
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# typed: true
|
|
2
|
+
|
|
3
|
+
module AgentCat
|
|
4
|
+
# Single source of truth for the payload ceilings applied before an event leaves
|
|
5
|
+
# the process (sanitization and truncation).
|
|
6
|
+
#
|
|
7
|
+
# These numbers match the Go and TypeScript SDKs exactly. Python's differ (10 KiB
|
|
8
|
+
# strings, depth 5, breadth 500, no per-field ceilings) — we follow Go/TS on purpose.
|
|
9
|
+
module PayloadLimits
|
|
10
|
+
extend T::Sig
|
|
11
|
+
|
|
12
|
+
# --- recursive normalization -------------------------------------------------
|
|
13
|
+
|
|
14
|
+
# Maximum nesting depth kept before a value becomes a marker.
|
|
15
|
+
MAX_DEPTH = 10
|
|
16
|
+
# Depth reduction never takes `error` below this: error -> chained_errors -> item
|
|
17
|
+
# -> frames -> frame keeps every frame a hash.
|
|
18
|
+
MIN_ERROR_DEPTH = 5
|
|
19
|
+
# Maximum number of entries kept per hash or array.
|
|
20
|
+
MAX_BREADTH = 100
|
|
21
|
+
# Per-string cap during normalization, in UTF-16 code units like every string
|
|
22
|
+
# limit here (TS `String#length`). The "..." suffix goes on top.
|
|
23
|
+
MAX_STRING_LENGTH = 32_768
|
|
24
|
+
|
|
25
|
+
# --- total event budget ------------------------------------------------------
|
|
26
|
+
|
|
27
|
+
# Total serialized event budget — the important one: anything over this has
|
|
28
|
+
# user-controlled fields progressively reduced until it fits.
|
|
29
|
+
MAX_EVENT_BYTES = 102_400
|
|
30
|
+
|
|
31
|
+
# --- field-level string limits -------------------------------------------------
|
|
32
|
+
#
|
|
33
|
+
# UTF-16 code units, suffix not counted, same as the TS SDK.
|
|
34
|
+
|
|
35
|
+
MAX_USER_INTENT_LENGTH = 2_048
|
|
36
|
+
MAX_ERROR_MESSAGE_LENGTH = 2_048
|
|
37
|
+
MAX_RESOURCE_NAME_LENGTH = 256
|
|
38
|
+
MAX_METADATA_LENGTH = 256
|
|
39
|
+
MAX_STACK_FRAMES = 50
|
|
40
|
+
# How many `#cause` links to follow when capturing a chained exception.
|
|
41
|
+
MAX_CHAIN_DEPTH = 10
|
|
42
|
+
# Per text block inside `response[:content]`.
|
|
43
|
+
MAX_CONTENT_TEXT_LENGTH = 32_768
|
|
44
|
+
|
|
45
|
+
# --- sanitization ---------------------------------------------------------------
|
|
46
|
+
|
|
47
|
+
# Strings at or above this size that look like base64 are treated as binary.
|
|
48
|
+
BASE64_SIZE_GATE = 10_240
|
|
49
|
+
# Sanitization walk depth cap (the Go SDK guards the same walk separately).
|
|
50
|
+
MAX_WALK_DEPTH = 100
|
|
51
|
+
|
|
52
|
+
# --- event_tags ---------------------------------------------------------------------
|
|
53
|
+
#
|
|
54
|
+
# From agentcat-api's generated docs directly (PublishEventRequest#tags), not
|
|
55
|
+
# mirrored from another SDK.
|
|
56
|
+
|
|
57
|
+
MAX_TAG_KEY_LENGTH = 32
|
|
58
|
+
MAX_TAG_VALUE_LENGTH = 200
|
|
59
|
+
MAX_TAGS = 50
|
|
60
|
+
TAG_KEY_PATTERN = /\A[A-Za-z0-9_.:$ -]+\z/
|
|
61
|
+
|
|
62
|
+
# --- markers -----------------------------------------------------------------------
|
|
63
|
+
|
|
64
|
+
TRUNCATION_SUFFIX = "..."
|
|
65
|
+
MAX_BREADTH_MARKER = "[MaxProperties ~]"
|
|
66
|
+
OBJECT_DEPTH_MARKER = "[Object]"
|
|
67
|
+
ARRAY_DEPTH_MARKER = "[Array]"
|
|
68
|
+
CIRCULAR_MARKER = "[Circular ~]"
|
|
69
|
+
MAX_DEPTH_EXCEEDED_MARKER = "[MAX_DEPTH_EXCEEDED]"
|
|
70
|
+
end
|
|
71
|
+
end
|