agent-trajectory 0.2.3__py3-none-any.whl

trajectory/_client.py

@@ -0,0 +1,236 @@
+"""Subprocess transport for the bundled trajectory runtime."""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+import sys
+from collections.abc import Iterable, Mapping
+from functools import lru_cache
+from pathlib import Path
+from typing import cast
+
+from ._errors import NodeUnavailableError, NormalizationError, TrajectoryRuntimeError
+from ._types import (
+    AnyTrajectorySource,
+    ListTrajectoriesResult,
+    NormalizationBounds,
+    NormalizationFilters,
+    NormalizationErrorCode,
+    NormalizeInput,
+    NormalizeRequest,
+    NormalizeResult,
+    SourceContext,
+    TrajectorySource,
+)
+
+_PROTOCOL_VERSION = 1
+_MINIMUM_NODE_MAJOR = 20
+_CLI_PATH = Path(__file__).parent / "_vendor" / "trajectory-cli.mjs"
+
+
+def normalize_transcript(
+    *,
+    source: TrajectorySource,
+    transcript: str,
+    bounds: NormalizationBounds | None = None,
+    filters: NormalizationFilters | None = None,
+    source_context: SourceContext | None = None,
+) -> NormalizeResult:
+    """Normalize one native transcript or an explicitly partial fragment.
+
+    ``source_context`` mirrors the TypeScript ``sourceContext`` input. Set
+    ``{"partial": True}`` for an offset-zero fragment; a non-zero
+    ``baseByteOffset`` also implies partial mode.
+    """
+
+    request: NormalizeInput = {"source": source, "transcript": transcript}
+    if bounds is not None:
+        request["bounds"] = bounds
+    if filters is not None:
+        request["filters"] = filters
+    if source_context is not None:
+        request["sourceContext"] = source_context
+    return normalize_many([request])[0]
+
+
+def normalize_checkpoint(
+    *,
+    thread_id: str,
+    path: str | Path | None = None,
+    bounds: NormalizationBounds | None = None,
+    filters: NormalizationFilters | None = None,
+    python_executable: str | None = None,
+) -> NormalizeResult:
+    """Normalize one Deep Agents thread from its LangGraph SQLite store.
+
+    ``path`` defaults to the Deep Agents CLI store, ``~/.deepagents/sessions.db``.
+    """
+
+    checkpoint: dict[str, str] = {
+        "threadId": thread_id,
+        "pythonExecutable": python_executable or sys.executable,
+    }
+    if path is not None:
+        checkpoint["path"] = str(path)
+    request: NormalizeRequest = {
+        "source": "deepagents",
+        "checkpoint": checkpoint,
+    }
+    if bounds is not None:
+        request["bounds"] = bounds
+    if filters is not None:
+        request["filters"] = filters
+    return normalize_many([request])[0]
+
+
+def list_trajectories(
+    *,
+    source: AnyTrajectorySource,
+    root: str | Path | None = None,
+    cursor: str | None = None,
+    limit: int | None = None,
+) -> ListTrajectoriesResult:
+    """List the trajectories in a source's local store, newest first.
+
+    Returns ``{"items": [...], "nextCursor": ...}``; ``nextCursor`` is present
+    exactly when more items remain. ``root`` overrides the source's standard
+    store location.
+    """
+
+    query: dict[str, object] = {"source": source}
+    if root is not None:
+        query["root"] = str(root)
+    if cursor is not None:
+        query["cursor"] = cursor
+    if limit is not None:
+        query["limit"] = limit
+    result = normalize_many([cast(NormalizeRequest, {"list": query})])[0]
+    return cast(ListTrajectoriesResult, result)
+
+
+def normalize_many(inputs: Iterable[NormalizeRequest]) -> list[NormalizeResult]:
+    """Normalize multiple transcript or checkpoint requests in one Node.js subprocess.
+
+    Results preserve input order. If a transcript fails, ``NormalizationError``
+    identifies its zero-based ``input_index``.
+    """
+
+    raw_requests = list(inputs)
+    if not raw_requests:
+        return []
+    requests: list[dict[str, object]] = []
+    for index, request in enumerate(raw_requests):
+        if not isinstance(request, Mapping):
+            raise TypeError(f"Input {index} must be a mapping.")
+        normalized_request = dict(request)
+        if normalized_request.get("source") == "deepagents":
+            checkpoint = normalized_request.get("checkpoint")
+            if isinstance(checkpoint, Mapping):
+                normalized_checkpoint = dict(checkpoint)
+                normalized_checkpoint.setdefault("pythonExecutable", sys.executable)
+                normalized_request["checkpoint"] = normalized_checkpoint
+        requests.append(normalized_request)
+
+    payload = json.dumps(
+        {"version": _PROTOCOL_VERSION, "requests": requests},
+        ensure_ascii=False,
+        separators=(",", ":"),
+    )
+    completed = _run_bridge(payload)
+    try:
+        response = json.loads(completed.stdout)
+    except json.JSONDecodeError as error:
+        raise TrajectoryRuntimeError(
+            "The trajectory runtime returned invalid JSON."
+        ) from error
+
+    if not isinstance(response, dict) or response.get("version") != _PROTOCOL_VERSION:
+        raise TrajectoryRuntimeError(
+            "The trajectory runtime protocol version did not match."
+        )
+    results = response.get("results")
+    if not isinstance(results, list) or len(results) != len(requests):
+        raise TrajectoryRuntimeError(
+            "The trajectory runtime returned an invalid result count."
+        )
+
+    normalized: list[NormalizeResult] = []
+    for index, item in enumerate(results):
+        if not isinstance(item, dict):
+            raise TrajectoryRuntimeError(
+                f"The trajectory runtime returned an invalid result at index {index}."
+            )
+        if item.get("ok") is True and isinstance(item.get("result"), dict):
+            normalized.append(cast(NormalizeResult, item["result"]))
+            continue
+        normalization_error = item.get("error")
+        if item.get("ok") is False and isinstance(normalization_error, dict):
+            code = normalization_error.get("code")
+            message = normalization_error.get("message")
+            if isinstance(code, str) and isinstance(message, str):
+                if code == "internal_error":
+                    raise TrajectoryRuntimeError(
+                        f"Trajectory runtime error for input {index}: {message}"
+                    )
+                raise NormalizationError(
+                    cast(NormalizationErrorCode, code), message, input_index=index
+                )
+        raise TrajectoryRuntimeError(
+            f"The trajectory runtime returned an invalid result at index {index}."
+        )
+    return normalized
+
+
+def _run_bridge(payload: str) -> subprocess.CompletedProcess[str]:
+    node = _node_executable()
+    if not _CLI_PATH.is_file():
+        raise TrajectoryRuntimeError(
+            f"The bundled trajectory runtime is missing at {_CLI_PATH}."
+        )
+    try:
+        return subprocess.run(
+            [node, str(_CLI_PATH)],
+            input=payload,
+            text=True,
+            encoding="utf-8",
+            capture_output=True,
+            check=True,
+        )
+    except subprocess.CalledProcessError as error:
+        detail = error.stderr.strip() or f"exit status {error.returncode}"
+        raise TrajectoryRuntimeError(
+            f"The trajectory runtime failed: {detail}"
+        ) from error
+    except OSError as error:
+        raise TrajectoryRuntimeError(
+            f"Could not execute the trajectory runtime: {error}"
+        ) from error
+
+
+@lru_cache(maxsize=1)
+def _node_executable() -> str:
+    node = shutil.which("node")
+    if node is None:
+        raise NodeUnavailableError("trajectory requires Node.js 20 or newer.")
+    try:
+        completed = subprocess.run(
+            [node, "--version"],
+            text=True,
+            encoding="utf-8",
+            capture_output=True,
+            check=True,
+        )
+    except (OSError, subprocess.CalledProcessError) as error:
+        raise NodeUnavailableError(
+            "trajectory could not determine the installed Node.js version."
+        ) from error
+    match = re.fullmatch(r"v(\d+)(?:\.\d+){2}\s*", completed.stdout)
+    if match is None or int(match.group(1)) < _MINIMUM_NODE_MAJOR:
+        version = completed.stdout.strip() or "unknown"
+        raise NodeUnavailableError(
+            f"trajectory requires Node.js 20 or newer; found {version}."
+        )
+    return node

trajectory/_errors.py

@@ -0,0 +1,22 @@
+"""Exceptions raised by the Python wrapper."""
+
+from ._types import NormalizationErrorCode
+
+
+class TrajectoryRuntimeError(RuntimeError):
+    """The bundled trajectory runtime could not be executed reliably."""
+
+
+class NodeUnavailableError(TrajectoryRuntimeError):
+    """Node.js 20 or newer could not be found."""
+
+
+class NormalizationError(ValueError):
+    """A transcript could not be normalized."""
+
+    def __init__(
+        self, code: NormalizationErrorCode, message: str, *, input_index: int = 0
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.input_index = input_index

trajectory/_types.py

@@ -0,0 +1,203 @@
+"""Public typing contract for trajectory inputs and outputs."""
+
+from typing import Literal, TypedDict, Union
+
+TrajectorySource = Literal[
+    "claude-code", "codex", "copilot-cli", "cursor", "droid", "gemini-cli", "hermes", "letta-code", "omp", "openclaw", "opencode", "openhands", "pi"
+]
+CheckpointTrajectorySource = Literal["deepagents"]
+AnyTrajectorySource = Literal[
+    "claude-code", "codex", "copilot-cli", "cursor", "droid", "gemini-cli", "hermes", "letta-code", "omp", "openclaw", "opencode", "openhands", "pi", "deepagents"
+]
+ToolResultTruncationStrategy = Literal["head", "head-tail"]
+ToolResultPolicy = Literal["include", "omit"]
+DiagnosticCode = Literal[
+    "invalid_json_line",
+    "non_object_json_line",
+    "injected_context_dropped",
+    "noise_record_dropped",
+    "sidechain_record_dropped",
+    "tool_call_id_synthesized",
+    "duplicate_tool_call_id",
+    "orphan_tool_result",
+    "duplicate_tool_result",
+    "unknown_tool_name",
+    "tool_arguments_reshaped",
+    "tool_arguments_truncated",
+    "tool_result_truncated",
+    "timestamps_synthesized",
+    "timestamps_interpolated",
+]
+NormalizationErrorCode = Literal[
+    "invalid_input",
+    "unknown_source",
+    "python_unavailable",
+    "python_dependency_missing",
+    "checkpoint_database_not_found",
+    "checkpoint_database_unreadable",
+    "checkpoint_read_failed",
+    "checkpoint_not_found",
+    "checkpoint_messages_missing",
+    "invalid_checkpoint_state",
+    "listing_unavailable",
+    "missing_user_records",
+    "missing_assistant_records",
+    "invalid_normalized_transcript",
+    "source_group_required",
+    "source_group_conflict",
+]
+
+
+class _TrajectoryListingOptional(TypedDict, total=False):
+    updatedAt: str
+    title: str
+    sizeBytes: int
+
+
+class TrajectoryListing(_TrajectoryListingOptional):
+    id: str
+    path: str
+
+
+class _ListTrajectoriesResultOptional(TypedDict, total=False):
+    nextCursor: str
+
+
+class ListTrajectoriesResult(_ListTrajectoriesResultOptional):
+    items: list[TrajectoryListing]
+
+
+class ToolArgumentBounds(TypedDict, total=False):
+    maxCharacters: int | None
+
+
+class ToolResultBounds(TypedDict, total=False):
+    maxCharacters: int | None
+    strategy: ToolResultTruncationStrategy
+
+
+class NormalizationBounds(TypedDict, total=False):
+    toolArguments: ToolArgumentBounds
+    toolResults: ToolResultBounds
+
+
+class NormalizationFilters(TypedDict, total=False):
+    toolResults: ToolResultPolicy
+
+
+class SourceContext(TypedDict, total=False):
+    groupId: str
+    baseByteOffset: int
+    partial: bool
+
+
+class _NormalizeInputOptional(TypedDict, total=False):
+    bounds: NormalizationBounds
+    filters: NormalizationFilters
+    sourceContext: SourceContext
+
+
+class NormalizeInput(_NormalizeInputOptional):
+    source: TrajectorySource
+    transcript: str
+
+
+class _DeepAgentsCheckpointLocationOptional(TypedDict, total=False):
+    path: str
+    pythonExecutable: str
+
+
+class DeepAgentsCheckpointLocation(_DeepAgentsCheckpointLocationOptional):
+    threadId: str
+
+
+class _DeepAgentsCheckpointInputOptional(TypedDict, total=False):
+    bounds: NormalizationBounds
+    filters: NormalizationFilters
+
+
+class DeepAgentsCheckpointInput(_DeepAgentsCheckpointInputOptional):
+    source: Literal["deepagents"]
+    checkpoint: DeepAgentsCheckpointLocation
+
+
+NormalizeRequest = Union[NormalizeInput, DeepAgentsCheckpointInput]
+
+
+class _DiagnosticOptional(TypedDict, total=False):
+    inputLine: int
+    recordIndex: int
+    count: int
+
+
+class Diagnostic(_DiagnosticOptional):
+    code: DiagnosticCode
+    message: str
+
+
+class _MetaOptional(TypedDict, total=False):
+    cwd: str
+    git_branch: str
+    model: str
+
+
+class MetaRecord(_MetaOptional):
+    role: Literal["meta"]
+    source: str
+
+
+class UserRecord(TypedDict):
+    role: Literal["user"]
+    content: str
+    timestamp: str
+
+
+class ReasoningRecord(TypedDict):
+    role: Literal["reasoning"]
+    content: str
+    timestamp: str
+
+
+class AssistantMessageRecord(TypedDict):
+    role: Literal["assistant"]
+    content: str
+    timestamp: str
+
+
+class ToolCall(TypedDict):
+    id: str
+    name: str
+    args: str
+
+
+class AssistantToolCallRecord(TypedDict):
+    role: Literal["assistant"]
+    content: None
+    tool_calls: list[ToolCall]
+    timestamp: str
+
+
+class _ToolResultOptional(TypedDict, total=False):
+    ok: bool
+
+
+class ToolResultRecord(_ToolResultOptional):
+    role: Literal["tool"]
+    tool_call_id: str
+    content: str
+    timestamp: str
+
+
+NormalizedRecord = Union[
+    MetaRecord,
+    UserRecord,
+    ReasoningRecord,
+    AssistantMessageRecord,
+    AssistantToolCallRecord,
+    ToolResultRecord,
+]
+
+
+class NormalizeResult(TypedDict):
+    records: list[NormalizedRecord]
+    diagnostics: list[Diagnostic]