failproofai 1.0.1 → 1.0.2-beta.0

package/.next/standalone/sdk/python/failproofai_sdk/_resolver.py

@@ -0,0 +1,118 @@
+import os
+from pathlib import Path
+
+_base_dir: Path | None = None
+
+
+def get_base_dir() -> Path:
+    """Where this SDK writes its event spool.
+
+    Resolution order, most explicit first:
+
+      1. ``set_base_dir()``               — a caller said so outright
+      2. ``~/.failproofai/custom-agents`` — always
+
+    There is no environment variable that redirects the spool off the umbrella,
+    and that is the point. ``FAILPROOFAI_HOME`` (honoured by
+    ``failproofai_custom_agents_dir()`` below) MOVES the umbrella; it cannot
+    take you outside it, because the ``custom-agents`` segment is appended
+    unconditionally. Wherever the home is, the spool is inside it.
+
+    ## Why ``$AGENTEYE_HOME`` no longer resolves here
+
+    It used to sit at step 2 and win over the default, which made it possible to
+    aim this SDK at ``~/.agenteye`` — or anywhere else — from the environment.
+    That is a redirect with no confirmation and no error: batches land in a
+    directory, something may or may not read it, and an unread spool is
+    indistinguishable from an idle one. A variable named for a product this
+    package no longer belongs to is a poor thing to have that power, and an
+    operator who exports it for the OTHER component that reads it (the older
+    ``agenteye-collector``, which resolves ``$AGENTEYE_HOME`` or ``~/.agenteye``
+    and nothing else) moved this SDK's spool as a side effect they never asked
+    for.
+
+    So it is gone from resolution. The variable itself still exists and still
+    means something — just not here.
+
+    ## Nothing is stranded by this
+
+    ``failproofaid``, the daemon this SDK ships beside, watches BOTH
+    ``~/.failproofai/custom-agents/events`` AND ``~/.agenteye/events``, and
+    keeps doing so (``crates/fpai-collect/src/config.rs``, ``spool_dirs``). An
+    SDK old enough to write only the legacy root is still collected. Batches
+    already sitting there still drain. What changed is only that THIS version
+    has no way to be pointed at that root by accident — it writes to the
+    umbrella, and the daemon reads both.
+
+    ## The one case that needs a deliberate choice
+
+    A host running the older ``agenteye-collector`` and nothing else. That
+    collector never learned the umbrella, so it does not watch where this SDK
+    now writes. Setting ``AGENTEYE_HOME`` no longer bridges that gap from this
+    side; the supported bridges are, in order of preference:
+
+      * run ``failproofaid`` instead — it watches both roots, so nothing is
+        configured at all; or
+      * point the collector AT the SDK by setting its own
+        ``AGENTEYE_HOME=~/.failproofai/custom-agents``, which makes it watch
+        ``~/.failproofai/custom-agents/events``; or
+      * ``set_base_dir("~/.agenteye")`` in the application, which is explicit,
+        visible at the call site, and cannot happen by inheriting somebody
+        else's environment.
+
+    ``test_spool_contract.py`` reads the Rust and the TypeScript that define
+    these roots and fails if either drifts from what this module resolves.
+    """
+    if _base_dir is not None:
+        return _base_dir
+
+    return failproofai_custom_agents_dir()
+
+
+def failproofai_custom_agents_dir() -> Path:
+    """``~/.failproofai/custom-agents``, honouring ``$FAILPROOFAI_HOME``.
+
+    Mirrors ``customAgentsDir()`` in ``src/hooks/fp-home.ts`` and
+    ``custom_agents_events_dir()`` in ``crates/fpai-collect/src/config.rs``. The
+    three must agree; a divergence would mean this SDK writes somewhere the
+    daemon never reads.
+
+    All three live in THIS repository, so the agreement is checkable rather than
+    hoped for — ``tests/test_spool_contract.py`` reads the Rust and the
+    TypeScript and fails if either drifts.
+
+    Returns a path unconditionally and never checks whether it exists. The
+    caller creates it: ``_writer._write_batch`` already does
+    ``mkdir(parents=True, exist_ok=True)`` on the directory it is about to write
+    into. An existence check here is what made the old opt-in dead — a spool
+    root that must pre-exist can never be the place a first batch is written.
+    """
+    fp_home = os.environ.get("FAILPROOFAI_HOME")
+    base = Path(fp_home) if fp_home else Path.home() / ".failproofai"
+    return base / "custom-agents"
+
+
+def legacy_agenteye_dir() -> Path:
+    """``~/.agenteye`` — the root this SDK wrote to before the default moved.
+
+    Not part of resolution any more, and no environment variable can put it
+    back — see ``get_base_dir``. Kept as a named constant because the migration
+    notes and the tests still refer to it, and because ``failproofaid`` goes on
+    watching ``~/.agenteye/events`` for SDKs old enough to write there. Spelling
+    it in four places is how the two sides drift apart.
+    """
+    return Path.home() / ".agenteye"
+
+
+def set_base_dir(path: "str | Path | None") -> None:
+    global _base_dir
+    # `expanduser`, because the migration bridge this module itself prescribes —
+    # `configure(base_dir="~/.agenteye")`, listed in `get_base_dir`'s docstring
+    # and in README.md as the explicit, visible-at-the-call-site option — is a
+    # RELATIVE path whose first segment is the literal character `~`. Without
+    # this, `_write_batch`'s `mkdir(parents=True)` cheerfully created a `~`
+    # directory under the process's cwd and spooled into it: nothing on the
+    # machine watches that path, so 100% of the telemetry was lost, which is the
+    # precise "an unread spool is indistinguishable from an idle one" failure
+    # the prose above it is written to prevent.
+    _base_dir = Path(path).expanduser() if path is not None else None

package/.next/standalone/sdk/python/failproofai_sdk/_runtime.py

@@ -0,0 +1,21 @@
+"""The process-wide writer and event namespace.
+
+These used to be constructed in `failproofai_sdk/__init__.py`. They live in a
+leaf module now so that `_scopes` and the framework adapters can reach the
+namespace without importing the `failproofai_sdk` package itself, which would be
+a circular import.
+
+Constructing `EventWriter` starts a daemon thread and registers the module-level
+atexit flush, and that still happens at `import failproofai_sdk` time —
+`__init__.py` imports this module, so the timing is unchanged.
+
+Reach the namespace as `_runtime.event`, an attribute lookup at call time rather
+than a `from ... import event` binding, so a test can swap in a recording
+namespace and the scopes pick it up.
+"""
+
+from failproofai_sdk._events import EventNamespace
+from failproofai_sdk._writer import EventWriter
+
+writer = EventWriter()
+event = EventNamespace(writer)

package/.next/standalone/sdk/python/failproofai_sdk/_schema.py

@@ -0,0 +1,317 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+from failproofai_sdk._environment import get_environment
+
+
+def _build(base: dict, specifics: list[tuple[str, Any]], extra: dict) -> dict:
+    """Build ordered event dict, omitting None values, then merge extra fields."""
+    result = {**base}
+    result["environment"] = get_environment()
+    for k, v in specifics:
+        if v is not None:
+            result[k] = v
+    result.update(extra)
+    return result
+
+
+@dataclass(kw_only=True)
+class ToolUseEvent:
+    timestamp: str
+    session_id: str
+    agent_id: str
+    tool_name: str
+    tool_call_id: str
+    input: dict | None = None
+    extra_fields: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return _build(
+            {"timestamp": self.timestamp, "session_id": self.session_id, "agent_id": self.agent_id, "type": "tool_use",
+             "tool_name": self.tool_name, "tool_call_id": self.tool_call_id},
+            [("input", self.input)],
+            self.extra_fields,
+        )
+
+
+@dataclass(kw_only=True)
+class ToolResultEvent:
+    timestamp: str
+    session_id: str
+    agent_id: str
+    tool_name: str
+    tool_call_id: str
+    output: Any | None = None
+    error: str | None = None
+    duration_ms: float | None = None
+    extra_fields: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return _build(
+            {"timestamp": self.timestamp, "session_id": self.session_id, "agent_id": self.agent_id, "type": "tool_result",
+             "tool_name": self.tool_name, "tool_call_id": self.tool_call_id},
+            [("output", self.output), ("error", self.error), ("duration_ms", self.duration_ms)],
+            self.extra_fields,
+        )
+
+
+@dataclass(kw_only=True)
+class ModelRequestEvent:
+    timestamp: str
+    session_id: str
+    agent_id: str
+    model: str | None = None
+    messages: list[dict] | None = None
+    system: Any | None = None
+    tools: list[dict] | None = None
+    #: Pairs this request with its response. Appended LAST in `_build`'s ordered
+    #: list so an event that omits it serialises byte-for-byte as before —
+    #: `test_wire_format.py` freezes those bytes, and the dedup key hashes them.
+    request_id: str | None = None
+    extra_fields: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return _build(
+            {"timestamp": self.timestamp, "session_id": self.session_id, "agent_id": self.agent_id, "type": "model_request"},
+            [("model", self.model), ("messages", self.messages),
+             ("system", self.system), ("tools", self.tools),
+             ("request_id", self.request_id)],
+            self.extra_fields,
+        )
+
+
+@dataclass(kw_only=True)
+class ModelResponseEvent:
+    timestamp: str
+    session_id: str
+    agent_id: str
+    model: str | None = None
+    stop_reason: str | None = None
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    content: Any | None = None
+    role: str | None = None
+    #: The `request_id` of the `model_request` this answers. See above.
+    request_id: str | None = None
+    extra_fields: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return _build(
+            {"timestamp": self.timestamp, "session_id": self.session_id, "agent_id": self.agent_id, "type": "model_response"},
+            [("model", self.model), ("stop_reason", self.stop_reason),
+             ("input_tokens", self.input_tokens), ("output_tokens", self.output_tokens),
+             ("content", self.content), ("role", self.role),
+             ("request_id", self.request_id)],
+            self.extra_fields,
+        )
+
+
+@dataclass(kw_only=True)
+class AgentStartEvent:
+    timestamp: str
+    session_id: str
+    agent_id: str
+    goal: str | None = None
+    parent_id: str | None = None
+    extra_fields: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return _build(
+            {"timestamp": self.timestamp, "session_id": self.session_id, "agent_id": self.agent_id, "type": "agent_start"},
+            [("goal", self.goal), ("parent_id", self.parent_id)],
+            self.extra_fields,
+        )
+
+
+@dataclass(kw_only=True)
+class AgentEndEvent:
+    timestamp: str
+    session_id: str
+    agent_id: str
+    outcome: str | None = None
+    summary: str | None = None
+    extra_fields: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return _build(
+            {"timestamp": self.timestamp, "session_id": self.session_id, "agent_id": self.agent_id, "type": "agent_end"},
+            [("outcome", self.outcome), ("summary", self.summary)],
+            self.extra_fields,
+        )
+
+
+@dataclass(kw_only=True)
+class AgentPauseEvent:
+    timestamp: str
+    session_id: str
+    agent_id: str
+    pause_id: str
+    reason: str | None = None
+    user_id: str | None = None
+    extra_fields: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return _build(
+            {"timestamp": self.timestamp, "session_id": self.session_id, "agent_id": self.agent_id,
+             "type": "agent_pause", "pause_id": self.pause_id},
+            [("reason", self.reason), ("user_id", self.user_id)],
+            self.extra_fields,
+        )
+
+
+@dataclass(kw_only=True)
+class AgentResumeEvent:
+    timestamp: str
+    session_id: str
+    agent_id: str
+    pause_id: str
+    duration_ms: float | None = None
+    reason: str | None = None
+    user_id: str | None = None
+    extra_fields: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return _build(
+            {"timestamp": self.timestamp, "session_id": self.session_id, "agent_id": self.agent_id,
+             "type": "agent_resume", "pause_id": self.pause_id},
+            [("duration_ms", self.duration_ms), ("reason", self.reason), ("user_id", self.user_id)],
+            self.extra_fields,
+        )
+
+
+@dataclass(kw_only=True)
+class HookTriggeredEvent:
+    timestamp: str
+    session_id: str
+    agent_id: str
+    hook_name: str
+    hook_id: str
+    trigger_event: str | None = None
+    input: Any | None = None
+    extra_fields: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return _build(
+            {"timestamp": self.timestamp, "session_id": self.session_id, "agent_id": self.agent_id, "type": "hook_triggered",
+             "hook_name": self.hook_name, "hook_id": self.hook_id},
+            [("trigger_event", self.trigger_event), ("input", self.input)],
+            self.extra_fields,
+        )
+
+
+@dataclass(kw_only=True)
+class HookCompletedEvent:
+    timestamp: str
+    session_id: str
+    agent_id: str
+    hook_name: str
+    hook_id: str
+    outcome: str | None = None
+    output: Any | None = None
+    error: str | None = None
+    duration_ms: float | None = None
+    extra_fields: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return _build(
+            {"timestamp": self.timestamp, "session_id": self.session_id, "agent_id": self.agent_id, "type": "hook_completed",
+             "hook_name": self.hook_name, "hook_id": self.hook_id},
+            [("outcome", self.outcome), ("output", self.output),
+             ("error", self.error), ("duration_ms", self.duration_ms)],
+            self.extra_fields,
+        )
+
+
+@dataclass(kw_only=True)
+class ErrorEvent:
+    timestamp: str
+    session_id: str
+    agent_id: str
+    error_type: str
+    message: str
+    traceback: str | None = None
+    extra_fields: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return _build(
+            {"timestamp": self.timestamp, "session_id": self.session_id, "agent_id": self.agent_id, "type": "error",
+             "error_type": self.error_type, "message": self.message},
+            [("traceback", self.traceback)],
+            self.extra_fields,
+        )
+
+
+@dataclass(kw_only=True)
+class HumanWaitEvent:
+    timestamp: str
+    session_id: str
+    agent_id: str
+    input_id: str
+    prompt: str | None = None
+    options: list[str] | None = None
+    reason: str | None = None
+    extra_fields: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return _build(
+            {"timestamp": self.timestamp, "session_id": self.session_id, "agent_id": self.agent_id,
+             "type": "human_wait", "input_id": self.input_id},
+            [("prompt", self.prompt), ("options", self.options), ("reason", self.reason)],
+            self.extra_fields,
+        )
+
+
+@dataclass(kw_only=True)
+class HumanInputEvent:
+    timestamp: str
+    session_id: str
+    agent_id: str
+    input_id: str
+    response: str | None = None
+    duration_ms: float | None = None
+    extra_fields: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return _build(
+            {"timestamp": self.timestamp, "session_id": self.session_id, "agent_id": self.agent_id,
+             "type": "human_input", "input_id": self.input_id},
+            [("response", self.response), ("duration_ms", self.duration_ms)],
+            self.extra_fields,
+        )
+
+
+@dataclass(kw_only=True)
+class HumanPauseEvent:
+    timestamp: str
+    session_id: str
+    agent_id: str
+    reason: str | None = None
+    user_id: str | None = None
+    extra_fields: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return _build(
+            {"timestamp": self.timestamp, "session_id": self.session_id, "agent_id": self.agent_id,
+             "type": "human_pause"},
+            [("reason", self.reason), ("user_id", self.user_id)],
+            self.extra_fields,
+        )
+
+
+@dataclass(kw_only=True)
+class HumanInterruptEvent:
+    timestamp: str
+    session_id: str
+    agent_id: str
+    reason: str | None = None
+    user_id: str | None = None
+    at_step: str | None = None
+    extra_fields: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return _build(
+            {"timestamp": self.timestamp, "session_id": self.session_id, "agent_id": self.agent_id,
+             "type": "human_interrupt"},
+            [("reason", self.reason), ("user_id", self.user_id), ("at_step", self.at_step)],
+            self.extra_fields,
+        )