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,190 @@
1
+ # typed: true
2
+
3
+ require_relative "clock"
4
+ require_relative "log"
5
+
6
+ module AgentCat
7
+ # Runs a user-supplied hook with a timeout, isolated from the call it's attached to.
8
+ # A hook that misbehaves (raises, times out, returns garbage) just loses that one
9
+ # event's data — it never takes the tool call down with it.
10
+ module Hooks
11
+ class << self
12
+ extend T::Sig
13
+
14
+ # Returns the hook's value, or nil if it's absent, raises, times out, or isn't callable.
15
+ # A failure logs one WARN line (rate-limited, see `Log`) naming the hook option and
16
+ # the exception class; the exception message, which can carry the hook's input, goes
17
+ # to debug.
18
+ sig { params(hook: T.untyped, args: T.untyped, timeout: Numeric, name: String).returns(T.untyped).checked(:tests) }
19
+ def run(hook, *args, timeout: 1, name: "hook")
20
+ return nil unless hook
21
+
22
+ validate_callable!(hook)
23
+
24
+ thread = Thread.new { hook.call(*args) }
25
+ thread.report_on_exception = false
26
+ thread.join(timeout)
27
+
28
+ if thread.alive?
29
+ thread.kill
30
+ Log.warn("#{name} hook timed out after #{timeout}s")
31
+ return nil
32
+ end
33
+
34
+ thread.value
35
+ rescue => e
36
+ Log.warn("#{name} hook raised #{e.class}")
37
+ AgentCat.logger.debug { "#{name} hook raised #{e.class}: #{e.message}" }
38
+ nil
39
+ end
40
+
41
+ # Hooks that see a call (`identify`, `resolve_session_id`, `event_tags`,
42
+ # `event_properties`) take one `AgentCat::ToolCall`. A hook that still
43
+ # needs two arguments (the old `(arguments, server_context)`) gets one WARN line
44
+ # naming the new form. It is still called with the ToolCall: a lambda then raises
45
+ # ArgumentError, which costs the hook's value for that call, never the call.
46
+ sig { params(hook: T.untyped, name: String).void }
47
+ def warn_if_two_arguments(hook, name)
48
+ return if hook.nil?
49
+
50
+ callable = (hook.is_a?(Proc) || hook.is_a?(Method)) ? hook : hook.method(:call)
51
+ arity = callable.arity
52
+ return unless arity >= 2 || arity <= -3
53
+
54
+ Log.warn("#{name} takes 2 arguments, but hooks now get one AgentCat::ToolCall: " \
55
+ "change ->(arguments, server_context) { ... } to ->(tool_call) { ... } " \
56
+ "and read tool_call.arguments and tool_call.server_context")
57
+ rescue
58
+ nil
59
+ end
60
+
61
+ private
62
+
63
+ sig { params(hook: T.untyped).void }
64
+ def validate_callable!(hook)
65
+ return if hook.respond_to?(:call)
66
+
67
+ raise ArgumentError, "hook must respond to #call, got #{hook.class}"
68
+ end
69
+ end
70
+
71
+ # `Hooks.run` for a hook called once per value (redact_sensitive_information on
72
+ # every string of an event): one thread for the whole pass instead of one per call,
73
+ # which on a big response cost far more than the hook itself. Each call still gets
74
+ # its own timeout; a call that runs past it kills the thread and the next call
75
+ # starts a fresh one. `close` when done. Failures log at debug only: the caller
76
+ # (Redaction) logs the WARN line, once for the event it drops.
77
+ class Worker
78
+ extend T::Sig
79
+
80
+ sig { params(hook: T.untyped, timeout: Numeric).void }
81
+ def initialize(hook, timeout:)
82
+ @hook = hook
83
+ @timeout = timeout
84
+ @inbox = T.let(nil, T.nilable(Thread::Queue))
85
+ @thread = T.let(nil, T.nilable(Thread))
86
+ end
87
+
88
+ # Same contract as `Hooks.run`: the hook's value, or nil if it raised or timed out.
89
+ sig { params(args: T.untyped).returns(T.untyped) }
90
+ def call(*args)
91
+ start unless @thread&.alive?
92
+ slot = Slot.new
93
+ T.must(@inbox) << [args, slot]
94
+
95
+ unless slot.wait(@timeout)
96
+ stop
97
+ AgentCat.logger.debug { "hook timed out after #{@timeout}s" }
98
+ return nil
99
+ end
100
+
101
+ error = slot.error
102
+ return slot.value unless error
103
+
104
+ AgentCat.logger.debug { "hook raised #{error.class}: #{error.message}" }
105
+ nil
106
+ end
107
+
108
+ sig { void }
109
+ def close
110
+ @inbox&.close
111
+ @inbox = nil
112
+ @thread = nil
113
+ end
114
+
115
+ private
116
+
117
+ sig { void }
118
+ def start
119
+ inbox = @inbox = Thread::Queue.new
120
+ hook = @hook
121
+ @thread = Thread.new do
122
+ while (job = inbox.pop)
123
+ args, slot = job
124
+ begin
125
+ slot.fulfill(value: hook.call(*args))
126
+ # Anything worse than a StandardError takes the thread down with it; the
127
+ # caller then just waits out the timeout, same as a hung call.
128
+ rescue => e
129
+ slot.fulfill(error: e)
130
+ end
131
+ end
132
+ end
133
+ T.must(@thread).report_on_exception = false
134
+ end
135
+
136
+ sig { void }
137
+ def stop
138
+ @thread&.kill
139
+ @inbox&.close
140
+ @inbox = nil
141
+ @thread = nil
142
+ end
143
+
144
+ # One call's result, handed from the worker thread back to the caller.
145
+ class Slot
146
+ extend T::Sig
147
+
148
+ sig { returns(T.untyped) }
149
+ attr_reader :value
150
+
151
+ sig { returns(T.nilable(Exception)) }
152
+ attr_reader :error
153
+
154
+ sig { void }
155
+ def initialize
156
+ @mutex = Mutex.new
157
+ @done_signal = ConditionVariable.new
158
+ @done = T.let(false, T::Boolean)
159
+ @value = T.let(nil, T.untyped)
160
+ @error = T.let(nil, T.nilable(Exception))
161
+ end
162
+
163
+ sig { params(value: T.untyped, error: T.nilable(Exception)).void }
164
+ def fulfill(value: nil, error: nil)
165
+ @mutex.synchronize do
166
+ @value = value
167
+ @error = error
168
+ @done = true
169
+ @done_signal.signal
170
+ end
171
+ end
172
+
173
+ # false when `timeout` ran out first.
174
+ sig { params(timeout: Numeric).returns(T::Boolean) }
175
+ def wait(timeout)
176
+ deadline = Clock.monotonic_now + timeout
177
+ @mutex.synchronize do
178
+ until @done
179
+ remaining = deadline - Clock.monotonic_now
180
+ return false if remaining <= 0
181
+
182
+ @done_signal.wait(@mutex, remaining)
183
+ end
184
+ end
185
+ true
186
+ end
187
+ end
188
+ end
189
+ end
190
+ end
@@ -0,0 +1,61 @@
1
+ # typed: true
2
+
3
+ require "net/http"
4
+ require "timeout"
5
+ require "uri"
6
+
7
+ module AgentCat
8
+ # Shared by every HTTP exporter and the diagnostics beacon. Callers pick their own
9
+ # timeouts. Doesn't raise on
10
+ # a non-2xx response — the caller decides what that means.
11
+ #
12
+ # `open_timeout`/`read_timeout` are per step (a server that trickles bytes never
13
+ # trips `read_timeout`); `deadline`, when given, bounds the whole request, DNS
14
+ # lookup included, and raises Timeout::Error when it runs out.
15
+ module HttpPost
16
+ class << self
17
+ extend T::Sig
18
+
19
+ sig do
20
+ params(
21
+ url: String,
22
+ headers: T::Hash[String, String],
23
+ body: String,
24
+ open_timeout: Numeric,
25
+ read_timeout: Numeric,
26
+ deadline: T.nilable(Numeric)
27
+ ).returns([Integer, String])
28
+ end
29
+ def call(url, headers, body, open_timeout:, read_timeout:, deadline: nil)
30
+ return post(url, headers, body, open_timeout, read_timeout) if deadline.nil?
31
+
32
+ Timeout.timeout(deadline) { post(url, headers, body, open_timeout, read_timeout) }
33
+ end
34
+
35
+ private
36
+
37
+ sig do
38
+ params(
39
+ url: String,
40
+ headers: T::Hash[String, String],
41
+ body: String,
42
+ open_timeout: Numeric,
43
+ read_timeout: Numeric
44
+ ).returns([Integer, String])
45
+ end
46
+ def post(url, headers, body, open_timeout, read_timeout)
47
+ uri = URI.parse(url)
48
+ http = Net::HTTP.new(uri.host, uri.port)
49
+ http.use_ssl = (uri.scheme == "https")
50
+ http.open_timeout = open_timeout
51
+ http.read_timeout = read_timeout
52
+ http.write_timeout = read_timeout
53
+
54
+ request = Net::HTTP::Post.new(T.unsafe(uri).request_uri, headers)
55
+ request.body = body
56
+ response = http.request(request)
57
+ [response.code.to_i, response.body.to_s]
58
+ end
59
+ end
60
+ end
61
+ end