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,58 @@
1
+ # typed: true
2
+
3
+ require_relative "diagnostics"
4
+
5
+ module AgentCat
6
+ # Retries a failed publish with exponential backoff and jitter, then gives up. Kept
7
+ # separate from Client because the generated client has no opinion on retry policy.
8
+ # Runs on the queue's worker thread, so the sleeps here never touch a tool call.
9
+ #
10
+ # Defaults: 3 retries after the first attempt, 1s base doubling (~1s, 2s, 4s) plus
11
+ # jitter, 10s HTTP timeout per attempt. Override via Options#max_retries /
12
+ # #retry_base_delay / #request_timeout.
13
+ class Delivery
14
+ extend T::Sig
15
+
16
+ DEFAULT_MAX_RETRIES = 3
17
+ DEFAULT_BASE_DELAY_SECONDS = 1.0
18
+ JITTER_RATIO = 0.25
19
+
20
+ sig do
21
+ params(
22
+ client: T.untyped,
23
+ event: T::Hash[Symbol, T.untyped],
24
+ max_retries: Integer,
25
+ base_delay: Numeric,
26
+ epoch: T.nilable(Integer)
27
+ ).void
28
+ end
29
+ def self.publish(client, event, max_retries: DEFAULT_MAX_RETRIES, base_delay: DEFAULT_BASE_DELAY_SECONDS, epoch: nil)
30
+ attempt = 0
31
+ loop do
32
+ # epoch is captured at enqueue time. If AgentCat got reset since (test
33
+ # teardown, usually), this event is stale and shouldn't publish into
34
+ # whatever state the process is in now.
35
+ return if epoch && epoch != AgentCat.event_epoch
36
+
37
+ return if client.post_event(event)
38
+
39
+ if attempt >= max_retries
40
+ Log.error("event publish failed after #{max_retries + 1} attempts; the event is lost")
41
+ Diagnostics.record(:error, "AgentCat runtime error | event publish failed after #{max_retries + 1} attempts | project #{event[:project_id] || "(telemetry-only)"}")
42
+ return
43
+ end
44
+
45
+ sleep(backoff(attempt + 1, base: base_delay))
46
+ attempt += 1
47
+ end
48
+ end
49
+
50
+ # attempt is 1-based: base * 2^(attempt-1), plus jitter up to JITTER_RATIO of
51
+ # base. Random.rand, not Kernel#rand — Kernel#rand won't scale a Float below 1.0.
52
+ sig { params(attempt: Integer, base: Numeric).returns(Float) }
53
+ def self.backoff(attempt, base: DEFAULT_BASE_DELAY_SECONDS)
54
+ exponentiated = T.must(base.to_f) * (2**(attempt - 1))
55
+ (exponentiated + Random.rand(exponentiated * JITTER_RATIO)).to_f
56
+ end
57
+ end
58
+ end
@@ -0,0 +1,434 @@
1
+ # typed: true
2
+
3
+ require "digest"
4
+ require "etc"
5
+ require "json"
6
+ require "logger"
7
+ require "socket"
8
+
9
+ require_relative "version"
10
+ require_relative "http_post"
11
+ require_relative "test_mode"
12
+
13
+ module AgentCat
14
+ class << self
15
+ extend T::Sig
16
+
17
+ # Defaults to WARN on $stderr — best-effort failures (publishing, bad config)
18
+ # shouldn't show up in tool results, but they shouldn't vanish either.
19
+ sig { params(logger: Logger).void }
20
+ attr_writer :logger
21
+
22
+ sig { returns(Logger) }
23
+ def logger
24
+ @logger ||= Logger.new($stderr, level: Logger::WARN, progname: "agentcat")
25
+ end
26
+
27
+ # When true, also appends to ~/agentcat.log (never $stderr — stdio transports
28
+ # need that clean). Independent of the remote beacon's on/off switch.
29
+ sig { returns(T::Boolean) }
30
+ def debug?
31
+ !!@debug
32
+ end
33
+
34
+ sig { params(debug: T::Boolean).void }
35
+ attr_writer :debug
36
+ end
37
+
38
+ # Anonymized signal sent back to AgentCat when setup or runtime errors happen.
39
+ # Just operational metadata — project id (or an anonymous install id), SDK/MCP/
40
+ # runtime versions, host shape. Never tool calls, responses, or anything about
41
+ # your users.
42
+ #
43
+ # Ships as an OTLP/HTTP log record to https://otel.agentcat.com/v1/logs (override
44
+ # with AGENTCAT_DIAGNOSTICS_ENDPOINT / AGENTCAT_DIAGNOSTICS_TOKEN). On by default —
45
+ # turn it off with Options#disable_diagnostics or AGENTCAT_DISABLE_DIAGNOSTICS
46
+ # (false/0/no/off forces it back on). The unprefixed DISABLE_DIAGNOSTICS (the TS
47
+ # name) can only turn it off; the unprefixed DIAGNOSTICS_ENDPOINT/DIAGNOSTICS_TOKEN
48
+ # are never read, so an app's own variables never reach AgentCat. Test
49
+ # processes disable themselves unless forced. ~/agentcat.log doesn't care about any
50
+ # of this.
51
+ module Diagnostics
52
+ DEFAULT_ENDPOINT = "https://otel.agentcat.com"
53
+ DEFAULT_TOKEN = "dgk_sdk_diag_3f9a2c7e1b8d4065af2e9c1d7b6a4f80"
54
+ SCOPE_NAME = "agentcat-diagnostics"
55
+ LOGS_PATH = "/v1/logs"
56
+ MAX_BUFFER = 1000
57
+ FLUSH_DELAY = 2
58
+ # A blocked collector costs a flush (and so `AgentCat.flush` / at_exit) at
59
+ # most about a second.
60
+ CONNECT_TIMEOUT = 0.25
61
+ TOTAL_TIMEOUT = 1.0
62
+ LOCAL_LOG_NAME = "agentcat.log"
63
+ # lib/agentcat/../.. - the installed gem's directory.
64
+ GEM_ROOT = T.let(
65
+ begin
66
+ File.realpath(File.expand_path("../..", __dir__))
67
+ rescue SystemCallError
68
+ File.expand_path("../..", __dir__)
69
+ end,
70
+ String
71
+ )
72
+
73
+ SEVERITY = T.let(
74
+ {
75
+ info: [9, "INFO"],
76
+ warn: [13, "WARN"],
77
+ error: [17, "ERROR"]
78
+ }.freeze,
79
+ T::Hash[Symbol, T::Array[T.untyped]]
80
+ )
81
+
82
+ extend T::Sig
83
+
84
+ @mutex = T.let(Mutex.new, Mutex)
85
+ @initialized = T.let(false, T::Boolean)
86
+ @enabled = T.let(false, T::Boolean)
87
+ @buffer = T.let([], T::Array[T::Hash[String, T.untyped]])
88
+ @flush_pending = T.let(false, T::Boolean)
89
+ @static_attrs = T.let([], T::Array[T::Hash[String, T.untyped]])
90
+ @record_attrs = T.let([], T::Array[T::Hash[String, T.untyped]])
91
+
92
+ class << self
93
+ extend T::Sig
94
+
95
+ # Test seam: (url, headers, body) -> [status, body].
96
+ sig { returns(T.untyped) }
97
+ attr_accessor :http_post
98
+
99
+ # Idempotent — only the first call per process does anything. Never raises.
100
+ sig { params(project_id: T.nilable(String), integration: String, disabled: T::Boolean).void }
101
+ def init(project_id:, integration:, disabled:)
102
+ @mutex.synchronize do
103
+ return if @initialized
104
+
105
+ @initialized = true
106
+ @static_attrs = build_static_attributes(project_id, integration)
107
+ @record_attrs = build_record_attributes
108
+ @enabled = compute_enabled?(disabled)
109
+ end
110
+ rescue => e
111
+ AgentCat.logger.debug { "diagnostics init failed: #{e.class}: #{e.message}" }
112
+ end
113
+
114
+ # Buffers a message for the next batched send; also writes to agentcat.log
115
+ # when debug? is on. Never raises, never blocks.
116
+ sig { params(level: Symbol, message: String).void }
117
+ def record(level, message)
118
+ file_log(level, message) if AgentCat.debug?
119
+ return unless @enabled
120
+ return if level == :debug
121
+
122
+ flush_already_pending = schedule_record(record: build_record(level, message))
123
+ spawn_flush unless flush_already_pending
124
+ rescue => e
125
+ AgentCat.logger.debug { "diagnostics record failed: #{e.class}: #{e.message}" }
126
+ end
127
+
128
+ # Best-effort send of whatever's buffered, bounded by TOTAL_TIMEOUT. AgentCat.flush
129
+ # (and so the at_exit hook) calls this too, so a record never waits for the
130
+ # FLUSH_DELAY batch timer at shutdown.
131
+ sig { void }
132
+ def flush
133
+ records = @mutex.synchronize do
134
+ pending = @buffer
135
+ @buffer = []
136
+ pending
137
+ end
138
+ return if records.empty?
139
+
140
+ post(build_payload(records))
141
+ rescue => e
142
+ AgentCat.logger.debug { "diagnostics flush failed: #{e.class}: #{e.message}" }
143
+ end
144
+
145
+ sig { returns(T::Boolean) }
146
+ def enabled?
147
+ @enabled
148
+ end
149
+
150
+ sig { returns(T::Array[T::Hash[String, T.untyped]]) }
151
+ def static_attributes
152
+ @static_attrs
153
+ end
154
+
155
+ # Node `os.platform()` names for `Etc.uname[:sysname]`: `win32` for Windows,
156
+ # else the name in lower case (`linux`, `darwin`, `freebsd`, `sunos`).
157
+ sig { params(sysname: String).returns(String) }
158
+ def os_type(sysname)
159
+ name = sysname.downcase
160
+ name.start_with?("windows", "mingw", "msys", "cygwin") ? "win32" : name
161
+ end
162
+
163
+ # Node `os.arch()` names for x64 and arm64 (any case); any other machine name as is.
164
+ sig { params(machine: String).returns(String) }
165
+ def arch(machine)
166
+ case machine.downcase
167
+ when "x86_64", "amd64", "x64" then "x64"
168
+ when "aarch64", "arm64" then "arm64"
169
+ else machine
170
+ end
171
+ end
172
+
173
+ sig { returns(Integer) }
174
+ def buffer_size
175
+ @mutex.synchronize { @buffer.size }
176
+ end
177
+
178
+ # Test helper, called from AgentCat.reset!.
179
+ sig { void }
180
+ def reset!
181
+ @mutex.synchronize do
182
+ @initialized = false
183
+ @enabled = false
184
+ @buffer = []
185
+ @flush_pending = false
186
+ @static_attrs = []
187
+ @record_attrs = []
188
+ end
189
+ end
190
+
191
+ private
192
+
193
+ # The option, then AGENTCAT_DISABLE_DIAGNOSTICS, then the test environment. The
194
+ # unprefixed DISABLE_DIAGNOSTICS can only turn diagnostics off, also over a false
195
+ # AGENTCAT_DISABLE_DIAGNOSTICS: a privacy opt-out fails closed.
196
+ sig { params(disabled: T::Boolean).returns(T::Boolean) }
197
+ def compute_enabled?(disabled)
198
+ return false if disabled
199
+
200
+ flag = (env_flag("DISABLE_DIAGNOSTICS") == :disabled) ? :disabled : env_flag("AGENTCAT_DISABLE_DIAGNOSTICS")
201
+ return false if flag == :disabled
202
+ return true if flag == :force_enabled
203
+
204
+ !test_environment?
205
+ end
206
+
207
+ # Mirrors TS `envDiagnosticsFlag`: blank is "unset", false/0/no/off (trimmed, any
208
+ # case) forces it back on, anything else turns it off.
209
+ sig { params(name: String).returns(Symbol) }
210
+ def env_flag(name)
211
+ case ENV[name].to_s.strip.downcase
212
+ when ""
213
+ :unset
214
+ when "false", "0", "no", "off"
215
+ :force_enabled
216
+ else
217
+ :disabled
218
+ end
219
+ end
220
+
221
+ # Off in the same test environments as test mode (TestMode). Not the
222
+ # AGENTCAT_ENABLED answer: forcing the SDK on in tests keeps diagnostics off
223
+ # unless AGENTCAT_DISABLE_DIAGNOSTICS=false forces them on too.
224
+ sig { returns(T::Boolean) }
225
+ def test_environment?
226
+ TestMode.test_environment?
227
+ end
228
+
229
+ sig { returns(String) }
230
+ def endpoint
231
+ base = ENV["AGENTCAT_DIAGNOSTICS_ENDPOINT"].to_s.strip
232
+ base = DEFAULT_ENDPOINT if base.empty?
233
+ base = base.chomp("/")
234
+ base.end_with?(LOGS_PATH) ? base : "#{base}#{LOGS_PATH}"
235
+ end
236
+
237
+ sig { returns(String) }
238
+ def token
239
+ value = ENV["AGENTCAT_DIAGNOSTICS_TOKEN"].to_s.strip
240
+ value.empty? ? DEFAULT_TOKEN : value
241
+ end
242
+
243
+ # Stable per-install id for setups with no project id to attribute telemetry to
244
+ # instead (TS uses `hostname|import.meta.url`): hostname + "|file://" + the
245
+ # gem root, symlinks resolved, hashed. Not the cwd or $0, so every script of one
246
+ # install shares it. The hostname is hashed, never sent.
247
+ sig { returns(String) }
248
+ def install_id
249
+ Digest::SHA256.hexdigest("#{Socket.gethostname}|file://#{GEM_ROOT}").slice(0, 16) || "0" * 16
250
+ rescue => e
251
+ AgentCat.logger.debug { "diagnostics install_id failed: #{e.class}: #{e.message}" }
252
+ "0" * 16
253
+ end
254
+
255
+ sig { returns(T.nilable(String)) }
256
+ def mcp_version
257
+ return nil unless defined?(MCP)
258
+ return nil unless MCP.respond_to?(:const_get) && MCP.const_defined?(:VERSION)
259
+
260
+ MCP::VERSION.to_s
261
+ end
262
+
263
+ sig do
264
+ params(record: T::Hash[String, T.untyped]).returns(T::Boolean)
265
+ end
266
+ def schedule_record(record:)
267
+ @mutex.synchronize do
268
+ @buffer.shift while @buffer.size >= MAX_BUFFER
269
+ @buffer << record
270
+ flush_pending = @flush_pending
271
+ @flush_pending = true
272
+ flush_pending
273
+ end
274
+ end
275
+
276
+ sig do
277
+ params(
278
+ project_id: T.nilable(String),
279
+ integration: String
280
+ ).returns(T::Array[T::Hash[String, T.untyped]])
281
+ end
282
+ def build_static_attributes(project_id, integration)
283
+ attrs = []
284
+ if project_id.nil? || project_id.empty?
285
+ add_attr!(attrs, "agentcat.install_id", install_id)
286
+ else
287
+ add_attr!(attrs, "agentcat.project_id", project_id)
288
+ end
289
+
290
+ add_attr!(attrs, "agentcat.sdk.language", "ruby")
291
+ add_attr!(attrs, "agentcat.sdk.version", AgentCat::VERSION)
292
+ add_attr!(attrs, "agentcat.mcp_sdk.version", mcp_version)
293
+ add_attr!(attrs, "agentcat.integration", integration)
294
+
295
+ add_attr!(attrs, "process.runtime.name", "ruby")
296
+ add_attr!(attrs, "process.runtime.version", RUBY_VERSION)
297
+ add_attr!(attrs, "process.pid", Process.pid)
298
+
299
+ # Node vocabulary, and no host.cpu.count.
300
+ uname = self.uname
301
+ sysname = uname[:sysname]
302
+ machine = uname[:machine]
303
+ add_attr!(attrs, "os.type", sysname && os_type(sysname))
304
+ add_attr!(attrs, "os.version", uname[:release])
305
+ add_attr!(attrs, "host.arch", machine && arch(machine))
306
+
307
+ add_attr!(attrs, "deployment.environment", deployment_environment)
308
+ attrs
309
+ end
310
+
311
+ sig { returns(T::Hash[Symbol, T.nilable(String)]) }
312
+ def uname
313
+ Etc.uname
314
+ rescue => e
315
+ AgentCat.logger.debug { "diagnostics uname failed: #{e.class}: #{e.message}" }
316
+ {}
317
+ end
318
+
319
+ # The Rack/Rails names, like NODE_ENV in TS and APP_ENV in PHP. Blank counts as unset.
320
+ sig { returns(T.nilable(String)) }
321
+ def deployment_environment
322
+ %w[RAILS_ENV RACK_ENV].each do |name|
323
+ value = ENV[name].to_s.strip
324
+ return value unless value.empty?
325
+ end
326
+ nil
327
+ end
328
+
329
+ sig { returns(T::Array[T::Hash[String, T.untyped]]) }
330
+ def build_record_attributes
331
+ attrs = []
332
+ add_attr!(attrs, "agentcat.sdk.version", AgentCat::VERSION)
333
+ add_attr!(attrs, "agentcat.mcp_sdk.version", mcp_version)
334
+ add_attr!(attrs, "process.runtime.version", RUBY_VERSION)
335
+ attrs
336
+ end
337
+
338
+ sig { params(level: Symbol, message: String).returns(T::Hash[String, T.untyped]) }
339
+ def build_record(level, message)
340
+ severity, text = SEVERITY.fetch(level, SEVERITY[:info])
341
+ {
342
+ "timeUnixNano" => (Time.now.to_r * 1_000_000_000).to_i.to_s,
343
+ "severityNumber" => severity,
344
+ "severityText" => text,
345
+ "body" => {"stringValue" => message},
346
+ "attributes" => @record_attrs
347
+ }
348
+ end
349
+
350
+ sig { params(records: T::Array[T::Hash[T.untyped, T.untyped]]).returns(T::Hash[String, T.untyped]) }
351
+ def build_payload(records)
352
+ {
353
+ "resourceLogs" => [
354
+ {
355
+ "resource" => {"attributes" => @static_attrs},
356
+ "scopeLogs" => [
357
+ {
358
+ "scope" => {"name" => SCOPE_NAME, "version" => AgentCat::VERSION},
359
+ "logRecords" => records
360
+ }
361
+ ]
362
+ }
363
+ ]
364
+ }
365
+ end
366
+
367
+ sig { void }
368
+ def spawn_flush
369
+ Thread.new do
370
+ sleep(FLUSH_DELAY)
371
+ @mutex.synchronize { @flush_pending = false }
372
+ flush
373
+ end
374
+ rescue ThreadError
375
+ nil
376
+ end
377
+
378
+ sig { params(payload: T::Hash[String, T.untyped]).void }
379
+ def post(payload)
380
+ sender = http_post || default_http_post
381
+ sender.call(endpoint, build_headers, payload.to_json)
382
+ end
383
+
384
+ sig { returns(T::Hash[String, String]) }
385
+ def build_headers
386
+ {
387
+ "Content-Type" => "application/json",
388
+ "Authorization" => "Bearer #{token}",
389
+ "User-Agent" => "agentcat-ruby/#{AgentCat::VERSION}"
390
+ }
391
+ end
392
+
393
+ # Doesn't raise on non-2xx.
394
+ sig do
395
+ returns(
396
+ T.proc.params(
397
+ url: String,
398
+ headers: T::Hash[String, String],
399
+ body: String
400
+ ).returns([Integer, String])
401
+ )
402
+ end
403
+ def default_http_post
404
+ lambda do |url, headers, body|
405
+ HttpPost.call(url, headers, body, open_timeout: CONNECT_TIMEOUT, read_timeout: TOTAL_TIMEOUT, deadline: TOTAL_TIMEOUT)
406
+ end
407
+ end
408
+
409
+ sig { params(level: Symbol, message: String).void }
410
+ def file_log(level, message)
411
+ path = File.join(Dir.home, LOCAL_LOG_NAME)
412
+ File.open(path, "a") do |file|
413
+ file.puts "[agentcat] #{Time.now.utc.iso8601} #{level.to_s.upcase}: #{message}"
414
+ end
415
+ rescue => e
416
+ AgentCat.logger.debug { "diagnostics file log failed: #{e.class}: #{e.message}" }
417
+ end
418
+
419
+ sig do
420
+ params(
421
+ attrs: T::Array[T::Hash[String, T.untyped]],
422
+ key: String,
423
+ value: T.untyped
424
+ ).void
425
+ end
426
+ def add_attr!(attrs, key, value)
427
+ return if value.nil?
428
+ return if value.to_s.empty?
429
+
430
+ attrs << {"key" => key, "value" => {"stringValue" => value.to_s}}
431
+ end
432
+ end
433
+ end
434
+ end
@@ -0,0 +1,117 @@
1
+ # typed: true
2
+
3
+ require_relative "payload_limits"
4
+ require_relative "truncation"
5
+
6
+ module AgentCat
7
+ # Converts a raised exception into the structured error payload the Go and TypeScript
8
+ # SDKs send: message, type, platform, a raw stack string, structured frames (function/
9
+ # filename/lineno/in_app), and the `#cause` chain. Ruby's `backtrace_locations` already
10
+ # gives structured frames for free - no need to parse a stack-trace string the way the
11
+ # Go SDK does.
12
+ #
13
+ # Never raises: a malformed error (a custom #message that itself raises, for example)
14
+ # falls back to a minimal payload rather than taking the publish pipeline down with it.
15
+ module ErrorCapture
16
+ extend T::Sig
17
+
18
+ PLATFORM = "ruby"
19
+
20
+ sig { params(error: Exception).returns(T::Hash[String, T.untyped]) }
21
+ def self.capture(error)
22
+ {
23
+ "message" => safe_message(error),
24
+ "type" => error.class.name,
25
+ "platform" => PLATFORM
26
+ }.merge(stack_and_frames(error)).merge(chain(error))
27
+ rescue => e
28
+ {
29
+ "message" => "[error capture failed: #{e.class}: #{e.message}]",
30
+ "type" => error.class.name,
31
+ "platform" => PLATFORM
32
+ }
33
+ end
34
+
35
+ # The error of an isError tool result with no exception behind it, like the TS
36
+ # SDK's `captureCallToolResultError`: its text blocks joined by a space as the
37
+ # message, no type and no stack. nil for a result that isn't an isError result.
38
+ sig { params(result: T.untyped).returns(T.nilable(T::Hash[String, T.untyped])) }
39
+ def self.capture_result(result)
40
+ return nil unless result.is_a?(Hash)
41
+
42
+ flag = result.key?(:isError) ? result[:isError] : result["isError"]
43
+ content = result.key?(:content) ? result[:content] : result["content"]
44
+ return nil unless flag == true && content.is_a?(Array)
45
+
46
+ texts = content.filter_map do |block|
47
+ next if !block.is_a?(Hash) || (block[:type] || block["type"]) != "text"
48
+
49
+ block.key?(:text) ? block[:text] : block["text"]
50
+ end
51
+ message = texts.join(" ").strip
52
+ {"message" => message.empty? ? "Unknown error" : message, "platform" => PLATFORM}
53
+ end
54
+
55
+ sig { params(error: Exception).returns(T::Hash[String, T.untyped]) }
56
+ def self.stack_and_frames(error)
57
+ backtrace = error.backtrace
58
+ return {} if backtrace.nil? || backtrace.empty?
59
+
60
+ result = T.let({"stack" => backtrace.join("\n")}, T::Hash[String, T.untyped])
61
+ frames = frames_from(error)
62
+ result["frames"] = Truncation.truncate_frames(frames) unless frames.empty?
63
+ result
64
+ end
65
+ private_class_method :stack_and_frames
66
+
67
+ sig { params(error: Exception).returns(T::Array[T::Hash[String, T.untyped]]) }
68
+ def self.frames_from(error)
69
+ locations = error.backtrace_locations
70
+ return [] if locations.nil?
71
+
72
+ locations.map do |location|
73
+ path = location.absolute_path || location.path
74
+ {
75
+ "function" => location.label,
76
+ "filename" => location.path,
77
+ "abs_path" => path,
78
+ "lineno" => location.lineno,
79
+ "in_app" => in_app?(path)
80
+ }
81
+ end
82
+ end
83
+ private_class_method :frames_from
84
+
85
+ # Library/stdlib frames (this gem included) are noise next to the tool's own code.
86
+ sig { params(path: T.nilable(String)).returns(T::Boolean) }
87
+ def self.in_app?(path)
88
+ return true if path.nil?
89
+
90
+ !(Gem.path.any? { |gem_dir| path.start_with?(gem_dir) } || path.start_with?(RbConfig::CONFIG["rubylibdir"]))
91
+ end
92
+ private_class_method :in_app?
93
+
94
+ sig { params(error: Exception).returns(T::Hash[String, T.untyped]) }
95
+ def self.chain(error)
96
+ chained = []
97
+ seen = Set.new
98
+ current = T.let(error.cause, T.nilable(Exception))
99
+ while current && seen.add?(current.object_id) && chained.size < PayloadLimits::MAX_CHAIN_DEPTH
100
+ entry = T.let({"message" => safe_message(current), "type" => current.class.name}, T::Hash[String, T.untyped])
101
+ entry.merge!(stack_and_frames(current))
102
+ chained << entry
103
+ current = current.cause
104
+ end
105
+ chained.empty? ? {} : {"chained_errors" => chained}
106
+ end
107
+ private_class_method :chain
108
+
109
+ sig { params(error: Exception).returns(String) }
110
+ def self.safe_message(error)
111
+ error.message.to_s
112
+ rescue => e
113
+ "[message capture failed: #{e.class}]"
114
+ end
115
+ private_class_method :safe_message
116
+ end
117
+ end
@@ -0,0 +1,19 @@
1
+ # typed: true
2
+
3
+ module AgentCat
4
+ # Mints "evt_<KSUID>" ids, same scheme as session ids ("ses_"). The events API
5
+ # will happily 202 a request with no id and then silently drop it server-side,
6
+ # so don't skip this.
7
+ class EventId
8
+ PREFIX = "evt_"
9
+
10
+ class << self
11
+ extend T::Sig
12
+
13
+ sig { returns(String).checked(:tests) }
14
+ def mint
15
+ SessionManager.mint_id(T.must(PREFIX))
16
+ end
17
+ end
18
+ end
19
+ end