devfortress-sdk 0.3.0__py3-none-any.whl

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 (38) hide show
  1. devfortress/__init__.py +252 -0
  2. devfortress/agent.py +324 -0
  3. devfortress/agent_loop_detector.py +250 -0
  4. devfortress/agent_output_exfiltration_detector.py +152 -0
  5. devfortress/agent_security.py +560 -0
  6. devfortress/alias_verify.py +185 -0
  7. devfortress/api_key_aliasing.py +424 -0
  8. devfortress/bounded_map.py +53 -0
  9. devfortress/circuit_breaker.py +163 -0
  10. devfortress/classify.py +128 -0
  11. devfortress/client.py +368 -0
  12. devfortress/clock_drift_detector.py +142 -0
  13. devfortress/closed_loop.py +442 -0
  14. devfortress/config_integrity_verifier.py +165 -0
  15. devfortress/credential_isolation.py +433 -0
  16. devfortress/credential_vault.py +111 -0
  17. devfortress/fastapi_middleware.py +131 -0
  18. devfortress/flask_middleware.py +105 -0
  19. devfortress/graduated_rate_limiter.py +282 -0
  20. devfortress/internal_closed_loop_engine.py +782 -0
  21. devfortress/license_manager.py +314 -0
  22. devfortress/quick.py +34 -0
  23. devfortress/security_extensions.py +97 -0
  24. devfortress/sensitive_action_monitor.py +188 -0
  25. devfortress/session_fixation_guard.py +145 -0
  26. devfortress/shadow_agent_registry.py +157 -0
  27. devfortress/signing.py +105 -0
  28. devfortress/telemetry.py +435 -0
  29. devfortress/tier_gate.py +456 -0
  30. devfortress/tool_call_sequence_validator.py +206 -0
  31. devfortress/unified_audit_trail.py +272 -0
  32. devfortress/version.py +5 -0
  33. devfortress/webhook.py +113 -0
  34. devfortress_sdk-0.3.0.dist-info/METADATA +57 -0
  35. devfortress_sdk-0.3.0.dist-info/RECORD +38 -0
  36. devfortress_sdk-0.3.0.dist-info/WHEEL +5 -0
  37. devfortress_sdk-0.3.0.dist-info/licenses/LICENSE +63 -0
  38. devfortress_sdk-0.3.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,252 @@
1
+ """DevFortress Python SDK (external mode).
2
+
3
+ Event reporting is the original surface: ``DevFortressClient``, the
4
+ Flask/FastAPI middlewares, signing, and webhook verification.
5
+
6
+ Agent security (added in 0.3.0) ports the Node SDK's three core security
7
+ pillars — credential aliasing, agent-identity behavioral fingerprinting,
8
+ and closed-loop response. See each submodule's docstring for what it
9
+ ports and from where. Agent-security symbols are importable from their
10
+ submodules directly (``from devfortress.agent_security import
11
+ AgentBaselineEngine``, etc.) — this top-level ``__init__`` re-exports
12
+ only the event-reporting surface plus the small set of agent-security
13
+ entry points most demos need.
14
+ """
15
+
16
+ from .agent import AgentAdapter, AgentToolCall, ObserveResult, validate_agent_id
17
+ from .agent_loop_detector import AgentLoopDetector, LoopDetectionResult
18
+ from .agent_output_exfiltration_detector import (
19
+ AgentOutput,
20
+ AgentOutputExfiltrationDetector,
21
+ ExfiltrationResult,
22
+ )
23
+ from .agent_security import (
24
+ AgentAnomalyDetector,
25
+ AgentAnomalySignal,
26
+ AgentBaselineEngine,
27
+ AgentCredentialManager,
28
+ AgentScopeEnforcer,
29
+ )
30
+ try:
31
+ # AbuseIPDB trade-secret integration is proprietary and stripped from
32
+ # the open-core checkout (2026-11-08 standalone-build audit, round 2).
33
+ # Not imported by any other module in this package (confirmed by
34
+ # grepping before adding this guard), so a plain ImportError guard is
35
+ # enough — these names simply aren't bound on that checkout, same
36
+ # pattern as the Node/Ruby SDKs' boundary for this module. Never
37
+ # triggers in the private repo, where abuseipdb.py always exists.
38
+ from .abuseipdb import (
39
+ AbuseIPDBCheckResult,
40
+ AbuseIPDBError,
41
+ CompositeScoreResult,
42
+ check_ip,
43
+ get_abuseipdb_rate_limit_status,
44
+ get_cached_score,
45
+ report_ip,
46
+ score_threat,
47
+ sync_blacklist,
48
+ )
49
+ except ImportError:
50
+ pass
51
+ from .client import DevFortressClient, DevFortressError
52
+ from .clock_drift_detector import (
53
+ ClockDriftAction,
54
+ ClockDriftDetector,
55
+ ClockDriftResult,
56
+ ClockDriftSeverity,
57
+ ClockDriftTrend,
58
+ )
59
+ from .closed_loop import ClosedLoopEngine, ThreatEvent
60
+ from .circuit_breaker import CircuitBreakerDiagnostics, PlatformCircuitBreaker
61
+ try:
62
+ # Cold-start behavioral baseline detector (Invention A1) is proprietary
63
+ # and stripped from the open-core checkout — same reasoning/guard as
64
+ # the abuseipdb import above.
65
+ from .cold_start_detector import (
66
+ BaselineQuality,
67
+ BehavioralFeatureVector,
68
+ ColdStartDetectionResult,
69
+ ColdStartDetector,
70
+ )
71
+ except ImportError:
72
+ pass
73
+ from .config_integrity_verifier import (
74
+ ConfigIntegrityResult,
75
+ ConfigIntegrityVerifier,
76
+ ConfigViolation,
77
+ )
78
+ from .credential_isolation import CredentialIsolationManager, ThreatInterceptor
79
+ from .fastapi_middleware import DevFortressMiddleware
80
+ from .flask_middleware import DevFortressFlask
81
+ from .graduated_rate_limiter import GraduatedRateLimiter, RateLimitResult
82
+ from .internal_closed_loop_engine import (
83
+ InternalCLAction,
84
+ InternalCLAuditEntry,
85
+ InternalCLConfig,
86
+ InternalCLRequest,
87
+ InternalCLResult,
88
+ InternalCLRule,
89
+ InternalClosedLoopEngine,
90
+ matches_known_attack_pattern,
91
+ )
92
+ from .license_manager import LicenseManager, LicenseState, ModelState
93
+ try:
94
+ # LSH fingerprint clustering / campaign detection (Invention A2) is
95
+ # proprietary and stripped from the open-core checkout — same
96
+ # reasoning/guard as the abuseipdb import above.
97
+ from .lsh_cluster_engine import (
98
+ CampaignSignature,
99
+ ClusterInfo,
100
+ LSHClusterEngine,
101
+ LSHMatchResult,
102
+ RequestFingerprint,
103
+ )
104
+ except ImportError:
105
+ pass
106
+ from .quick import get_instance, init
107
+ from .sensitive_action_monitor import (
108
+ SensitiveActionEvent,
109
+ SensitiveActionMonitor,
110
+ SensitiveActionResult,
111
+ )
112
+ from .session_fixation_guard import (
113
+ SessionFingerprint,
114
+ SessionFixationGuard,
115
+ SessionValidationResult,
116
+ )
117
+ from .shadow_agent_registry import (
118
+ AgentRegistryStats,
119
+ RegisteredAgent,
120
+ ShadowAgentDetection,
121
+ ShadowAgentRegistry,
122
+ )
123
+ from .signing import derive_key_id, sign_request, verify_request_signature
124
+ from .telemetry import (
125
+ RollupContributionInput,
126
+ TelemetryManager,
127
+ TelemetryRollupBuffer,
128
+ TelemetrySnapshot,
129
+ hourly_period_key,
130
+ )
131
+ from .tier_gate import SubscriptionTier, TierCapabilities, TierGate, TierGateSnapshot
132
+ from .tool_call_sequence_validator import ToolCallSequenceValidator, ToolCallValidationResult
133
+ from .unified_audit_trail import UnifiedAuditEntry, UnifiedAuditTrail
134
+ from .webhook import WebhookVerification, verify_webhook_signature
135
+
136
+ __version__ = "0.3.0"
137
+
138
+ __all__ = [
139
+ "DevFortressClient",
140
+ "DevFortressError",
141
+ "DevFortressMiddleware",
142
+ "DevFortressFlask",
143
+ "WebhookVerification",
144
+ "verify_webhook_signature",
145
+ "derive_key_id",
146
+ "sign_request",
147
+ "verify_request_signature",
148
+ "init",
149
+ "get_instance",
150
+ # Credential aliasing
151
+ "CredentialIsolationManager",
152
+ "ThreatInterceptor",
153
+ "AgentCredentialManager",
154
+ # Behavioral fingerprinting
155
+ "AgentAdapter",
156
+ "AgentToolCall",
157
+ "ObserveResult",
158
+ "validate_agent_id",
159
+ "AgentBaselineEngine",
160
+ "AgentAnomalyDetector",
161
+ "AgentAnomalySignal",
162
+ "AgentScopeEnforcer",
163
+ "ToolCallSequenceValidator",
164
+ "ToolCallValidationResult",
165
+ "AgentLoopDetector",
166
+ "LoopDetectionResult",
167
+ # Closed-loop response
168
+ "ClosedLoopEngine",
169
+ "ThreatEvent",
170
+ # Internal/hybrid closed-loop mode (TODO 407 port)
171
+ "InternalClosedLoopEngine",
172
+ "InternalCLConfig",
173
+ "InternalCLRequest",
174
+ "InternalCLResult",
175
+ "InternalCLAction",
176
+ "InternalCLAuditEntry",
177
+ "InternalCLRule",
178
+ "matches_known_attack_pattern",
179
+ # License / tier state (CV-M1, CV-M4, CV-M7)
180
+ "LicenseManager",
181
+ "LicenseState",
182
+ "ModelState",
183
+ # Telemetry heartbeat (CV-M2) + non-billing aggregate rollup buffer
184
+ "TelemetryManager",
185
+ "TelemetrySnapshot",
186
+ "TelemetryRollupBuffer",
187
+ "RollupContributionInput",
188
+ "hourly_period_key",
189
+ # Tier gating / feature access control
190
+ "TierGate",
191
+ "SubscriptionTier",
192
+ "TierCapabilities",
193
+ "TierGateSnapshot",
194
+ # B7: Agent output exfiltration detection (moved from tier2_gated, TODO 380)
195
+ "AgentOutputExfiltrationDetector",
196
+ "AgentOutput",
197
+ "ExfiltrationResult",
198
+ # B10: Shadow agent registry (moved from tier2_gated, TODO 380)
199
+ "ShadowAgentRegistry",
200
+ "RegisteredAgent",
201
+ "ShadowAgentDetection",
202
+ "AgentRegistryStats",
203
+ # Invention A3: graduated rate limiting (TODO 373)
204
+ "GraduatedRateLimiter",
205
+ "RateLimitResult",
206
+ # Platform circuit breaker (TODO 372)
207
+ "PlatformCircuitBreaker",
208
+ "CircuitBreakerDiagnostics",
209
+ # Invention A18: clock drift anomaly detection (TODO 419)
210
+ "ClockDriftDetector",
211
+ "ClockDriftResult",
212
+ "ClockDriftTrend",
213
+ "ClockDriftSeverity",
214
+ "ClockDriftAction",
215
+ # Invention A9: config integrity verification (TODO 419/426)
216
+ "ConfigIntegrityVerifier",
217
+ "ConfigIntegrityResult",
218
+ "ConfigViolation",
219
+ # Invention A13: session fixation guard (TODO 419/429)
220
+ "SessionFixationGuard",
221
+ "SessionFingerprint",
222
+ "SessionValidationResult",
223
+ # Invention A6: sensitive action monitor (TODO 419/424)
224
+ "SensitiveActionMonitor",
225
+ "SensitiveActionEvent",
226
+ "SensitiveActionResult",
227
+ # Invention A1: cold-start behavioral baselines (TODO 374)
228
+ "ColdStartDetector",
229
+ "BehavioralFeatureVector",
230
+ "BaselineQuality",
231
+ "ColdStartDetectionResult",
232
+ # Invention A2: LSH fingerprint clustering / campaign detection (TODO 374)
233
+ "LSHClusterEngine",
234
+ "RequestFingerprint",
235
+ "CampaignSignature",
236
+ "LSHMatchResult",
237
+ "ClusterInfo",
238
+ # Unified audit trail (CL-M3, TODO 371) — in-memory only, not
239
+ # tamper-evident; see unified_audit_trail.py's module docstring.
240
+ "UnifiedAuditTrail",
241
+ "UnifiedAuditEntry",
242
+ # AbuseIPDB threat-intel enrichment (TODO 375)
243
+ "check_ip",
244
+ "report_ip",
245
+ "sync_blacklist",
246
+ "score_threat",
247
+ "get_cached_score",
248
+ "get_abuseipdb_rate_limit_status",
249
+ "AbuseIPDBCheckResult",
250
+ "CompositeScoreResult",
251
+ "AbuseIPDBError",
252
+ ]
devfortress/agent.py ADDED
@@ -0,0 +1,324 @@
1
+ """DevFortress Agent Security Adapter.
2
+
3
+ Port of the Node SDK's ``agent.ts``. Wraps the event client for AI agent
4
+ tool invocations. Intercepts agent_id, tool_name, and input_summary from
5
+ LangChain/LangGraph, OpenAI function calling, and raw HTTP-based agent tool
6
+ invocations.
7
+
8
+ Scoping note (Python port): Node's ``AgentAdapter.observeToolCall()``
9
+ delegates to ``DevFortress.observe()``, whose ``flagged``/``confidence``
10
+ fields are computed by a large, separate client-side ML/tier-gate pipeline
11
+ (``ml-classifier.ts``, ``tier-gate.ts``, license/quota machinery) — that
12
+ pipeline is shared infrastructure used by every event type, not part of
13
+ this package's agent-security pillars (credential aliasing, behavioral
14
+ fingerprinting, closed-loop response), and is out of scope here. Python's
15
+ ``observe_tool_call()`` reports the event through the existing signed
16
+ ingest path (``DevFortressClient.track_event``) and returns the real
17
+ ``event_id`` the platform assigns; ``flagged``/``confidence`` are always
18
+ ``False``/``0.0`` — they do not fabricate a classification Python has no
19
+ engine to produce. A caller that wants a tool call blocked locally should
20
+ rely on the other pillars (``ToolCallSequenceValidator``, ``AgentAnomalyDetector``,
21
+ ``AgentScopeEnforcer``, ``AgentLoopDetector``), exactly as the reference
22
+ demo's gate chain does before it ever calls ``observe_tool_call()``.
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ import json
28
+ import re
29
+ from dataclasses import dataclass
30
+ from typing import Any, Dict, Optional
31
+
32
+ from .client import DevFortressClient
33
+
34
+ AGENT_ID_MAX_LENGTH = 128
35
+ _AGENT_ID_PATTERN = re.compile(r"^[a-zA-Z0-9_\-.:@]+$")
36
+
37
+ _MAX_TRACKED_SESSIONS = 10_000
38
+
39
+
40
+ def validate_agent_id(agent_id: str) -> None:
41
+ """Validate agent ID to prevent injection and ensure safe usage as
42
+ cache keys and pseudo-URL path segments."""
43
+ if not agent_id or not isinstance(agent_id, str):
44
+ raise ValueError("agent_id is required and must be a non-empty string")
45
+ if len(agent_id) > AGENT_ID_MAX_LENGTH:
46
+ raise ValueError(f"agent_id must be at most {AGENT_ID_MAX_LENGTH} characters")
47
+ if not _AGENT_ID_PATTERN.match(agent_id):
48
+ raise ValueError(
49
+ "agent_id may only contain alphanumeric characters, hyphens, underscores, "
50
+ "dots, colons, and @"
51
+ )
52
+
53
+
54
+ @dataclass
55
+ class ObserveResult:
56
+ flagged: bool
57
+ event_id: str
58
+ confidence: float
59
+
60
+
61
+ @dataclass
62
+ class AgentToolCall:
63
+ tool: str
64
+ input: Optional[Dict[str, Any]] = None
65
+ output: Any = None
66
+ duration_ms: Optional[float] = None
67
+ model: Optional[str] = None
68
+ framework: str = "custom"
69
+ meta: Optional[Dict[str, Any]] = None
70
+
71
+
72
+ def _safe_track_event(client: DevFortressClient, event: Dict[str, Any]) -> "ObserveResult":
73
+ """Matches Node's observe()'s outer try/catch exactly: a delivery failure
74
+ (network error, 5xx after retries, etc.) is logged and never propagates
75
+ to the caller — observation must never break the agent. Returns a
76
+ non-flagged result on failure, same as Node returning null (callers here
77
+ treat an unflagged result identically to None for gating purposes)."""
78
+ try:
79
+ response = client.track_event(event)
80
+ event_id = response.get("event_id") or response.get("eventId") or ""
81
+ return ObserveResult(flagged=False, event_id=event_id, confidence=0.0)
82
+ except Exception as error:
83
+ print(f"[DevFortress] observe() failed: {error}") # noqa: T201
84
+ return ObserveResult(flagged=False, event_id="", confidence=0.0)
85
+
86
+
87
+ def _summarize_input(
88
+ input_data: Optional[Dict[str, Any]], max_len: int, sanitize: bool
89
+ ) -> str:
90
+ if not input_data:
91
+ return "{}"
92
+ summary: Dict[str, str] = {}
93
+ for key, val in input_data.items():
94
+ if val is None:
95
+ summary[key] = "null"
96
+ elif isinstance(val, str):
97
+ lowered = key.lower()
98
+ if sanitize and any(s in lowered for s in ("key", "token", "secret", "password")):
99
+ summary[key] = "[REDACTED]"
100
+ else:
101
+ summary[key] = val if len(val) <= 64 else val[:61] + "..."
102
+ elif isinstance(val, bool):
103
+ summary[key] = "true" if val else "false"
104
+ elif isinstance(val, (int, float)):
105
+ summary[key] = str(val)
106
+ elif isinstance(val, list):
107
+ summary[key] = f"Array({len(val)})"
108
+ else:
109
+ summary[key] = "{...}"
110
+
111
+ text = json.dumps(summary)
112
+ return text if len(text) <= max_len else text[: max_len - 3] + "..."
113
+
114
+
115
+ class AgentAdapter:
116
+ def __init__(
117
+ self,
118
+ client: DevFortressClient,
119
+ agent_id: str,
120
+ *,
121
+ agent_name: Optional[str] = None,
122
+ agent_ip: str = "127.0.0.1",
123
+ max_input_summary_length: int = 256,
124
+ sanitize_inputs: bool = True,
125
+ on_flagged: Optional[Any] = None,
126
+ ):
127
+ validate_agent_id(agent_id)
128
+ self._client = client
129
+ self._agent_id = agent_id
130
+ self._agent_name = agent_name or agent_id
131
+ self._agent_ip = agent_ip
132
+ self._max_input_summary_length = max_input_summary_length
133
+ self._sanitize_inputs = sanitize_inputs
134
+ self._on_flagged = on_flagged
135
+ self._session_tool_counts: "Dict[str, int]" = {}
136
+
137
+ async def observe_tool_call(
138
+ self, tool_call: AgentToolCall, session_id: Optional[str] = None
139
+ ) -> Optional[ObserveResult]:
140
+ """Observe an AI agent tool invocation through DevFortress.
141
+
142
+ Extracts agent_id, tool_name, input_summary and sends as a
143
+ structured event. The real tool inputs stay local — only the
144
+ summary is transmitted. See module docstring for the
145
+ flagged/confidence scoping note.
146
+ """
147
+ input_summary = _summarize_input(
148
+ tool_call.input, self._max_input_summary_length, self._sanitize_inputs
149
+ )
150
+
151
+ sid = session_id or "default"
152
+ count = self._session_tool_counts.get(sid, 0) + 1
153
+ self._session_tool_counts[sid] = count
154
+
155
+ event = {
156
+ "eventType": "custom",
157
+ "ip": self._agent_ip,
158
+ "method": "TOOL_CALL",
159
+ "path": f"/agent/{self._agent_id}/tool/{tool_call.tool}",
160
+ "userAgent": f"DevFortress-Agent/{self._agent_name}",
161
+ "severity": "LOW",
162
+ "clMode": "external",
163
+ "authPhase": "post_auth",
164
+ "actionTaken": "monitored",
165
+ "responseLatencyMs": tool_call.duration_ms or 0,
166
+ "isAgent": True,
167
+ "agentId": self._agent_id,
168
+ "metadata": {
169
+ "agent_id": self._agent_id,
170
+ "agent_name": self._agent_name,
171
+ "tool_name": tool_call.tool,
172
+ "input_summary": input_summary,
173
+ "duration_ms": tool_call.duration_ms,
174
+ "model": tool_call.model,
175
+ "framework": tool_call.framework,
176
+ "session_tool_count": count,
177
+ "session_id": session_id,
178
+ "event_category": "agent_tool_call",
179
+ **(tool_call.meta or {}),
180
+ },
181
+ }
182
+
183
+ result = _safe_track_event(self._client, event)
184
+
185
+ if result.flagged and self._on_flagged:
186
+ maybe_awaitable = self._on_flagged(tool_call, result)
187
+ if maybe_awaitable is not None:
188
+ await maybe_awaitable
189
+
190
+ return result
191
+
192
+ async def observe_langchain_tool(
193
+ self,
194
+ tool_name: str,
195
+ tool_input: Dict[str, Any],
196
+ *,
197
+ session_id: Optional[str] = None,
198
+ model: Optional[str] = None,
199
+ duration_ms: Optional[float] = None,
200
+ ) -> Optional[ObserveResult]:
201
+ return await self.observe_tool_call(
202
+ AgentToolCall(
203
+ tool=tool_name,
204
+ input=tool_input,
205
+ framework="langchain",
206
+ model=model,
207
+ duration_ms=duration_ms,
208
+ ),
209
+ session_id,
210
+ )
211
+
212
+ async def observe_openai_tool_call(
213
+ self,
214
+ function_name: str,
215
+ arguments_json: str,
216
+ *,
217
+ session_id: Optional[str] = None,
218
+ model: Optional[str] = None,
219
+ duration_ms: Optional[float] = None,
220
+ ) -> Optional[ObserveResult]:
221
+ try:
222
+ parsed_args = json.loads(arguments_json)
223
+ except Exception:
224
+ parsed_args = {"raw": arguments_json}
225
+
226
+ return await self.observe_tool_call(
227
+ AgentToolCall(
228
+ tool=function_name,
229
+ input=parsed_args,
230
+ framework="openai",
231
+ model=model,
232
+ duration_ms=duration_ms,
233
+ ),
234
+ session_id,
235
+ )
236
+
237
+ async def observe_http_tool_call(
238
+ self,
239
+ url: str,
240
+ method: str,
241
+ *,
242
+ status_code: Optional[int] = None,
243
+ duration_ms: Optional[float] = None,
244
+ session_id: Optional[str] = None,
245
+ meta: Optional[Dict[str, Any]] = None,
246
+ ) -> Optional[ObserveResult]:
247
+ return await self.observe_tool_call(
248
+ AgentToolCall(
249
+ tool=f"http:{method.upper()}",
250
+ input={"url": url, "status_code": status_code},
251
+ framework="raw_http",
252
+ duration_ms=duration_ms,
253
+ meta=meta,
254
+ ),
255
+ session_id,
256
+ )
257
+
258
+ async def track_session_start(
259
+ self, session_id: str, task_description: Optional[str] = None
260
+ ) -> Optional[ObserveResult]:
261
+ if len(self._session_tool_counts) >= _MAX_TRACKED_SESSIONS:
262
+ first = next(iter(self._session_tool_counts), None)
263
+ if first is not None:
264
+ del self._session_tool_counts[first]
265
+ self._session_tool_counts[session_id] = 0
266
+
267
+ event = {
268
+ "eventType": "custom",
269
+ "ip": self._agent_ip,
270
+ "method": "SESSION_START",
271
+ "path": f"/agent/{self._agent_id}/session/{session_id}",
272
+ "userAgent": f"DevFortress-Agent/{self._agent_name}",
273
+ "severity": "LOW",
274
+ "clMode": "external",
275
+ "authPhase": "post_auth",
276
+ "actionTaken": "monitored",
277
+ "responseLatencyMs": 0,
278
+ "isAgent": True,
279
+ "agentId": self._agent_id,
280
+ "metadata": {
281
+ "agent_id": self._agent_id,
282
+ "session_id": session_id,
283
+ "task_description": task_description,
284
+ "event_category": "agent_session_start",
285
+ },
286
+ }
287
+ return _safe_track_event(self._client, event)
288
+
289
+ async def track_session_end(
290
+ self,
291
+ session_id: str,
292
+ *,
293
+ total_tools: Optional[int] = None,
294
+ duration_ms: Optional[float] = None,
295
+ success: Optional[bool] = None,
296
+ ) -> Optional[ObserveResult]:
297
+ tool_count = self._session_tool_counts.pop(session_id, 0)
298
+
299
+ event = {
300
+ "eventType": "custom",
301
+ "ip": self._agent_ip,
302
+ "method": "SESSION_END",
303
+ "path": f"/agent/{self._agent_id}/session/{session_id}",
304
+ "userAgent": f"DevFortress-Agent/{self._agent_name}",
305
+ "severity": "LOW",
306
+ "clMode": "external",
307
+ "authPhase": "post_auth",
308
+ "actionTaken": "monitored",
309
+ "responseLatencyMs": 0,
310
+ "isAgent": True,
311
+ "agentId": self._agent_id,
312
+ "metadata": {
313
+ "agent_id": self._agent_id,
314
+ "session_id": session_id,
315
+ "total_tools": total_tools if total_tools is not None else tool_count,
316
+ "total_duration_ms": duration_ms,
317
+ "success": success,
318
+ "event_category": "agent_session_end",
319
+ },
320
+ }
321
+ return _safe_track_event(self._client, event)
322
+
323
+ def get_session_tool_count(self, session_id: str) -> int:
324
+ return self._session_tool_counts.get(session_id, 0)