atomicdjt-agent-session-bridge 0.2.1__tar.gz

atomicdjt_agent_session_bridge-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Session Bridge Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

atomicdjt_agent_session_bridge-0.2.1/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: atomicdjt-agent-session-bridge
+Version: 0.2.1
+Summary: ATIF-based reference implementation for portable coding-agent trajectories with explicit fidelity and loss reporting.
+Author: David Turner
+License: MIT
+Project-URL: Homepage, https://github.com/atomicdjt/agent-session-bridge
+Project-URL: Repository, https://github.com/atomicdjt/agent-session-bridge
+Project-URL: Issues, https://github.com/atomicdjt/agent-session-bridge/issues
+Keywords: ai-agents,coding-agents,claude-code,session-portability,interoperability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: atif<1.8,>=1.7
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.0.280; extra == "dev"
+Provides-Extra: observability
+Requires-Dist: opentelemetry-api>=1.20.0; extra == "observability"
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "observability"
+Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == "observability"
+Requires-Dist: openinference-semantic-conventions>=0.1.0; extra == "observability"
+Dynamic: license-file
+
+# Agent Session Bridge
+
+**Move structured coding-agent history between tools without collapsing it into a prose summary.**
+
+**[Canonical project page](https://ai-project-portfolio-portfolio-hub.vercel.app/projects/agent-session-bridge) · [Repository](https://github.com/atomicdjt/agent-session-bridge) · [Full portfolio](https://ai-project-portfolio-portfolio-hub.vercel.app/)**
+
+Agent Session Bridge is an MIT-licensed reference implementation for converting supported coding-agent transcripts into the [Agent Trajectory Interchange Format (ATIF)](https://github.com/harbor-framework/harbor/blob/main/rfcs/0001-trajectory-format.md). It is not a competing interchange standard.
+
+> **Current status:** Claude Code JSONL normalization to ATIF v1.7, heuristic secret redaction, ASB fidelity reporting, and an Antigravity derived-log mapping are implemented. Native Antigravity session rehydration is not supported because Antigravity has no supported historical-session import boundary.
+
+![Agent Session Bridge quick tour](docs/images/agent-session-bridge-quick-tour.gif)
+
+*Animated architecture tour based on documented behavior; it is not a fabricated live screen recording.*
+
+## What ATIF provides and what ASB adds
+
+ATIF is the portable trajectory layer: ordered system/user/agent steps, structured tool calls, call-correlated observations, agent metadata, metrics, and a namespaced `extra` extension mechanism. ASB converts provider-specific transcript shapes into that public format.
+
+ASB's distinct responsibilities are deliberately narrower:
+
+- provider-specific parsing and normalization;
+- best-effort secret redaction before export;
+- transformation/fidelity accounting in `extra.agent_session_bridge`;
+- target-specific mappings, such as the observed Antigravity derived-log shape; and
+- explicit refusal to fabricate native resumable session state.
+
+The current Antigravity reference mapper reports any ATIF system messages it cannot map to the observed derived-log shape; it does not silently invent a target record type.
+
+See [the ATIF mapping](docs/FORMAT.md) and [layered architecture](docs/ARCHITECTURE.md) for exact preserved, transformed, and unsupported semantics.
+
+## What works today
+
+| Capability | Status | Notes |
+| --- | --- | --- |
+| Claude Code JSONL import | ✅ | Parses supported message and tool structures into ATIF v1.7 |
+| Portable interchange document | ✅ | Validated by the official `atif` Python models |
+| ASB fidelity reporting | ✅ | Namespaced provenance and unsupported/degraded source counts in ATIF `extra` |
+| Heuristic secret redaction | ✅ | Best effort only; output still requires human review |
+| Antigravity derived-log mapping | ✅ | Reference payload based on observed `transcript.jsonl` structures |
+| Native Antigravity session import | ❌ blocked upstream | No supported API creates or resumes external historical state |
+
+## Quick start
+
+This project is not published as `agent-session-bridge` on PyPI; that name belongs to an unrelated project. It is packaged as `atomicdjt-agent-session-bridge` (build and install verified locally — sdist/wheel pass `twine check`, install cleanly into a fresh virtualenv, and the CLI runs end-to-end against the fixtures in this repo). It is not yet live on PyPI; see [Releasing](#releasing) for the exact remaining step. Until then, install from this repository with Python 3.11 or newer:
+
+```bash
+git clone https://github.com/atomicdjt/agent-session-bridge.git
+cd agent-session-bridge
+python -m venv .venv
+```
+
+Activate the environment, then install the package:
+
+```bash
+# Linux/macOS
+source .venv/bin/activate
+
+# Windows PowerShell
+.\.venv\Scripts\Activate.ps1
+
+python -m pip install -e .
+```
+
+Normalize a Claude Code transcript to an ATIF document, inspect ASB's source-fidelity report, or generate the Antigravity reference mapping:
+
+```bash
+agent-session import --from claude-code --source your_claude_log.jsonl --output trajectory.atif.json --report
+agent-session convert --from claude-code --to antigravity your_claude_log.jsonl
+agent-session handoff --from claude-code --to antigravity your_claude_log.jsonl
+```
+
+`handoff` returns `UnsupportedNativeImport` after producing the reference payload. It does not imply that Antigravity can resume the converted history.
+
+## Architecture
+
+```text
+provider transcript
+       │
+       ▼
+source parser and normalizer
+       │
+       ▼
+ATIF trajectory ─────► ASB provenance/fidelity extension
+       │
+       ├──────────────► redacted portable trajectory
+       │
+       ▼
+target-specific mapper
+       │
+       ▼
+target payload / supported importer, if one exists
+```
+
+ATIF makes a trajectory portable; it does not require target runtimes to ingest it as native state. Native resumption remains a target-owned capability, with target-owned validation, persistence, and security constraints.
+
+## Fidelity and security boundaries
+
+For the current Claude Code adapter, ASB preserves supported roles, ISO-8601 timestamps, text, tool names, tool arguments, and tool results. It normalizes later Claude `tool_result` blocks into ATIF observations attached to their originating calls. Unsupported source records or blocks are counted in `extra.agent_session_bridge.fidelity`; they are never represented as successfully preserved.
+
+- Imported history is processed as data. Historical commands are never executed.
+- Redaction is heuristic and is not a guarantee.
+- Do not publish a converted transcript without reviewing it for credentials, personal data, private source, or proprietary context.
+- ASB does not reverse-engineer or write Antigravity's opaque internal session database.
+
+## Optional observability projection
+
+The observability implementation is an optional downstream projection of ATIF, not a replacement for ATIF, and not original runtime instrumentation. It is a historical structural projection.
+
+```text
+provider transcript
+        ↓
+Agent Session Bridge
+        ↓
+ATIF v1.7
+        ↓
+historical observability projection
+        ↓
+OpenTelemetry / OpenInference
+        ↓
+OTLP
+        ↓
+Phoenix or another compatible backend
+```
+
+To install the optional observability dependencies:
+
+```bash
+python -m pip install -e ".[observability]"
+```
+
+For the local Phoenix example, Phoenix may be installed separately. It is not required for core Agent Session Bridge operation:
+
+```bash
+python -m pip install arize-phoenix
+```
+
+A Claude Code source may also be observed using the existing supported `--from claude-code` path where appropriate.
+
+```bash
+agent-session observe trajectory.atif.json \
+  --from atif \
+  --backend phoenix \
+  --endpoint http://127.0.0.1:6006/v1/traces
+```
+
+### Privacy
+
+- `metadata-only` is the default.
+- `redacted-content` exports redacted textual content.
+- `full-content` must be explicitly selected and may expose sensitive transcript data. Treat `full-content` carefully.
+
+### Historical timing
+
+As this is a historical structural projection:
+- ATIF Step timestamps may be represented as observed timing.
+- Root boundaries may be derived from observed Step timestamps.
+- Where independent tool completion timing is unavailable from ATIF, the projection does not pretend to have measured runtime duration.
+
+For implementation details, see [docs/OBSERVABILITY.md](docs/OBSERVABILITY.md). For the evidence model, ecosystem comparison, limitations, and external-review questions, see [Reconstructing Agent Traces After the Fact Without Inventing Runtime Truth](docs/HISTORICAL_OBSERVABILITY_WRITEUP.md).
+
+## Migration from v0.1 ASEF output
+
+v0.2 removes the proprietary ASEF schema. Existing `*.asef.json` files are not ATIF documents and must not be relabeled as such. Re-run the original source transcript through `agent-session import` to produce a validated `*.atif.json` file, then review the ASB fidelity report. Python 3.11 is now the minimum supported version because the official ATIF models require it.
+
+## Releasing
+
+`.github/workflows/publish.yml` builds the sdist/wheel, runs `twine check`, and publishes to PyPI via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC) on a `v*.*.*` tag push or manual dispatch. No PyPI token is stored in this repository.
+
+Before the first publish, add a pending trusted publisher on pypi.org for a project named `atomicdjt-agent-session-bridge`, with owner `atomicdjt`, repository `agent-session-bridge`, workflow `publish.yml`, and environment `pypi`. That is the only step this workflow cannot perform on its own.
+
+## Contributing
+
+Useful contributions include provider transcript fixtures, source adapters, target mappings for documented ingestion boundaries, fidelity-report improvements, and reproducible evidence about real cross-provider transformations. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

atomicdjt_agent_session_bridge-0.2.1/README.md

@@ -0,0 +1,177 @@
+# Agent Session Bridge
+
+**Move structured coding-agent history between tools without collapsing it into a prose summary.**
+
+**[Canonical project page](https://ai-project-portfolio-portfolio-hub.vercel.app/projects/agent-session-bridge) · [Repository](https://github.com/atomicdjt/agent-session-bridge) · [Full portfolio](https://ai-project-portfolio-portfolio-hub.vercel.app/)**
+
+Agent Session Bridge is an MIT-licensed reference implementation for converting supported coding-agent transcripts into the [Agent Trajectory Interchange Format (ATIF)](https://github.com/harbor-framework/harbor/blob/main/rfcs/0001-trajectory-format.md). It is not a competing interchange standard.
+
+> **Current status:** Claude Code JSONL normalization to ATIF v1.7, heuristic secret redaction, ASB fidelity reporting, and an Antigravity derived-log mapping are implemented. Native Antigravity session rehydration is not supported because Antigravity has no supported historical-session import boundary.
+
+![Agent Session Bridge quick tour](docs/images/agent-session-bridge-quick-tour.gif)
+
+*Animated architecture tour based on documented behavior; it is not a fabricated live screen recording.*
+
+## What ATIF provides and what ASB adds
+
+ATIF is the portable trajectory layer: ordered system/user/agent steps, structured tool calls, call-correlated observations, agent metadata, metrics, and a namespaced `extra` extension mechanism. ASB converts provider-specific transcript shapes into that public format.
+
+ASB's distinct responsibilities are deliberately narrower:
+
+- provider-specific parsing and normalization;
+- best-effort secret redaction before export;
+- transformation/fidelity accounting in `extra.agent_session_bridge`;
+- target-specific mappings, such as the observed Antigravity derived-log shape; and
+- explicit refusal to fabricate native resumable session state.
+
+The current Antigravity reference mapper reports any ATIF system messages it cannot map to the observed derived-log shape; it does not silently invent a target record type.
+
+See [the ATIF mapping](docs/FORMAT.md) and [layered architecture](docs/ARCHITECTURE.md) for exact preserved, transformed, and unsupported semantics.
+
+## What works today
+
+| Capability | Status | Notes |
+| --- | --- | --- |
+| Claude Code JSONL import | ✅ | Parses supported message and tool structures into ATIF v1.7 |
+| Portable interchange document | ✅ | Validated by the official `atif` Python models |
+| ASB fidelity reporting | ✅ | Namespaced provenance and unsupported/degraded source counts in ATIF `extra` |
+| Heuristic secret redaction | ✅ | Best effort only; output still requires human review |
+| Antigravity derived-log mapping | ✅ | Reference payload based on observed `transcript.jsonl` structures |
+| Native Antigravity session import | ❌ blocked upstream | No supported API creates or resumes external historical state |
+
+## Quick start
+
+This project is not published as `agent-session-bridge` on PyPI; that name belongs to an unrelated project. It is packaged as `atomicdjt-agent-session-bridge` (build and install verified locally — sdist/wheel pass `twine check`, install cleanly into a fresh virtualenv, and the CLI runs end-to-end against the fixtures in this repo). It is not yet live on PyPI; see [Releasing](#releasing) for the exact remaining step. Until then, install from this repository with Python 3.11 or newer:
+
+```bash
+git clone https://github.com/atomicdjt/agent-session-bridge.git
+cd agent-session-bridge
+python -m venv .venv
+```
+
+Activate the environment, then install the package:
+
+```bash
+# Linux/macOS
+source .venv/bin/activate
+
+# Windows PowerShell
+.\.venv\Scripts\Activate.ps1
+
+python -m pip install -e .
+```
+
+Normalize a Claude Code transcript to an ATIF document, inspect ASB's source-fidelity report, or generate the Antigravity reference mapping:
+
+```bash
+agent-session import --from claude-code --source your_claude_log.jsonl --output trajectory.atif.json --report
+agent-session convert --from claude-code --to antigravity your_claude_log.jsonl
+agent-session handoff --from claude-code --to antigravity your_claude_log.jsonl
+```
+
+`handoff` returns `UnsupportedNativeImport` after producing the reference payload. It does not imply that Antigravity can resume the converted history.
+
+## Architecture
+
+```text
+provider transcript
+       │
+       ▼
+source parser and normalizer
+       │
+       ▼
+ATIF trajectory ─────► ASB provenance/fidelity extension
+       │
+       ├──────────────► redacted portable trajectory
+       │
+       ▼
+target-specific mapper
+       │
+       ▼
+target payload / supported importer, if one exists
+```
+
+ATIF makes a trajectory portable; it does not require target runtimes to ingest it as native state. Native resumption remains a target-owned capability, with target-owned validation, persistence, and security constraints.
+
+## Fidelity and security boundaries
+
+For the current Claude Code adapter, ASB preserves supported roles, ISO-8601 timestamps, text, tool names, tool arguments, and tool results. It normalizes later Claude `tool_result` blocks into ATIF observations attached to their originating calls. Unsupported source records or blocks are counted in `extra.agent_session_bridge.fidelity`; they are never represented as successfully preserved.
+
+- Imported history is processed as data. Historical commands are never executed.
+- Redaction is heuristic and is not a guarantee.
+- Do not publish a converted transcript without reviewing it for credentials, personal data, private source, or proprietary context.
+- ASB does not reverse-engineer or write Antigravity's opaque internal session database.
+
+## Optional observability projection
+
+The observability implementation is an optional downstream projection of ATIF, not a replacement for ATIF, and not original runtime instrumentation. It is a historical structural projection.
+
+```text
+provider transcript
+        ↓
+Agent Session Bridge
+        ↓
+ATIF v1.7
+        ↓
+historical observability projection
+        ↓
+OpenTelemetry / OpenInference
+        ↓
+OTLP
+        ↓
+Phoenix or another compatible backend
+```
+
+To install the optional observability dependencies:
+
+```bash
+python -m pip install -e ".[observability]"
+```
+
+For the local Phoenix example, Phoenix may be installed separately. It is not required for core Agent Session Bridge operation:
+
+```bash
+python -m pip install arize-phoenix
+```
+
+A Claude Code source may also be observed using the existing supported `--from claude-code` path where appropriate.
+
+```bash
+agent-session observe trajectory.atif.json \
+  --from atif \
+  --backend phoenix \
+  --endpoint http://127.0.0.1:6006/v1/traces
+```
+
+### Privacy
+
+- `metadata-only` is the default.
+- `redacted-content` exports redacted textual content.
+- `full-content` must be explicitly selected and may expose sensitive transcript data. Treat `full-content` carefully.
+
+### Historical timing
+
+As this is a historical structural projection:
+- ATIF Step timestamps may be represented as observed timing.
+- Root boundaries may be derived from observed Step timestamps.
+- Where independent tool completion timing is unavailable from ATIF, the projection does not pretend to have measured runtime duration.
+
+For implementation details, see [docs/OBSERVABILITY.md](docs/OBSERVABILITY.md). For the evidence model, ecosystem comparison, limitations, and external-review questions, see [Reconstructing Agent Traces After the Fact Without Inventing Runtime Truth](docs/HISTORICAL_OBSERVABILITY_WRITEUP.md).
+
+## Migration from v0.1 ASEF output
+
+v0.2 removes the proprietary ASEF schema. Existing `*.asef.json` files are not ATIF documents and must not be relabeled as such. Re-run the original source transcript through `agent-session import` to produce a validated `*.atif.json` file, then review the ASB fidelity report. Python 3.11 is now the minimum supported version because the official ATIF models require it.
+
+## Releasing
+
+`.github/workflows/publish.yml` builds the sdist/wheel, runs `twine check`, and publishes to PyPI via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC) on a `v*.*.*` tag push or manual dispatch. No PyPI token is stored in this repository.
+
+Before the first publish, add a pending trusted publisher on pypi.org for a project named `atomicdjt-agent-session-bridge`, with owner `atomicdjt`, repository `agent-session-bridge`, workflow `publish.yml`, and environment `pypi`. That is the only step this workflow cannot perform on its own.
+
+## Contributing
+
+Useful contributions include provider transcript fixtures, source adapters, target mappings for documented ingestion boundaries, fidelity-report improvements, and reproducible evidence about real cross-provider transformations. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

atomicdjt_agent_session_bridge-0.2.1/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "atomicdjt-agent-session-bridge"
+version = "0.2.1"
+description = "ATIF-based reference implementation for portable coding-agent trajectories with explicit fidelity and loss reporting."
+readme = "README.md"
+license = {text = "MIT"}
+authors = [{name = "David Turner"}]
+requires-python = ">=3.11"
+dependencies = [
+    "atif>=1.7,<1.8",
+    "pydantic>=2.0.0",
+]
+keywords = [
+    "ai-agents",
+    "coding-agents",
+    "claude-code",
+    "session-portability",
+    "interoperability",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/atomicdjt/agent-session-bridge"
+Repository = "https://github.com/atomicdjt/agent-session-bridge"
+Issues = "https://github.com/atomicdjt/agent-session-bridge/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "mypy>=1.0.0",
+    "ruff>=0.0.280"
+]
+
+observability = [
+    "opentelemetry-api>=1.20.0",
+    "opentelemetry-sdk>=1.20.0",
+    "opentelemetry-exporter-otlp>=1.20.0",
+    "openinference-semantic-conventions>=0.1.0",
+]
+
+[project.scripts]
+agent-session = "cli.main:main"

atomicdjt_agent_session_bridge-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

atomicdjt_agent_session_bridge-0.2.1/src/adapters/antigravity/exporter.py

@@ -0,0 +1,83 @@
+import json
+from dataclasses import dataclass
+
+from atif import Step, Trajectory
+
+
+@dataclass(frozen=True)
+class AntigravityExport:
+    payload: str
+    omitted_system_messages: int
+
+
+def export_to_antigravity(trajectory: Trajectory) -> str:
+    """Return the reference payload for callers that need only JSONL."""
+    return export_with_report(trajectory).payload
+
+
+def export_with_report(trajectory: Trajectory) -> AntigravityExport:
+    """Map an ATIF trajectory to the observed Antigravity derived-log shape.
+
+    This is a reference export only. The generated log is not represented as a
+    supported native Antigravity session-import format.
+    """
+    transcript_lines: list[str] = []
+    omitted_system_messages = 0
+
+    for step in trajectory.steps:
+        if step.source == "user":
+            transcript_lines.append(
+                json.dumps(
+                    {
+                        "step_index": len(transcript_lines) + 1,
+                        "source": "USER_EXPLICIT",
+                        "type": "USER_INPUT",
+                        "status": "DONE",
+                        "created_at": step.timestamp,
+                        "content": step.message,
+                    }
+                )
+            )
+        elif step.source == "agent":
+            transcript_lines.append(
+                json.dumps(
+                    {
+                        "step_index": len(transcript_lines) + 1,
+                        "source": "MODEL",
+                        "type": "PLANNER_RESPONSE",
+                        "status": "DONE",
+                        "created_at": step.timestamp,
+                        "content": step.message,
+                        "tool_calls": _tool_calls(step),
+                    }
+                )
+            )
+        elif step.source == "system" and step.message:
+            omitted_system_messages += 1
+
+        if step.observation:
+            for result in step.observation.results:
+                transcript_lines.append(
+                    json.dumps(
+                        {
+                            "step_index": len(transcript_lines) + 1,
+                            "source": "SYSTEM",
+                            "type": "TOOL_RESPONSE",
+                            "status": "DONE",
+                            "created_at": step.timestamp,
+                            "content": result.content or "",
+                        }
+                    )
+                )
+
+    return AntigravityExport(
+        payload="\n".join(transcript_lines) + "\n",
+        omitted_system_messages=omitted_system_messages,
+    )
+
+
+def _tool_calls(step: Step) -> list[dict[str, object]]:
+    return [
+        {"name": call.function_name, "args": call.arguments}
+        for call in step.tool_calls or []
+    ]