agentcat 0.0.1 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) 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 +73 -0
  5. data/lib/agentcat/adapters/official.rb +194 -0
  6. data/lib/agentcat/client.rb +171 -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 +711 -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 +271 -0
  30. data/lib/agentcat/redaction.rb +115 -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/session_manager.rb +83 -0
  36. data/lib/agentcat/tags.rb +61 -0
  37. data/lib/agentcat/test_mode.rb +86 -0
  38. data/lib/agentcat/testing.rb +153 -0
  39. data/lib/agentcat/text.rb +68 -0
  40. data/lib/agentcat/token_estimate.rb +98 -0
  41. data/lib/agentcat/tool_call.rb +129 -0
  42. data/lib/agentcat/tool_handle.rb +289 -0
  43. data/lib/agentcat/tracker.rb +201 -0
  44. data/lib/agentcat/truncation.rb +265 -0
  45. data/lib/agentcat/unredacted_event.rb +155 -0
  46. data/lib/agentcat/user_identity.rb +11 -0
  47. data/lib/agentcat/version.rb +2 -2
  48. data/lib/agentcat.rb +391 -21
  49. metadata +193 -16
  50. data/agentcat.gemspec +0 -30
@@ -0,0 +1,171 @@
1
+ # typed: strict
2
+
3
+ require "uri"
4
+ require "agentcat-api"
5
+ require_relative "diagnostics"
6
+
7
+ module AgentCatApi
8
+ # `PublishEventRequest#event_type=` validates against the OpenAPI spec's enum, which
9
+ # predates `agentcat:custom` (see `AgentCat::Client::CUSTOM_EVENT_TYPE`) — the backend
10
+ # has accepted that value since the TypeScript SDK's 2.0 release, but every generated
11
+ # client (Ruby, Python, TS's own type alias) still ships the stale list, because
12
+ # they're all generated from the same spec snapshot. Left alone, every custom event
13
+ # would fail construction right here and vanish into `Client#post_event`'s rescue.
14
+ #
15
+ # Same fix the Python SDK ships (`agentcat/types.py`'s `Event#event_type_validate_enum`
16
+ # override) — don't remove this expecting a future `agentcat-api` bump to carry it;
17
+ # regenerating from the same stale spec would silently reintroduce the rejection.
18
+ # `test/test_client.rb`'s custom-event-type test is the tripwire.
19
+ class PublishEventRequest
20
+ extend T::Sig
21
+
22
+ alias_method :_generated_event_type=, :event_type=
23
+
24
+ sig { params(event_type: T.untyped).void }
25
+ def event_type=(event_type)
26
+ if event_type == AgentCat::Client::CUSTOM_EVENT_TYPE
27
+ @event_type = T.let(event_type, T.nilable(String))
28
+ else
29
+ self._generated_event_type = event_type
30
+ end
31
+ end
32
+ end
33
+
34
+ # Every generated model's `_to_hash` calls `value.compact` on arrays before it maps
35
+ # them, so a payload array `[1, nil, 2]` would go out as `[1, 2]`, and the event would not
36
+ # say what the tool got or returned. Same reasoning as the `event_type=` reopening
37
+ # above - a regenerated `agentcat-api` would bring the `compact` back, so the fix
38
+ # lives here. `test/test_client.rb`'s nil-element tests are the tripwire.
39
+ module KeepNilArrayElements
40
+ extend T::Sig
41
+
42
+ sig { params(value: T.untyped).returns(T.untyped) }
43
+ def _to_hash(value)
44
+ return value.map { |element| _to_hash(element) } if value.is_a?(Array)
45
+
46
+ super
47
+ end
48
+ end
49
+
50
+ constants.each do |name|
51
+ klass = const_get(name)
52
+ next unless klass.is_a?(Class) && klass.method_defined?(:_to_hash)
53
+
54
+ klass.prepend(KeepNilArrayElements) unless klass.ancestors.include?(KeepNilArrayElements)
55
+ end
56
+ end
57
+
58
+ module AgentCat
59
+ # Thin wrapper around the generated agentcat-api client. Runs on the event queue's
60
+ # worker thread, never the caller's (see EventQueue, Delivery).
61
+ #
62
+ # AGENTCAT_API_URL is just the base (scheme, host, optional port/path prefix) — the
63
+ # generated client appends the events path itself.
64
+ class Client
65
+ DEFAULT_API_URL = "https://api.agentcat.com"
66
+ ENV_API_URL = "AGENTCAT_API_URL"
67
+ ENV_API_KEY = "AGENTCAT_API_KEY"
68
+ # See the `AgentCatApi::PublishEventRequest` reopening above this class.
69
+ CUSTOM_EVENT_TYPE = "agentcat:custom"
70
+ # Without these a hung connection stalls the worker thread forever and the queue
71
+ # just stops draining. 10s read / 1s open, matching the reference SDKs;
72
+ # Options#request_timeout overrides the read side.
73
+ OPEN_TIMEOUT_SECONDS = 1
74
+ DEFAULT_READ_TIMEOUT_SECONDS = 10
75
+ EVENT_FIELDS = T.let(AgentCatApi::PublishEventRequest.attribute_map.keys.freeze, T::Array[Symbol])
76
+
77
+ # First `track` call wins — this is process-wide, same as the queue and exporters.
78
+ @configured_read_timeout = T.let(nil, T.nilable(Float))
79
+ @configured_api_url = T.let(nil, T.nilable(String))
80
+
81
+ class << self
82
+ extend T::Sig
83
+
84
+ # `Options#api_base_url` takes precedence over AGENTCAT_API_URL; first `track`
85
+ # call wins, same as the read timeout.
86
+ sig { params(url: String).void }
87
+ def configure_base_url(url)
88
+ @configured_api_url ||= url
89
+ end
90
+
91
+ sig { returns(String) }
92
+ def api_url
93
+ @configured_api_url || env_api_url
94
+ end
95
+
96
+ sig { returns(T.nilable(String)) }
97
+ def api_key
98
+ value = ENV[ENV_API_KEY]
99
+ (value.nil? || value.empty?) ? nil : value
100
+ end
101
+
102
+ sig { params(seconds: Numeric).void }
103
+ def configure_timeout(seconds)
104
+ @configured_read_timeout ||= seconds.to_f
105
+ end
106
+
107
+ sig { returns(Float) }
108
+ def read_timeout_seconds
109
+ @configured_read_timeout || DEFAULT_READ_TIMEOUT_SECONDS.to_f
110
+ end
111
+
112
+ sig { void }
113
+ def reset_timeout!
114
+ @configured_read_timeout = nil
115
+ end
116
+
117
+ sig { void }
118
+ def reset_base_url!
119
+ @configured_api_url = nil
120
+ end
121
+
122
+ # Publishes one event. Never raises; returns the API response or nil on failure.
123
+ sig { params(event: T::Hash[Symbol, T.untyped]).returns(T.nilable(AgentCatApi::EventAcceptedResponse)).checked(:tests) }
124
+ def post_event(event)
125
+ attributes = EVENT_FIELDS.each_with_object({}) { |field, acc| acc[field] = event[field] if event.key?(field) }
126
+ request = AgentCatApi::PublishEventRequest.new(attributes)
127
+ headers = {}
128
+ headers["Authorization"] = "Bearer #{api_key}" if api_key
129
+
130
+ # Authorization is set explicitly above; disabling the generated auth scheme avoids a nil header when no key is configured.
131
+ events_api.publish_event(publish_event_request: request, header_params: headers, debug_auth_names: [])
132
+ rescue => e
133
+ # The API error's message carries the response body: debug only.
134
+ code = e.is_a?(AgentCatApi::ApiError) ? e.code : nil
135
+ status = code ? " (HTTP #{code})" : ""
136
+ AgentCat::Log.error("failed to publish event to AgentCat: #{e.class}#{status}")
137
+ AgentCat.logger.debug { "failed to publish event: #{e.class}: #{e.message}" }
138
+ nil
139
+ end
140
+
141
+ sig { returns(AgentCatApi::Configuration) }
142
+ def configuration
143
+ uri = URI.parse(api_url)
144
+ AgentCatApi::Configuration.new.tap do |config|
145
+ config.scheme = uri.scheme
146
+ config.host = (uri.port == uri.default_port) ? uri.host : "#{uri.host}:#{uri.port}"
147
+ config.base_path = uri.path.to_s.sub(%r{/+\z}, "")
148
+ config.ignore_operation_servers = true
149
+ config.timeout = read_timeout_seconds
150
+ config.configure_faraday_connection do |conn|
151
+ conn.options.open_timeout = OPEN_TIMEOUT_SECONDS
152
+ conn.options.timeout = read_timeout_seconds
153
+ end
154
+ end
155
+ end
156
+
157
+ private
158
+
159
+ sig { returns(String) }
160
+ def env_api_url
161
+ value = ENV[ENV_API_URL]
162
+ (value.nil? || value.empty?) ? DEFAULT_API_URL : value
163
+ end
164
+
165
+ sig { returns(AgentCatApi::EventsApi) }
166
+ def events_api
167
+ AgentCatApi::EventsApi.new(AgentCatApi::ApiClient.new(configuration))
168
+ end
169
+ end
170
+ end
171
+ end
@@ -0,0 +1,16 @@
1
+ # typed: true
2
+
3
+ module AgentCat
4
+ # Monotonic clock for measuring elapsed time. Don't use Time.now for this; NTP can
5
+ # step it backwards mid-call. Interceptor and EventQueue both depend on it.
6
+ module Clock
7
+ class << self
8
+ extend T::Sig
9
+
10
+ sig { returns(Float) }
11
+ def monotonic_now
12
+ Process.clock_gettime(Process::CLOCK_MONOTONIC).to_f
13
+ end
14
+ end
15
+ end
16
+ end
@@ -0,0 +1,215 @@
1
+ # typed: true
2
+
3
+ require_relative "client"
4
+ require_relative "event_id"
5
+ require_relative "unredacted_event"
6
+ require_relative "tags"
7
+ require_relative "delivery"
8
+ require_relative "event_pipeline"
9
+
10
+ module AgentCat
11
+ # `AgentCat.publish_custom_event`'s body - one `agentcat:custom` event for work
12
+ # that is not a tool call: a background job, a webhook, a checkout step, anything
13
+ # the customer wants on the same timeline as the tool calls AgentCat captures
14
+ # automatically.
15
+ #
16
+ # Parity with the canonical SDKs' `publishCustomEvent`/`publish_custom_event`
17
+ # (TS/Python) - Python's is the more defensive of the two, and is what this
18
+ # follows field-for-field: fire-and-forget (never raises), and a single
19
+ # unusable field costs only that field, never the whole event.
20
+ module CustomEvent
21
+ extend T::Sig
22
+
23
+ sig do
24
+ params(
25
+ server_or_session_id: T.untyped,
26
+ project_id: T.untyped,
27
+ session_id: T.untyped,
28
+ resource_name: T.untyped,
29
+ parameters: T.untyped,
30
+ response: T.untyped,
31
+ message: T.untyped,
32
+ duration: T.untyped,
33
+ is_error: T.untyped,
34
+ error: T.untyped,
35
+ tags: T.untyped,
36
+ properties: T.untyped
37
+ ).void
38
+ end
39
+ def self.publish(
40
+ server_or_session_id,
41
+ project_id,
42
+ session_id: nil,
43
+ resource_name: nil,
44
+ parameters: nil,
45
+ response: nil,
46
+ message: nil,
47
+ duration: nil,
48
+ is_error: nil,
49
+ error: nil,
50
+ tags: nil,
51
+ properties: nil
52
+ )
53
+ session_id = wire_string("session_id", session_id)
54
+ session_id = nil if session_id && session_id.empty?
55
+
56
+ event = build_event(
57
+ resource_name: resource_name, parameters: parameters, response: response,
58
+ message: message, duration: duration, is_error: is_error, error: error,
59
+ tags: tags, properties: properties
60
+ )
61
+
62
+ if server_or_session_id.is_a?(String)
63
+ # TS: `eventData.sessionId || serverOrSessionId`, and "" goes out as null.
64
+ publish_untracked(event, session_id || (server_or_session_id.empty? ? nil : server_or_session_id), project_id)
65
+ else
66
+ publish_tracked(event, server_or_session_id, session_id)
67
+ end
68
+ rescue => e
69
+ Log.error("failed to publish custom event: #{e.class}; the event is lost")
70
+ AgentCat.logger.debug { "failed to publish custom event: #{e.class}: #{e.message}" }
71
+ end
72
+
73
+ sig { params(event: UnredactedEvent, session_id: T.nilable(String), project_id: T.untyped).void }
74
+ def self.publish_untracked(event, session_id, project_id)
75
+ project = wire_string("project_id", project_id)
76
+ if project.nil? || project.empty?
77
+ Log.warn("publish_custom_event: project_id is required when the first argument is a session ID string; event dropped")
78
+ return
79
+ end
80
+
81
+ event.session_id = session_id
82
+ event.project_id = project
83
+ epoch = AgentCat.event_epoch
84
+ # No tracker, so no hooks and no per-server exporters: like TS's queue, the event
85
+ # goes to the process-wide exporters (the first `track` that had any).
86
+ exporters = AgentCat.process_exporters
87
+ AgentCat.event_queue.enqueue do
88
+ EventPipeline.normalize(event, label: "a custom event")
89
+ next if EventPipeline.record_in_fake(event, epoch)
90
+
91
+ Delivery.publish(AgentCat::Client, event.to_wire_hash, epoch: epoch)
92
+ Exporters.dispatch(exporters, event)
93
+ end
94
+ end
95
+ private_class_method :publish_untracked
96
+
97
+ sig { params(event: UnredactedEvent, server: T.untyped, session_id: T.nilable(String)).void }
98
+ def self.publish_tracked(event, server, session_id)
99
+ tracker = AgentCat.tracker_for(server)
100
+ unless tracker
101
+ Log.warn(
102
+ "publish_custom_event: first argument is neither a tracked server nor a session ID string " \
103
+ "(got #{server.class}); event dropped. Call AgentCat.track() first, or pass a session ID."
104
+ )
105
+ return
106
+ end
107
+
108
+ options = tracker.options
109
+ # Tracing off means nothing gets published for this server, custom events included.
110
+ # Accepted and dropped quietly, same as the Go SDK.
111
+ return unless options.enable_tracing
112
+
113
+ event.session_id = session_id
114
+ event.project_id = tracker.project_id
115
+ epoch = AgentCat.event_epoch
116
+ AgentCat.event_queue(queue_size: options.queue_size).enqueue do
117
+ EventPipeline.run(event, tracker, epoch: epoch, label: "a custom event", redact_strings: false)
118
+ end
119
+ end
120
+ private_class_method :publish_tracked
121
+
122
+ sig do
123
+ params(
124
+ resource_name: T.untyped,
125
+ parameters: T.untyped,
126
+ response: T.untyped,
127
+ message: T.untyped,
128
+ duration: T.untyped,
129
+ is_error: T.untyped,
130
+ error: T.untyped,
131
+ tags: T.untyped,
132
+ properties: T.untyped
133
+ ).returns(UnredactedEvent)
134
+ end
135
+ def self.build_event(resource_name:, parameters:, response:, message:, duration:, is_error:, error:, tags:, properties:)
136
+ UnredactedEvent.new(
137
+ project_id: nil,
138
+ id: EventId.mint,
139
+ session_id: nil,
140
+ event_type: AgentCat::Client::CUSTOM_EVENT_TYPE,
141
+ resource_name: wire_string("resource_name", resource_name) || "",
142
+ parameters: wire_payload("parameters", parameters) || {},
143
+ user_intent: wire_string("message", message),
144
+ response: wire_payload("response", response),
145
+ is_error: wire_bool("is_error", is_error) || false,
146
+ error: wire_error(error),
147
+ duration: wire_integer("duration", duration) || 0,
148
+ timestamp: Time.now.utc.iso8601(3),
149
+ agentcat_version: AgentCat::VERSION,
150
+ tags: Tags.sanitize(wire_hash("tags", tags), "publish_custom_event tags"),
151
+ properties: wire_payload("properties", properties) || {}
152
+ )
153
+ end
154
+ private_class_method :build_event
155
+
156
+ # A value the wire's strict scalar field can hold, or nil. One unusable field is
157
+ # not worth the whole event - log and drop it, never raise.
158
+ sig { params(field: String, value: T.untyped).returns(T.nilable(String)) }
159
+ def self.wire_string(field, value)
160
+ return value if value.nil? || value.is_a?(String)
161
+
162
+ Log.warn("publish_custom_event: dropping '#{field}' - expected String, got #{value.class}")
163
+ nil
164
+ end
165
+ private_class_method :wire_string
166
+
167
+ sig { params(field: String, value: T.untyped).returns(T.nilable(Integer)) }
168
+ def self.wire_integer(field, value)
169
+ return value if value.nil? || value.is_a?(Integer)
170
+
171
+ Log.warn("publish_custom_event: dropping '#{field}' - expected Integer, got #{value.class}")
172
+ nil
173
+ end
174
+ private_class_method :wire_integer
175
+
176
+ sig { params(field: String, value: T.untyped).returns(T.nilable(T::Boolean)) }
177
+ def self.wire_bool(field, value)
178
+ return value if value.nil? || value == true || value == false
179
+
180
+ Log.warn("publish_custom_event: dropping '#{field}' - expected true/false, got #{value.class}")
181
+ nil
182
+ end
183
+ private_class_method :wire_bool
184
+
185
+ sig { params(field: String, value: T.untyped).returns(T.nilable(T::Hash[T.untyped, T.untyped])) }
186
+ def self.wire_hash(field, value)
187
+ return value if value.nil? || value.is_a?(Hash)
188
+
189
+ Log.warn("publish_custom_event: dropping '#{field}' - expected a Hash, got #{value.class}")
190
+ nil
191
+ end
192
+ private_class_method :wire_hash
193
+
194
+ # `parameters`/`response`/`properties` hold whatever the caller wants recorded, so a
195
+ # non-Hash is a plausible payload, not a mistake - wrapped, never dropped.
196
+ sig { params(field: String, value: T.untyped).returns(T.nilable(T::Hash[T.untyped, T.untyped])) }
197
+ def self.wire_payload(field, value)
198
+ return value if value.nil? || value.is_a?(Hash)
199
+
200
+ Log.warn("publish_custom_event: wrapping non-Hash '#{field}' (#{value.class}) as {value: ...}")
201
+ {"value" => value}
202
+ end
203
+ private_class_method :wire_payload
204
+
205
+ # `error` has a known shape consumers read `message` from, so a bare value becomes
206
+ # one rather than a `{value: ...}` payload.
207
+ sig { params(value: T.untyped).returns(T.nilable(T::Hash[T.untyped, T.untyped])) }
208
+ def self.wire_error(value)
209
+ return value if value.nil? || value.is_a?(Hash)
210
+
211
+ {"message" => value.to_s}
212
+ end
213
+ private_class_method :wire_error
214
+ end
215
+ end
@@ -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