forgesight-github 0.1.0__tar.gz

forgesight_github-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# venv / tooling
+.venv/
+venv/
+.uv/
+uv.lock
+
+# test / type / lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# secrets / local env (never commit)
+.env
+.env.*
+
+# editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# local-only session working state (per the workspace pipeline)
+.claude/state/
+
+# local-only launch planning (not part of the published repo)
+/launch/

forgesight_github-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: forgesight-github
+Version: 0.1.0
+Summary: ForgeSight GitHub Actions integration — one-line CI bootstrap; run↔commit/PR/job correlation.
+Project-URL: Homepage, https://github.com/Scaffoldic/forgesight
+Project-URL: Repository, https://github.com/Scaffoldic/forgesight
+Project-URL: Issues, https://github.com/Scaffoldic/forgesight/issues
+Project-URL: Changelog, https://github.com/Scaffoldic/forgesight/blob/main/docs/releases/v0.1.md
+Author: kjoshi
+License-Expression: Apache-2.0
+Keywords: ai-agents,ci,forgesight,github-actions,observability
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: forgesight-core
+Description-Content-Type: text/markdown
+
+# forgesight-github
+
+The GitHub Actions integration for [ForgeSight](https://github.com/Scaffoldic/forgesight).
+One line in your CI entry script correlates every agent run with the commit / PR / job /
+workflow that triggered it, and writes a cost+duration+status summary to the job page.
+
+```bash
+pip install forgesight-github
+```
+
+```python
+from forgesight_github import bootstrap
+bootstrap()   # configure() + attach GITHUB_* metadata + job summary on exit
+
+# Unchanged agent code — every run in this job is now correlated and flushed cleanly.
+result = await pr_reviewer.run(task)
+```
+
+```yaml
+# .github/workflows/review.yml
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write          # only if using OIDC exporter auth
+    steps:
+      - uses: actions/checkout@v4
+      - run: pip install forgesight-github
+      - run: python review_agent.py
+        env:
+          FORGESIGHT_EXPORTERS: otlp
+          FORGESIGHT_OTLP_ENDPOINT: ${{ vars.OTEL_COLLECTOR }}
+```
+
+## What you get
+
+- **Run↔commit/PR/job link for free.** Every run carries `vcs.repository.name`,
+  `vcs.ref.head.revision` (sha), `vcs.ref.head.name` (ref), `vcs.change.id` (PR number),
+  `cicd.pipeline.run.id` / `.attempt`, `cicd.pipeline.name` (workflow), and
+  `cicd.pipeline.task.name` (job) as run-scoped metadata (FR-5), so "agent spend on PR #1234"
+  or "spend by workflow" is a one-line backend query.
+- **PR number resolved correctly.** Parsed from the event payload JSON (`$GITHUB_EVENT_PATH`)
+  for `pull_request*` events — absent (not fabricated) otherwise.
+- **A useful job summary, automatically.** A markdown block —
+  `status · cost_usd · duration_ms · n_tool_calls` — is appended to `$GITHUB_STEP_SUMMARY`
+  on exit. Best-effort; never fails the job.
+- **Zero lost CI telemetry.** An `atexit` hook calls `force_flush()` + `shutdown()` so the
+  ephemeral runner never drops the buffered batch.
+- **Safe exporter auth (opt-in).** `bootstrap(oidc=True)` fetches the runner's short-lived
+  OIDC id-token (requires `id-token: write`) instead of a static secret; falls back to
+  configured auth if unavailable.
+- **Runs locally too.** Outside CI (`GITHUB_ACTIONS` unset) it falls back to a plain
+  `configure()` and warns once.
+
+## Configuration
+
+| Key | Env | Default |
+|---|---|---|
+| `write_summary` | `FORGESIGHT_GITHUB_SUMMARY` | `true` |
+| `oidc` | — (kwarg) | `false` |
+| `capture_env` | — (kwarg) | the documented `GITHUB_*` set |
+
+## License
+
+Apache-2.0

forgesight_github-0.1.0/README.md

@@ -0,0 +1,65 @@
+# forgesight-github
+
+The GitHub Actions integration for [ForgeSight](https://github.com/Scaffoldic/forgesight).
+One line in your CI entry script correlates every agent run with the commit / PR / job /
+workflow that triggered it, and writes a cost+duration+status summary to the job page.
+
+```bash
+pip install forgesight-github
+```
+
+```python
+from forgesight_github import bootstrap
+bootstrap()   # configure() + attach GITHUB_* metadata + job summary on exit
+
+# Unchanged agent code — every run in this job is now correlated and flushed cleanly.
+result = await pr_reviewer.run(task)
+```
+
+```yaml
+# .github/workflows/review.yml
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write          # only if using OIDC exporter auth
+    steps:
+      - uses: actions/checkout@v4
+      - run: pip install forgesight-github
+      - run: python review_agent.py
+        env:
+          FORGESIGHT_EXPORTERS: otlp
+          FORGESIGHT_OTLP_ENDPOINT: ${{ vars.OTEL_COLLECTOR }}
+```
+
+## What you get
+
+- **Run↔commit/PR/job link for free.** Every run carries `vcs.repository.name`,
+  `vcs.ref.head.revision` (sha), `vcs.ref.head.name` (ref), `vcs.change.id` (PR number),
+  `cicd.pipeline.run.id` / `.attempt`, `cicd.pipeline.name` (workflow), and
+  `cicd.pipeline.task.name` (job) as run-scoped metadata (FR-5), so "agent spend on PR #1234"
+  or "spend by workflow" is a one-line backend query.
+- **PR number resolved correctly.** Parsed from the event payload JSON (`$GITHUB_EVENT_PATH`)
+  for `pull_request*` events — absent (not fabricated) otherwise.
+- **A useful job summary, automatically.** A markdown block —
+  `status · cost_usd · duration_ms · n_tool_calls` — is appended to `$GITHUB_STEP_SUMMARY`
+  on exit. Best-effort; never fails the job.
+- **Zero lost CI telemetry.** An `atexit` hook calls `force_flush()` + `shutdown()` so the
+  ephemeral runner never drops the buffered batch.
+- **Safe exporter auth (opt-in).** `bootstrap(oidc=True)` fetches the runner's short-lived
+  OIDC id-token (requires `id-token: write`) instead of a static secret; falls back to
+  configured auth if unavailable.
+- **Runs locally too.** Outside CI (`GITHUB_ACTIONS` unset) it falls back to a plain
+  `configure()` and warns once.
+
+## Configuration
+
+| Key | Env | Default |
+|---|---|---|
+| `write_summary` | `FORGESIGHT_GITHUB_SUMMARY` | `true` |
+| `oidc` | — (kwarg) | `false` |
+| `capture_env` | — (kwarg) | the documented `GITHUB_*` set |
+
+## License
+
+Apache-2.0

forgesight_github-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "forgesight-github"
+version = "0.1.0"
+description = "ForgeSight GitHub Actions integration — one-line CI bootstrap; run↔commit/PR/job correlation."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "kjoshi" }]
+keywords = ["observability", "github-actions", "ci", "ai-agents", "forgesight"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Topic :: System :: Monitoring",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["forgesight-core"]
+
+[project.entry-points."forgesight.integrations"]
+github = "forgesight_github:install"
+
+[project.urls]
+Homepage = "https://github.com/Scaffoldic/forgesight"
+Repository = "https://github.com/Scaffoldic/forgesight"
+Issues = "https://github.com/Scaffoldic/forgesight/issues"
+Changelog = "https://github.com/Scaffoldic/forgesight/blob/main/docs/releases/v0.1.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/forgesight_github"]
+
+[tool.uv.sources]
+forgesight-core = { workspace = true }

forgesight_github-0.1.0/src/forgesight_github/__init__.py

@@ -0,0 +1,34 @@
+"""ForgeSight GitHub Actions integration — one-line CI bootstrap; run↔commit/PR/job link.
+
+```python
+from forgesight_github import bootstrap
+bootstrap()   # configure() + attach GITHUB_* metadata + job summary on exit
+```
+"""
+
+from __future__ import annotations
+
+from .bootstrap import bootstrap, in_github_actions, install, run_exit_hook
+from .interceptor import GitHubMetadataInterceptor
+from .metadata import GITHUB_ENV_MAP, github_metadata, pr_number
+from .oidc import fetch_oidc_token
+from .summary import DEFAULT_SUMMARY_METRICS, SummaryCollector, format_summary, write_summary
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_SUMMARY_METRICS",
+    "GITHUB_ENV_MAP",
+    "GitHubMetadataInterceptor",
+    "SummaryCollector",
+    "__version__",
+    "bootstrap",
+    "fetch_oidc_token",
+    "format_summary",
+    "github_metadata",
+    "in_github_actions",
+    "install",
+    "pr_number",
+    "run_exit_hook",
+    "write_summary",
+]

forgesight_github-0.1.0/src/forgesight_github/bootstrap.py

@@ -0,0 +1,127 @@
+"""``bootstrap()`` — the one-line CI wiring, plus the ``forgesight.integrations`` ``install``.
+
+``bootstrap()`` does three things in order: read ``GITHUB_*`` metadata, ``configure()`` the
+SDK and attach that metadata to every record (FR-5), and register an exit hook that flushes
+telemetry (so a deploy/ephemeral runner never drops it) and writes a job summary. Outside CI
+it falls back to a plain ``configure()`` and warns once, so the same script runs locally.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import os
+from collections.abc import Mapping, Sequence
+
+from forgesight_core import Runtime, configure
+
+from .interceptor import GitHubMetadataInterceptor
+from .metadata import github_metadata
+from .oidc import fetch_oidc_token
+from .summary import DEFAULT_SUMMARY_METRICS, SummaryCollector, write_summary
+
+_log = logging.getLogger("forgesight.github")
+
+OIDC_TOKEN_ENV = "FORGESIGHT_OTLP_TOKEN"  # documented hand-off for the collector/exporter
+_warned_not_ci = False
+_installed_config: dict[str, object] = {}
+
+
+def in_github_actions(env: Mapping[str, str] | None = None) -> bool:
+    source = os.environ if env is None else env
+    return source.get("GITHUB_ACTIONS") == "true"
+
+
+def bootstrap(
+    *,
+    write_summary: bool = True,
+    summary_metrics: Sequence[str] = DEFAULT_SUMMARY_METRICS,
+    oidc: bool = False,
+    extra_metadata: Mapping[str, str] | None = None,
+    _register_exit: bool = True,
+) -> None:
+    """One-line CI bootstrap: ``configure()``, attach ``GITHUB_*`` metadata, summary-on-exit."""
+    in_ci = in_github_actions()
+    if not in_ci:
+        _warn_not_ci()
+
+    metadata: dict[str, str] = github_metadata() if in_ci else {}
+    if extra_metadata:
+        metadata.update(extra_metadata)
+
+    if oidc:
+        _apply_oidc()
+
+    runtime = configure()
+    if metadata:
+        runtime.add_interceptor(GitHubMetadataInterceptor(metadata))
+
+    do_summary = write_summary and in_ci and _summary_enabled()
+    collector: SummaryCollector | None = None
+    if do_summary:
+        collector = SummaryCollector()
+        runtime.add_listener(collector)
+
+    fields = tuple(summary_metrics)
+    if _register_exit:
+        atexit.register(run_exit_hook, runtime, collector, fields)
+
+
+def run_exit_hook(
+    runtime: Runtime, collector: SummaryCollector | None, fields: Sequence[str]
+) -> None:
+    """Flush telemetry then (best-effort) write the job summary. Safe to call directly."""
+    timeout = runtime.config.export_timeout_millis
+    try:
+        runtime.force_flush(timeout)
+    finally:
+        runtime.shutdown(timeout)
+    if collector is not None:
+        write_summary(collector, fields)
+
+
+def _apply_oidc() -> None:
+    token = fetch_oidc_token()
+    if token is None:
+        _log.warning(
+            "forgesight-github: OIDC requested but no runner id-token endpoint; "
+            "falling back to configured exporter auth"
+        )
+        return
+    os.environ.setdefault(OIDC_TOKEN_ENV, token)
+    _log.info("forgesight-github: obtained runner OIDC token (handed off via %s)", OIDC_TOKEN_ENV)
+
+
+def _summary_enabled() -> bool:
+    env = os.environ.get("FORGESIGHT_GITHUB_SUMMARY")
+    if env is not None:
+        return env.strip().lower() in ("1", "true", "yes", "on")
+    if "write_summary" in _installed_config:
+        return bool(_installed_config["write_summary"])
+    return True
+
+
+def _warn_not_ci() -> None:
+    global _warned_not_ci
+    if not _warned_not_ci:
+        _log.warning(
+            "forgesight-github: GITHUB_ACTIONS unset; bootstrap() falls back to plain configure()"
+        )
+        _warned_not_ci = True
+
+
+def install(config: dict[str, object] | None = None) -> bool:
+    """The ``forgesight.integrations`` entry point: stash config defaults for ``bootstrap()``."""
+    cfg = dict(config or {})
+    _installed_config.clear()
+    if not cfg.get("enabled", True):
+        return False
+    _installed_config.update(cfg)
+    return True
+
+
+def _reset_for_tests() -> None:
+    """Clear module state so tests don't leak the not-in-CI warning / installed config."""
+    global _warned_not_ci
+    _warned_not_ci = False
+    _installed_config.clear()

forgesight_github-0.1.0/src/forgesight_github/interceptor.py

@@ -0,0 +1,30 @@
+"""``GitHubMetadataInterceptor`` — attach CI correlation metadata to every record.
+
+``bootstrap()`` runs once at process start, before any run opens, so there is no live run
+to ``set_metadata`` on. Instead this interceptor merges the ``GITHUB_*`` metadata onto every
+record's attributes (FR-5) — so each span carries the repo / sha / PR / workflow / job and
+"spend on PR #1234" is a one-line backend query. Per-call metadata wins (``setdefault``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import replace
+from types import MappingProxyType
+
+from forgesight_api import Record
+
+
+class GitHubMetadataInterceptor:
+    """Merge fixed CI metadata into each record's attributes without overwriting per-call keys."""
+
+    def __init__(self, metadata: Mapping[str, str]) -> None:
+        self._metadata = dict(metadata)
+
+    def intercept(self, record: Record) -> Record | None:
+        if not self._metadata:
+            return record
+        attrs = dict(record.attributes)
+        for key, value in self._metadata.items():
+            attrs.setdefault(key, value)  # don't clobber metadata the caller set explicitly
+        return replace(record, attributes=MappingProxyType(attrs))

forgesight_github-0.1.0/src/forgesight_github/metadata.py

@@ -0,0 +1,73 @@
+"""``GITHUB_*`` → business-metadata mapping (FR-5), per the OTel VCS / CICD conventions.
+
+Pure: reads the runner environment and parses the PR number from the event payload JSON
+(the one field that is not a plain env var). Maps onto the current ``vcs.*`` / ``cicd.*``
+semconv, with ``agentforge.*`` extensions where no convention exists yet. Absent fields are
+omitted, never fabricated.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from collections.abc import Mapping, Sequence
+
+_log = logging.getLogger("forgesight.github")
+
+# GITHUB_* env var → telemetry attribute key (the documented capture set).
+GITHUB_ENV_MAP: Mapping[str, str] = {
+    "GITHUB_REPOSITORY": "vcs.repository.name",
+    "GITHUB_SHA": "vcs.ref.head.revision",
+    "GITHUB_REF": "vcs.ref.head.name",
+    "GITHUB_RUN_ID": "cicd.pipeline.run.id",
+    "GITHUB_RUN_ATTEMPT": "cicd.pipeline.run.attempt",
+    "GITHUB_WORKFLOW": "cicd.pipeline.name",
+    "GITHUB_JOB": "cicd.pipeline.task.name",
+    "GITHUB_ACTOR": "vcs.change.author",  # agentforge extension where no semconv exists
+    "GITHUB_EVENT_NAME": "cicd.pipeline.run.trigger",
+}
+PR_NUMBER_KEY = "vcs.change.id"
+
+
+def github_metadata(
+    *,
+    capture_env: Sequence[str] | None = None,
+    env: Mapping[str, str] | None = None,
+) -> dict[str, str]:
+    """Return the ``GITHUB_*`` → metadata mapping (repo, sha, ref, run id/attempt, workflow,
+    job, actor, event, PR number). ``capture_env`` restricts which ``GITHUB_*`` keys to read.
+    """
+    source = os.environ if env is None else env
+    allowed = set(capture_env) if capture_env is not None else None
+    out: dict[str, str] = {}
+    for env_key, attr in GITHUB_ENV_MAP.items():
+        if allowed is not None and env_key not in allowed:
+            continue
+        value = source.get(env_key)
+        if value:
+            out[attr] = value
+    pr = pr_number(source)
+    if pr is not None:
+        out[PR_NUMBER_KEY] = pr
+    return out
+
+
+def pr_number(env: Mapping[str, str]) -> str | None:
+    """PR number from the event payload JSON for ``pull_request*`` events, else ``None``."""
+    event_name = env.get("GITHUB_EVENT_NAME", "")
+    if not event_name.startswith("pull_request"):
+        return None
+    path = env.get("GITHUB_EVENT_PATH")
+    if not path or not os.path.exists(path):
+        return None
+    try:
+        with open(path, encoding="utf-8") as handle:
+            payload = json.load(handle)
+    except (OSError, ValueError):  # unreadable / malformed payload — don't fabricate
+        _log.warning("forgesight-github: could not read event payload at %s", path)
+        return None
+    candidate = payload.get("pull_request", {}).get("number")
+    if candidate is None:
+        candidate = payload.get("number")
+    return str(candidate) if candidate is not None else None

forgesight_github-0.1.0/src/forgesight_github/oidc.py

@@ -0,0 +1,48 @@
+"""Best-effort GitHub Actions OIDC id-token fetch (stdlib HTTP, no GitHub SDK).
+
+CI should authenticate to the collector with the runner's short-lived OIDC token rather than
+a static secret. The runner exposes a token endpoint via ``ACTIONS_ID_TOKEN_REQUEST_URL`` +
+``ACTIONS_ID_TOKEN_REQUEST_TOKEN`` (only when the job has ``id-token: write``). This fetch is
+best-effort: any failure returns ``None`` so ``bootstrap`` falls back to configured exporter
+auth and never fails the job (P6).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.parse
+import urllib.request
+from collections.abc import Mapping
+from typing import Any
+
+_log = logging.getLogger("forgesight.github")
+
+_URL_ENV = "ACTIONS_ID_TOKEN_REQUEST_URL"
+_TOKEN_ENV = "ACTIONS_ID_TOKEN_REQUEST_TOKEN"
+
+
+def fetch_oidc_token(
+    *, audience: str | None = None, env: Mapping[str, str] | None = None, timeout: float = 5.0
+) -> str | None:
+    """Return the runner OIDC id-token, or ``None`` if unavailable / on any error."""
+    import os
+
+    source = os.environ if env is None else env
+    url = source.get(_URL_ENV)
+    bearer = source.get(_TOKEN_ENV)
+    if not url or not bearer:
+        return None
+    if audience:
+        url = f"{url}&audience={urllib.parse.quote(audience)}"
+    request = urllib.request.Request(url, headers={"Authorization": f"Bearer {bearer}"})
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            payload: Any = json.loads(response.read().decode("utf-8"))
+    except Exception:  # network / parse / auth — best-effort, never raise (P6)
+        _log.warning(
+            "forgesight-github: OIDC token request failed; falling back to configured auth"
+        )
+        return None
+    value = payload.get("value") if isinstance(payload, dict) else None
+    return str(value) if value else None

forgesight_github-0.1.0/src/forgesight_github/summary.py

@@ -0,0 +1,90 @@
+"""Per-job run summary written to ``$GITHUB_STEP_SUMMARY`` on exit.
+
+A :class:`SummaryCollector` (an ``EventListener``) tallies the runs the SDK saw in the
+process — status, cost (summed from LLM calls), duration, tool-call count. On exit a markdown
+block is appended to the Actions job summary so the UI shows "run: ok · cost $0.12 · 38s · 3
+tool calls" with no author effort. The write is best-effort and never fails the job (P6).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Sequence
+
+from forgesight_api import EventType, LifecycleEvent, RunStatus
+
+_log = logging.getLogger("forgesight.github")
+
+DEFAULT_SUMMARY_METRICS: tuple[str, ...] = ("status", "cost_usd", "duration_ms", "n_tool_calls")
+_RUN_DONE = frozenset({EventType.RUN_COMPLETED, EventType.RUN_FAILED})
+_TOOL_DONE = frozenset({EventType.TOOL_EXECUTED, EventType.MCP_EXECUTED})
+
+
+class SummaryCollector:
+    """Tally runs / cost / tool-calls from lifecycle events (an ``EventListener``)."""
+
+    def __init__(self) -> None:
+        self.run_statuses: list[str] = []
+        self.total_duration_ms: float = 0.0
+        self.total_cost_usd: float = 0.0
+        self.n_tool_calls: int = 0
+
+    def on_event(self, event: LifecycleEvent) -> None:
+        record = event.record
+        if event.type in _RUN_DONE and record is not None:
+            self.run_statuses.append(record.status.value)
+            if record.duration_ms is not None:
+                self.total_duration_ms += record.duration_ms
+        elif event.type is EventType.LLM_EXECUTED and record is not None and record.llm is not None:
+            if record.llm.cost_usd is not None:
+                self.total_cost_usd += record.llm.cost_usd
+        elif event.type in _TOOL_DONE:
+            self.n_tool_calls += 1
+
+    # --- rendering --------------------------------------------------------
+    def status(self) -> str:
+        if not self.run_statuses:
+            return "no runs"
+        if all(s == RunStatus.OK.value for s in self.run_statuses):
+            return "ok"
+        return "error"
+
+    def values(self) -> dict[str, str]:
+        return {
+            "status": self.status(),
+            "cost_usd": f"${self.total_cost_usd:.4f}",
+            "duration_ms": f"{self.total_duration_ms:.0f}",
+            "n_tool_calls": str(self.n_tool_calls),
+            "runs": str(len(self.run_statuses)),
+        }
+
+
+def format_summary(collector: SummaryCollector, fields: Sequence[str]) -> str:
+    """Render the markdown block appended to the job summary."""
+    n = len(collector.run_statuses)
+    values = collector.values()
+    heading = f"### 🤖 ForgeSight agent run{'s' if n != 1 else ''}"
+    lines = [heading]
+    if n > 1:
+        lines.append(f"- **runs**: {n}")
+    for field in fields:
+        if field in values:
+            lines.append(f"- **{field}**: {values[field]}")
+    return "\n".join(lines) + "\n"
+
+
+def write_summary(
+    collector: SummaryCollector, fields: Sequence[str], *, path: str | None = None
+) -> bool:
+    """Append the summary to ``$GITHUB_STEP_SUMMARY`` (or ``path``). Never raises (P6)."""
+    target = path or os.environ.get("GITHUB_STEP_SUMMARY")
+    if not target:
+        return False
+    try:
+        with open(target, "a", encoding="utf-8") as handle:
+            handle.write(format_summary(collector, fields))
+    except OSError:  # a failed summary write must never fail the job (P6)
+        _log.warning("forgesight-github: could not write job summary to %s", target)
+        return False
+    return True

forgesight_github-0.1.0/tests/test_github.py

@@ -0,0 +1,416 @@
+"""Tests for the GitHub Actions integration: metadata, bootstrap, summary, OIDC, fallback."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from pathlib import Path
+
+import pytest
+
+from forgesight_api import (
+    EventType,
+    Kind,
+    LifecycleEvent,
+    LLMCall,
+    Record,
+    RunStatus,
+)
+from forgesight_core import InMemoryExporter, get_runtime, reset_runtime, telemetry
+from forgesight_github import (
+    GitHubMetadataInterceptor,
+    SummaryCollector,
+    bootstrap,
+    fetch_oidc_token,
+    format_summary,
+    github_metadata,
+    in_github_actions,
+    install,
+    pr_number,
+    run_exit_hook,
+    write_summary,
+)
+from forgesight_github.bootstrap import _reset_for_tests
+
+CI_ENV = {
+    "GITHUB_ACTIONS": "true",
+    "GITHUB_REPOSITORY": "acme/agents",
+    "GITHUB_SHA": "abc123",
+    "GITHUB_REF": "refs/pull/42/merge",
+    "GITHUB_RUN_ID": "9999",
+    "GITHUB_RUN_ATTEMPT": "2",
+    "GITHUB_WORKFLOW": "review",
+    "GITHUB_JOB": "pr-review",
+    "GITHUB_ACTOR": "octocat",
+    "GITHUB_EVENT_NAME": "pull_request",
+}
+
+
+@pytest.fixture(autouse=True)
+def _clean(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]:
+    # CI itself sets GITHUB_* / GITHUB_STEP_SUMMARY — scrub the ambient env so tests are
+    # deterministic whether or not they run inside GitHub Actions.
+    for key in (
+        *CI_ENV,
+        "GITHUB_EVENT_PATH",
+        "GITHUB_STEP_SUMMARY",
+        "FORGESIGHT_GITHUB_SUMMARY",
+        "FORGESIGHT_OTLP_TOKEN",
+        "ACTIONS_ID_TOKEN_REQUEST_URL",
+        "ACTIONS_ID_TOKEN_REQUEST_TOKEN",
+    ):
+        monkeypatch.delenv(key, raising=False)
+    _reset_for_tests()
+    yield
+    reset_runtime()
+    _reset_for_tests()
+
+
+def _apply_env(monkeypatch: pytest.MonkeyPatch, env: dict[str, str]) -> None:
+    for key in (*CI_ENV, "GITHUB_EVENT_PATH", "GITHUB_STEP_SUMMARY"):
+        monkeypatch.delenv(key, raising=False)
+    for key, value in env.items():
+        monkeypatch.setenv(key, value)
+
+
+# --- github_metadata ----------------------------------------------------------
+def test_metadata_maps_all_github_vars(monkeypatch: pytest.MonkeyPatch) -> None:
+    _apply_env(monkeypatch, CI_ENV)
+    meta = github_metadata()
+    assert meta["vcs.repository.name"] == "acme/agents"
+    assert meta["vcs.ref.head.revision"] == "abc123"
+    assert meta["vcs.ref.head.name"] == "refs/pull/42/merge"
+    assert meta["cicd.pipeline.run.id"] == "9999"
+    assert meta["cicd.pipeline.run.attempt"] == "2"
+    assert meta["cicd.pipeline.name"] == "review"
+    assert meta["cicd.pipeline.task.name"] == "pr-review"
+    assert meta["vcs.change.author"] == "octocat"
+    assert meta["cicd.pipeline.run.trigger"] == "pull_request"
+
+
+def test_pr_number_from_event_payload(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    event = tmp_path / "event.json"
+    event.write_text(json.dumps({"pull_request": {"number": 42}}))
+    _apply_env(monkeypatch, {**CI_ENV, "GITHUB_EVENT_PATH": str(event)})
+    assert github_metadata()["vcs.change.id"] == "42"
+    assert pr_number(dict(__import__("os").environ)) == "42"
+
+
+def test_pr_number_top_level_number(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    event = tmp_path / "event.json"
+    event.write_text(json.dumps({"number": 7}))
+    _apply_env(monkeypatch, {**CI_ENV, "GITHUB_EVENT_PATH": str(event)})
+    assert github_metadata()["vcs.change.id"] == "7"
+
+
+def test_pr_number_absent_for_push(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    event = tmp_path / "event.json"
+    event.write_text(json.dumps({"pull_request": {"number": 42}}))
+    _apply_env(
+        monkeypatch,
+        {**CI_ENV, "GITHUB_EVENT_NAME": "push", "GITHUB_EVENT_PATH": str(event)},
+    )
+    assert "vcs.change.id" not in github_metadata()  # not a PR event ⇒ not fabricated
+
+
+def test_pr_number_missing_payload_file(monkeypatch: pytest.MonkeyPatch) -> None:
+    _apply_env(monkeypatch, {**CI_ENV, "GITHUB_EVENT_PATH": "/nonexistent/event.json"})
+    assert "vcs.change.id" not in github_metadata()
+
+
+def test_pr_number_malformed_payload(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    event = tmp_path / "event.json"
+    event.write_text("{not json")
+    _apply_env(monkeypatch, {**CI_ENV, "GITHUB_EVENT_PATH": str(event)})
+    assert "vcs.change.id" not in github_metadata()
+
+
+def test_capture_env_restriction(monkeypatch: pytest.MonkeyPatch) -> None:
+    _apply_env(monkeypatch, CI_ENV)
+    meta = github_metadata(capture_env=["GITHUB_REPOSITORY", "GITHUB_SHA"])
+    assert set(meta) == {"vcs.repository.name", "vcs.ref.head.revision"}  # actor dropped
+
+
+def test_metadata_via_explicit_env() -> None:
+    meta = github_metadata(env={"GITHUB_REPOSITORY": "x/y"})
+    assert meta == {"vcs.repository.name": "x/y"}
+
+
+# --- interceptor --------------------------------------------------------------
+def _record(**attrs: object) -> Record:
+    from types import MappingProxyType
+
+    return Record(
+        kind=Kind.AGENT,
+        run_id="r",
+        trace_id="4bf92f3577b34da6a3ce929d0e0e4736",
+        span_id="00f067aa0ba902b7",
+        parent_span_id=None,
+        name="c",
+        status=RunStatus.OK,
+        start_unix_nanos=1,
+        end_unix_nanos=2,
+        attributes=MappingProxyType(dict(attrs)),
+    )
+
+
+def test_interceptor_merges_without_clobbering() -> None:
+    interceptor = GitHubMetadataInterceptor({"vcs.repository.name": "acme/agents", "team": "ci"})
+    out = interceptor.intercept(_record(team="explicit"))
+    assert out is not None
+    assert out.attributes["vcs.repository.name"] == "acme/agents"  # added
+    assert out.attributes["team"] == "explicit"  # per-call metadata wins
+
+
+def test_interceptor_empty_is_passthrough() -> None:
+    record = _record()
+    assert GitHubMetadataInterceptor({}).intercept(record) is record
+
+
+# --- bootstrap ----------------------------------------------------------------
+def test_bootstrap_attaches_metadata_to_runs(monkeypatch: pytest.MonkeyPatch) -> None:
+    _apply_env(monkeypatch, CI_ENV)
+    bootstrap(write_summary=False, _register_exit=False)
+    exporter = InMemoryExporter()
+    runtime = get_runtime()
+    runtime.add_exporter(exporter)
+    with telemetry.agent_run("classifier"):
+        pass
+    runtime.force_flush()
+    run = next(r for r in exporter.records if r.kind is Kind.AGENT)
+    assert run.attributes["vcs.repository.name"] == "acme/agents"
+    assert run.attributes["cicd.pipeline.name"] == "review"
+
+
+def test_bootstrap_extra_metadata(monkeypatch: pytest.MonkeyPatch) -> None:
+    _apply_env(monkeypatch, CI_ENV)
+    bootstrap(write_summary=False, extra_metadata={"team": "payments"}, _register_exit=False)
+    exporter = InMemoryExporter()
+    get_runtime().add_exporter(exporter)
+    with telemetry.agent_run("c"):
+        pass
+    get_runtime().force_flush()
+    run = next(r for r in exporter.records if r.kind is Kind.AGENT)
+    assert run.attributes["team"] == "payments"
+
+
+def test_bootstrap_not_in_ci_warns_once(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    _apply_env(monkeypatch, {})  # GITHUB_ACTIONS unset
+    assert in_github_actions() is False
+    with caplog.at_level("WARNING"):
+        bootstrap(write_summary=False, _register_exit=False)
+        bootstrap(write_summary=False, _register_exit=False)
+    warnings = [r for r in caplog.records if "falls back to plain configure" in r.message]
+    assert len(warnings) == 1  # warned once, not twice
+
+
+def test_bootstrap_not_in_ci_no_metadata(monkeypatch: pytest.MonkeyPatch) -> None:
+    _apply_env(monkeypatch, {"GITHUB_REPOSITORY": "x/y"})  # set but GITHUB_ACTIONS unset
+    bootstrap(write_summary=False, _register_exit=False)
+    exporter = InMemoryExporter()
+    get_runtime().add_exporter(exporter)
+    with telemetry.agent_run("c"):
+        pass
+    get_runtime().force_flush()
+    run = next(r for r in exporter.records if r.kind is Kind.AGENT)
+    assert "vcs.repository.name" not in run.attributes  # no CI metadata outside CI
+
+
+# --- summary collector --------------------------------------------------------
+def _event(event_type: EventType, record: Record | None = None) -> LifecycleEvent:
+    return LifecycleEvent(type=event_type, run_id="r", unix_nanos=1, record=record)
+
+
+def test_summary_collector_tallies() -> None:
+    collector = SummaryCollector()
+    llm = Record(
+        kind=Kind.LLM,
+        run_id="r",
+        trace_id="t",
+        span_id="s",
+        parent_span_id=None,
+        name="m",
+        status=RunStatus.OK,
+        start_unix_nanos=0,
+        end_unix_nanos=1_000_000,
+        llm=LLMCall(provider="anthropic", request_model="m", cost_usd=0.05),
+    )
+    run = _record()
+    collector.on_event(_event(EventType.LLM_EXECUTED, llm))
+    collector.on_event(_event(EventType.TOOL_EXECUTED))
+    collector.on_event(_event(EventType.MCP_EXECUTED))
+    collector.on_event(_event(EventType.RUN_COMPLETED, run))
+    assert collector.total_cost_usd == 0.05
+    assert collector.n_tool_calls == 2
+    assert collector.status() == "ok"
+
+
+def test_summary_status_error_on_failed_run() -> None:
+    collector = SummaryCollector()
+    failed = Record(
+        kind=Kind.AGENT,
+        run_id="r",
+        trace_id="t",
+        span_id="s",
+        parent_span_id=None,
+        name="c",
+        status=RunStatus.ERROR,
+        start_unix_nanos=1,
+        end_unix_nanos=2,
+    )
+    collector.on_event(_event(EventType.RUN_FAILED, failed))
+    assert collector.status() == "error"
+
+
+def test_summary_status_no_runs() -> None:
+    assert SummaryCollector().status() == "no runs"
+
+
+def test_format_summary_single_and_multi() -> None:
+    collector = SummaryCollector()
+    collector.on_event(_event(EventType.RUN_COMPLETED, _record()))
+    single = format_summary(collector, DEFAULT := ("status", "cost_usd", "n_tool_calls"))
+    assert "### 🤖 ForgeSight agent run" in single
+    assert "- **status**: ok" in single
+    collector.on_event(_event(EventType.RUN_COMPLETED, _record()))
+    multi = format_summary(collector, DEFAULT)
+    assert "runs" in multi  # rollup shows run count for multi-run jobs
+
+
+def test_write_summary_to_file(tmp_path: Path) -> None:
+    collector = SummaryCollector()
+    collector.on_event(_event(EventType.RUN_COMPLETED, _record()))
+    summary = tmp_path / "summary.md"
+    assert write_summary(collector, ("status", "cost_usd"), path=str(summary)) is True
+    assert "status" in summary.read_text()
+
+
+def test_write_summary_no_target_is_false() -> None:
+    assert write_summary(SummaryCollector(), ("status",), path=None) is False
+
+
+def test_write_summary_failure_is_isolated(tmp_path: Path) -> None:
+    # a directory path can't be opened for append ⇒ returns False, never raises (P6)
+    assert write_summary(SummaryCollector(), ("status",), path=str(tmp_path)) is False
+
+
+# --- exit hook ----------------------------------------------------------------
+def test_run_exit_hook_flushes_and_writes_summary(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    summary = tmp_path / "step_summary.md"
+    _apply_env(monkeypatch, {**CI_ENV, "GITHUB_STEP_SUMMARY": str(summary)})
+    bootstrap(_register_exit=False)
+    exporter = InMemoryExporter()
+    runtime = get_runtime()
+    runtime.add_exporter(exporter)
+    collector = next(c for c in runtime.listeners if isinstance(c, SummaryCollector))
+    with (
+        telemetry.agent_run("classifier"),
+        telemetry.current_run().llm_call("anthropic", "m") as call,
+    ):  # type: ignore[union-attr]
+        call.record_usage(input=10, output=5)
+    run_exit_hook(runtime, collector, ("status", "cost_usd", "n_tool_calls"))
+    assert summary.exists()
+    assert "ForgeSight agent run" in summary.read_text()
+
+
+def test_bootstrap_summary_disabled_via_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    _apply_env(monkeypatch, {**CI_ENV, "FORGESIGHT_GITHUB_SUMMARY": "false"})
+    bootstrap(_register_exit=False)
+    assert not any(isinstance(c, SummaryCollector) for c in get_runtime().listeners)
+
+
+# --- OIDC ---------------------------------------------------------------------
+def test_oidc_absent_endpoint_returns_none() -> None:
+    assert fetch_oidc_token(env={}) is None
+
+
+def test_oidc_fetch_success(monkeypatch: pytest.MonkeyPatch) -> None:
+    import urllib.request
+
+    class _Resp:
+        def __enter__(self) -> _Resp:
+            return self
+
+        def __exit__(self, *a: object) -> None:
+            return None
+
+        def read(self) -> bytes:
+            return json.dumps({"value": "tok-123"}).encode()
+
+    monkeypatch.setattr(urllib.request, "urlopen", lambda *a, **k: _Resp())
+    token = fetch_oidc_token(
+        audience="collector",
+        env={
+            "ACTIONS_ID_TOKEN_REQUEST_URL": "https://runner/token?x=1",
+            "ACTIONS_ID_TOKEN_REQUEST_TOKEN": "bearer",
+        },
+    )
+    assert token == "tok-123"
+
+
+def test_oidc_fetch_error_returns_none(monkeypatch: pytest.MonkeyPatch) -> None:
+    import urllib.request
+
+    def _boom(*a: object, **k: object) -> object:
+        raise OSError("network down")
+
+    monkeypatch.setattr(urllib.request, "urlopen", _boom)
+    token = fetch_oidc_token(
+        env={
+            "ACTIONS_ID_TOKEN_REQUEST_URL": "https://runner/token",
+            "ACTIONS_ID_TOKEN_REQUEST_TOKEN": "bearer",
+        }
+    )
+    assert token is None
+
+
+def test_bootstrap_oidc_fallback_when_unavailable(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    _apply_env(monkeypatch, CI_ENV)  # no id-token endpoint
+    with caplog.at_level("WARNING"):
+        bootstrap(write_summary=False, oidc=True, _register_exit=False)
+    assert any("OIDC requested but no runner id-token" in r.message for r in caplog.records)
+
+
+# --- install ------------------------------------------------------------------
+def test_install_stashes_config_and_summary_default(monkeypatch: pytest.MonkeyPatch) -> None:
+    _apply_env(monkeypatch, CI_ENV)
+    assert install({"enabled": True, "write_summary": False}) is True
+    bootstrap(_register_exit=False)  # write_summary default reads installed config ⇒ off
+    assert not any(isinstance(c, SummaryCollector) for c in get_runtime().listeners)
+
+
+def test_install_disabled_returns_false() -> None:
+    assert install({"enabled": False}) is False
+
+
+def test_bootstrap_registers_exit_hook(monkeypatch: pytest.MonkeyPatch) -> None:
+    import sys
+
+    _apply_env(monkeypatch, CI_ENV)
+    registered: list[object] = []
+    bs = sys.modules["forgesight_github.bootstrap"]  # function shadows submodule on the package
+
+    monkeypatch.setattr(bs.atexit, "register", lambda fn, *a: registered.append((fn, a)))
+    bootstrap(write_summary=False)  # _register_exit defaults True
+    assert registered
+    assert registered[0][0] is run_exit_hook
+
+
+def test_bootstrap_oidc_success_sets_token(monkeypatch: pytest.MonkeyPatch) -> None:
+    import os
+    import sys
+
+    _apply_env(monkeypatch, CI_ENV)
+    monkeypatch.delenv("FORGESIGHT_OTLP_TOKEN", raising=False)
+    bs = sys.modules["forgesight_github.bootstrap"]
+
+    monkeypatch.setattr(bs, "fetch_oidc_token", lambda: "tok-xyz")
+    bootstrap(write_summary=False, oidc=True, _register_exit=False)
+    assert os.environ["FORGESIGHT_OTLP_TOKEN"] == "tok-xyz"
+    monkeypatch.delenv("FORGESIGHT_OTLP_TOKEN", raising=False)