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.
- checksums.yaml +4 -4
- data/LICENSE +2 -11
- data/README.md +265 -20
- data/lib/agentcat/adapters/base.rb +73 -0
- data/lib/agentcat/adapters/official.rb +194 -0
- data/lib/agentcat/client.rb +171 -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 +711 -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 +271 -0
- data/lib/agentcat/redaction.rb +115 -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/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 +201 -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 +391 -21
- metadata +193 -16
- 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
|