firekeep-client 1.7.2__tar.gz → 1.8.1__tar.gz

{firekeep_client-1.7.2/firekeep_client.egg-info → firekeep_client-1.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firekeep-client
-Version: 1.7.2
+Version: 1.8.1
 Summary: Client for Firekeep, the self-hosted operating layer for connected AI agents.
 License-Expression: LicenseRef-Firekeep-BUSL-1.1
 Project-URL: Homepage, https://firekeep.ai
@@ -57,9 +57,9 @@ an absent registry is seeded with both (default-on), `firekeep dex remove` is
 the off-switch, and removals stick across updates.
 
 **Firekeep is self-hosted — this package needs a server to talk to.** A person
-or team runs its own server, with per-key authentication. Current server images
-target `linux/amd64`: use an x86-64 Linux host, or Docker Desktop with amd64
-container support on Windows or Mac. There is no hosted endpoint. Server install:
+or team runs its own server, with per-key authentication. Server images target
+`linux/amd64` and, for releases after v1.6.2, `linux/arm64`: use an x86-64 or
+ARM64 Linux host, or Docker Desktop on Windows or Mac. There is no hosted endpoint. Server install:
 [firekeep.ai/docs.html](https://firekeep.ai/docs.html#server).
 
 ## Install

{firekeep_client-1.7.2 → firekeep_client-1.8.1}/README.md

@@ -30,9 +30,9 @@ an absent registry is seeded with both (default-on), `firekeep dex remove` is
 the off-switch, and removals stick across updates.
 
 **Firekeep is self-hosted — this package needs a server to talk to.** A person
-or team runs its own server, with per-key authentication. Current server images
-target `linux/amd64`: use an x86-64 Linux host, or Docker Desktop with amd64
-container support on Windows or Mac. There is no hosted endpoint. Server install:
+or team runs its own server, with per-key authentication. Server images target
+`linux/amd64` and, for releases after v1.6.2, `linux/arm64`: use an x86-64 or
+ARM64 Linux host, or Docker Desktop on Windows or Mac. There is no hosted endpoint. Server install:
 [firekeep.ai/docs.html](https://firekeep.ai/docs.html#server).
 
 ## Install

{firekeep_client-1.7.2 → firekeep_client-1.8.1}/firekeep_client/__init__.py

@@ -9,4 +9,4 @@ versions without a verdict (`_check_versions`) and judges staleness against the
 release manifest instead (`_check_client_version`).
 """
 
-__version__ = "1.7.2"
+__version__ = "1.8.1"

{firekeep_client-1.7.2 → firekeep_client-1.8.1}/firekeep_client/adapters/codex.py

@@ -46,6 +46,9 @@ def _toml_block(venv_bin: Path) -> str:
         # TOML literal (single-quoted) string: no escape processing -> Windows backslashes safe.
         lines.append(f"command = '{cmd}'")
         lines.append(f"args = [{arglist}]")
+        # Codex clears the env of stdio MCP servers; forward what Firekeep
+        # Studio sets per run (spec 2026-10-11 §7.2).
+        lines.append('env_vars = ["FIREKEEP_SESSION_REPORT_FILE"]')
         lines.append("")
     return "\n".join(lines).rstrip()
 

{firekeep_client-1.7.2 → firekeep_client-1.8.1}/firekeep_client/childenv.py

@@ -65,7 +65,7 @@ _KIT = frozenset({
     "FIREKEEP_SHIM_DEBUG", "FIREKEEP_NO_JOB_OBJECT",
     "FIREKEEP_REPORT_CONSENT", "FIREKEEP_REPORT_DIR",
     "FIREKEEP_FAILURE_REPORT", "FIREKEEP_NO_FAILURE_REPORT",
-    "FIREKEEP_SESSION_ID", "NEXUS_AGENT_ID",
+    "FIREKEEP_SESSION_ID", "FIREKEEP_SESSION_REPORT_FILE", "NEXUS_AGENT_ID",
     # hook-side knobs the client modules a child imports may consult
     "FIREKEEP_AGENT_GOAL", "FIREKEEP_BRIEFING", "FIREKEEP_NO_AUTO_UPDATE",
     "FIREKEEP_NO_AUTO_SYNC", "FIREKEEP_NO_AUTO_INDEX", "FIREKEEP_NO_AUTO_NIGHTSHIFT",
@@ -118,6 +118,9 @@ NOT_FORWARDED: frozenset[str] = frozenset({
     "FIREKEEP_SIGNING_KEY",
     # An enrolment code is a credential; only `firekeep join` reads it.
     "FIREKEEP_JOIN",
+    # The bootstrap's fresh-install answer belongs to the install hand-off
+    # alone; a child seeing it could count a non-install as a new install.
+    "FIREKEEP_INSTALL_REPORT_CONSENT",
     # Set by the gateway from ~/.firekeep/config for symdex alone; a parent's
     # copy (stale shell export, another member's key) is never authoritative.
     "FIREKEEP_CORTEX_URL", "FIREKEEP_CLIENT_API_KEY", "FIREKEEP_CORTEX_CA",

{firekeep_client-1.7.2 → firekeep_client-1.8.1}/firekeep_client/cli.py

@@ -87,6 +87,44 @@ def cmd_version(args) -> int:
     return 0
 
 
+# --- whoami: identity facts for Studio 0.5 -----------------------------------
+
+def cmd_whoami(args) -> int:
+    """Identity facts a local client (Firekeep Studio) needs — never the API key.
+
+    Studio must not read ~/.firekeep/config itself because the file holds the
+    key, so this is the one place it learns the agent id (spec 2026-10-11 §7.1).
+    """
+    cfg = None
+    try:
+        cfg = resolver.load_config(_config_path())
+    except resolver.ConfigMigrationConflict as exc:
+        print(f"firekeep: {exc}", file=sys.stderr)
+        return 3
+    except resolver.ConfigError:
+        cfg = None
+    agent: str | None = None
+    if cfg is not None:
+        try:
+            agent = resolver.agent_id(cfg)
+        except resolver.ConfigError:
+            agent = None
+    if agent == wizard.PLACEHOLDER_AGENT_ID:
+        agent = None  # the installer skeleton value is "unconfigured"
+    facts = {
+        "agent_id": agent,
+        "kit_version": __version__,
+        "personal_mode": bool(resolver.is_bypassed()),
+        "server_configured": bool(cfg is not None and wizard._already_connected(cfg)),
+    }
+    if getattr(args, "json", False):
+        print(json.dumps(facts))
+    else:
+        for key, value in facts.items():
+            print(f"{key}: {value}")
+    return 0 if agent else 1
+
+
 # --- install: venv, pip, ~/.firekeep bootstrap, adapter render -----------------
 
 # `configured = false` is the sentinel that makes "never set up" a REPRESENTABLE
@@ -277,7 +315,18 @@ def _venv_has_pip(venv: Path) -> bool:
     return True
 
 
-def _create_venv(venv: Path) -> None:
+def _is_live_venv(home: Path, venv: Path) -> bool:
+    """True when the `current` link resolves to `venv` — the install every hook runs."""
+    current = home / CURRENT_LINK_NAME
+    if not os.path.lexists(current):
+        return False
+    try:
+        return os.path.normcase(os.path.realpath(current)) == os.path.normcase(os.path.realpath(venv))
+    except OSError:
+        return False
+
+
+def _create_venv(venv: Path, home: Path) -> None:
     if _venv_bin(venv).exists():
         if _venv_has_pip(venv):
             return
@@ -285,6 +334,16 @@ def _create_venv(venv: Path) -> None:
         # bootstrap that died between `uv venv` and `uv pip install` leaves exactly this.
         # Short-circuiting here used to crash the checkout install later in _pip_install;
         # rebuild in place instead (--clear reprovisions, pip included via ensurepip).
+        #
+        # Never the LIVE venv, though: a healthy bootstrap venv is pip-less too, and a
+        # checkout whose version matches the installed one lands here. On 2026-10-12 the
+        # --clear died on executables held by running sessions, leaving Scripts/ without
+        # a stdlib, and every hook on the machine failed until the venv was rebuilt.
+        if _is_live_venv(home, venv):
+            raise RuntimeError(
+                f"{venv} is the live install (`current` points at it) and has no pip; "
+                "rebuilding it would break every running session. Bump the checkout's "
+                "version, or run `firekeep update` to repair the installed release.")
         _run([sys.executable, "-m", "venv", "--clear", str(venv)])
         return
     _run([sys.executable, "-m", "venv", str(venv)])
@@ -402,7 +461,7 @@ def _apply_flags(cfg, args) -> bool:
         # overwrite an ALREADY-recorded answer — a re-render, an update's
         # re-exec, or a non-interactive run relaying a pre-set env must not
         # rewrite a "no" a human already gave.
-        report.record_consent(cfg, pre == "1")
+        report.record_consent(cfg, pre == "1", installs=report.installs_env_answer())
         touched = True
     return touched
 
@@ -555,7 +614,7 @@ def cmd_install(args) -> int:
             # Checkout install: provision a fresh versioned venv at its FINAL path
             # (never moved — venvs aren't relocatable) and flip `current` to it below.
             venv = home / VENVS_DIR_NAME / _kit_version(kit)
-            _create_venv(venv)
+            _create_venv(venv, home)
         else:
             venv = Path(sys.executable).resolve().parent.parent
         python = _venv_python(venv)
@@ -651,8 +710,9 @@ def cmd_install(args) -> int:
         print(f"firekeep: install failed at '{step}': {exc}", file=sys.stderr)
         return 1
 
+    report.milestone("installed")
     print(f"firekeep: installed into {home}")
-    registered = "firekeep (gateway: memory, sessions, relay, monitoring, code, decisions)"
+    registered ="firekeep (gateway: memory, sessions, relay, monitoring, code, decisions)"
     print(f"firekeep: registered MCP servers: {registered}")
     print("firekeep: tip — `/personal` (Claude) or `firekeep personal` toggles a private "
           "session where Firekeep is fully bypassed (nothing logged/recalled); it "
@@ -959,6 +1019,8 @@ def _check_health(cfg) -> list[tuple[str, str, str]]:
     else:
         for svc, category in failures:
             report.emit("connectivity", svc, error=category, cfg=cfg)
+    if not failures:
+        report.milestone("connected", cfg=cfg)
     return out
 
 
@@ -3147,6 +3209,10 @@ def _build_parser() -> argparse.ArgumentParser:
     ver = sub.add_parser("version", help="print client version + skew status")
     ver.set_defaults(func=cmd_version)
 
+    who = sub.add_parser("whoami", help="print this machine's Firekeep identity (never the key)")
+    who.add_argument("--json", action="store_true", help="one line of JSON for programs")
+    who.set_defaults(func=cmd_whoami)
+
     inst = sub.add_parser("install", help="install/refresh the client kit")
     # An unset runtime prepares every shipped adapter. Explicit --runtime (or the
     # bootstrap's FIREKEEP_RUNTIME) remains available for a targeted re-render.

{firekeep_client-1.7.2 → firekeep_client-1.8.1}/firekeep_client/gateway.py

@@ -66,6 +66,15 @@ TOOLSET_PRESETS: dict[str, frozenset[str]] = {
         "ctx_abandon_session", "ctx_list_sessions", "ctx_resume_session",
         "ctx_get_shadow",
     }),
+    # Firekeep Studio's Keep panel and per-turn receipts (Studio 0.5, spec
+    # 2026-10-11 §7.1). Reads plus knowledge feedback only: Studio never
+    # starts, updates or completes a Keep session — the agent owns those.
+    "studio": frozenset({
+        "memory_recall", "memory_feedback",
+        "skill_list", "skill_recall",
+        "relay_who_is_online", "relay_read",
+        "ctx_list_sessions", "replay_timeline", "corpus_sources",
+    }),
 }
 
 # A preset that narrows the tool surface also narrows the handshake text: the

{firekeep_client-1.7.2 → firekeep_client-1.8.1}/firekeep_client/hooks/session_start.py

@@ -127,6 +127,8 @@ def run(payload: dict) -> dict:
             )
             if isinstance(data, dict) and data.get("rendered"):
                 rendered = data["rendered"]
+                # Once per machine; the flush below sends it.
+                report.milestone("connected", cfg=cfg, flush_now=False)
             # Stash the server-minted briefing_id so the bridge shim can inject it
             # into a ctx_start_session call the agent makes without it — closing the
             # briefing_id -> session_id A/B join mechanically. (The stale-id clear

{firekeep_client-1.7.2 → firekeep_client-1.8.1}/firekeep_client/promptrecall.py

@@ -286,6 +286,15 @@ def remember(agent: str, ids: list[str]) -> None:
         hooklog.log_failure(_HOOK, f"proactive recall dedupe write failed: {e}")
 
 
+def _keep_session(cfg) -> str | None:
+    """The agent's current Keep session, so the pushed recall is attributed to
+    it in replay (Studio 0.5 receipts, spec §7.2). Best-effort: None on any error."""
+    try:
+        return state.current_session_id(resolver.agent_id(cfg))
+    except Exception:  # noqa: BLE001
+        return None
+
+
 def recall(cfg, prompt: str) -> list:
     """POST the prompt to cortex `/memory/recall` and return its `sources`.
 
@@ -309,12 +318,15 @@ def recall(cfg, prompt: str) -> list:
     memory filed under `infrastructure` and friends — 146 of them on the live store,
     which is the defect `docs/guides/cortex-design-decisions.md` records.
 
+    It carries the agent's current Keep session (`X-Session-Id`) so the recall shows
+    in that session's replay timeline.
+
     Returns [] for a DEGRADED response (vector search down, results graph-only).
     Same call as Bridge makes: the floor below is calibrated on cosine, and a
     graph-only set is a different scale, so pushing it would be pushing noise the
     threshold cannot judge.
     """
-    ep = resolver.resolve("cortex", cfg=cfg)
+    ep = resolver.resolve("cortex", cfg=cfg, session_id=_keep_session(cfg))
     body = {
         "task": prompt[:MAX_TASK_CHARS],
         "top_k": TOP_K,

{firekeep_client-1.7.2 → firekeep_client-1.8.1}/firekeep_client/report.py

@@ -72,6 +72,15 @@ _STAGES_BY_KIND = {
     "runtime": RUNTIME_STAGES,
 }
 
+# Install milestones: the success half of the funnel, so downloads can be read
+# against installs that worked. NOT a failure kind — its own consent key
+# ([report] installs), its own once-per-machine marker, no `error` field, and
+# the collector logs it apart from failures (never mailed, never pulled into
+# Sentinel). installed = `firekeep install` completed; connected = the first
+# time this machine reached its Keep (doctor all-green or a served briefing).
+MILESTONE_KIND = "milestone"
+MILESTONE_STAGES = ("installed", "connected")
+
 _ERRNO_MAP = {
     _errno.EACCES: "permission-denied",
     _errno.EPERM: "permission-denied",
@@ -184,15 +193,43 @@ def build_event(kind, stage, *, error=None, exc=None, exit_code=None,
         return None
 
 
+def build_milestone(stage) -> dict | None:
+    """Validated milestone event, or None. Same closed fields as a failure
+    minus `error` and every tagged-union extra."""
+    try:
+        if stage not in MILESTONE_STAGES:
+            return None
+        os_family = detect_os()
+        if os_family not in OS_FAMILIES:
+            return None
+        from firekeep_client import __version__
+        return {
+            "id": uuid.uuid4().hex,
+            "kind": MILESTONE_KIND,
+            "stage": stage,
+            "os": os_family,
+            "arch": detect_arch(),
+            "client": __version__,
+            "py": py_bucket(),
+        }
+    except Exception:  # noqa: BLE001
+        return None
+
+
 _FALSEY = ("", "0", "false", "no", "off")
 
+# One question, two recorded answers ([report] failures + [report] installs).
+# Machines enrolled under the earlier failures-only wording keep `installs`
+# absent and so never send a milestone: their consent is not widened after
+# the fact. The bootstraps (install.sh / install.ps1) carry the same scope.
 CONSENT_PROMPT = (
-    "Send anonymous failure reports to firekeep.ai? When an install step fails, a\n"
-    "connection to your own Keep fails, or a Firekeep background task errors,\n"
-    "Firekeep sends category codes only — what failed, the error class, OS family,\n"
-    "versions. Never paths, messages, addresses, or any persistent device, account\n"
-    "or session identifier. Ongoing until you turn it off\n"
-    "([report] failures = false). [Y/n] "
+    "Send anonymous reports to firekeep.ai? Once when this install succeeds and\n"
+    "first reaches your Keep, and whenever an install step fails, a connection to\n"
+    "your own Keep fails, or a Firekeep background task errors, Firekeep sends\n"
+    "category codes only — what happened, the error class, OS family, versions.\n"
+    "Never paths, messages, addresses, or any persistent device, account or\n"
+    "session identifier. Ongoing until you turn it off\n"
+    "([report] failures = false, [report] installs = false). [Y/n] "
 )
 
 
@@ -216,6 +253,23 @@ def is_enabled(cfg=None) -> bool:
         return False
 
 
+def milestones_enabled(cfg=None) -> bool:
+    """Consent gate for install milestones. Stricter than is_enabled: only a
+    recorded `[report] installs = true` counts — there is deliberately no env
+    opt-in, so CI runs that set FIREKEEP_FAILURE_REPORT=1 never count as
+    installs. The failure opt-out and personal mode silence it too."""
+    try:
+        if os.environ.get("FIREKEEP_NO_FAILURE_REPORT", "").strip().lower() not in _FALSEY:
+            return False
+        if resolver.is_bypassed():
+            return False
+        if cfg is None:
+            cfg = resolver.load_config()
+        return cfg.get("report", "installs", fallback="").strip().lower() == "true"
+    except Exception:  # noqa: BLE001 — any doubt means OFF (fail closed)
+        return False
+
+
 def has_answer(cfg) -> bool:
     try:
         return cfg.get("report", "failures", fallback="").strip() != ""
@@ -223,15 +277,38 @@ def has_answer(cfg) -> bool:
         return False
 
 
-def record_consent(cfg, value: bool) -> None:
+def record_consent(cfg, value: bool, *, installs: bool | None = None) -> None:
+    """Record the failures answer, and the installs answer only when the
+    human was shown wording that covers milestones (installs is not None)."""
     try:
         if not cfg.has_section("report"):
             cfg.add_section("report")
         cfg.set("report", "failures", "true" if value else "false")
+        if installs is not None:
+            cfg.set("report", "installs", "true" if installs else "false")
     except Exception:  # noqa: BLE001
         pass
 
 
+# Set when THIS process recorded an answer from a human at the prompt. With
+# the bootstrap's relayed answer it defines a fresh install: the prompt only
+# ever appears on a machine with no recorded answer, so an update, a re-render
+# or a later opt-in never counts as a new install.
+_ANSWERED_HERE = False
+
+
+def _fresh_install_consented() -> bool:
+    return installs_env_answer() is True or _ANSWERED_HERE
+
+
+def installs_env_answer() -> bool | None:
+    """The bootstrap relays its prompt's answer in FIREKEEP_INSTALL_REPORT_CONSENT,
+    set ONLY when a human answered the milestone-covering wording — never by
+    FIREKEEP_FAILURE_REPORT or an update re-exec. None = not shown that prompt."""
+    pre = os.environ.get("FIREKEEP_INSTALL_REPORT_CONSENT", "").strip()
+    return (pre == "1") if pre in ("0", "1") else None
+
+
 def ask_consent(cfg) -> bool:
     """Ask once; record only a real answer. EOF and Ctrl-C record NOTHING —
     deliberately not wizard.console_ask, whose EOF-takes-the-default would
@@ -242,7 +319,7 @@ def ask_consent(cfg) -> bool:
             return False
         pre = os.environ.get("FIREKEEP_REPORT_CONSENT", "").strip()
         if pre in ("0", "1"):
-            record_consent(cfg, pre == "1")
+            record_consent(cfg, pre == "1", installs=installs_env_answer())
             return True
         if not sys.stdin.isatty():
             return False
@@ -256,7 +333,10 @@ def ask_consent(cfg) -> bool:
         except (EOFError, KeyboardInterrupt):
             print()
             return False
-        record_consent(cfg, answer in ("", "y", "yes"))
+        yes = answer in ("", "y", "yes")
+        record_consent(cfg, yes, installs=yes)
+        global _ANSWERED_HERE
+        _ANSWERED_HERE = yes
         return True
     except Exception:  # noqa: BLE001
         return False
@@ -373,6 +453,56 @@ def emit(kind, stage, *, error=None, exc=None, exit_code=None,
         pass
 
 
+def _milestones_path() -> Path:
+    return _report_dir() / "report-milestones.json"
+
+
+def _claim_milestone(stage: str) -> bool:
+    """Mark `stage` sent for this machine; True only for the caller that
+    newly marked it. The marker is written BEFORE the event is spooled and a
+    failed write means no event: a milestone may be lost, never repeated —
+    repeats would inflate exactly the count this exists to make honest.
+
+    The funnel is nested: `installed` only on a fresh install whose prompt was
+    answered yes in this run, `connected` only on a machine that already sent
+    `installed` — so an existing machine opting in later counts as neither."""
+    try:
+        path = _milestones_path()
+        seen = {}
+        if path.exists():
+            seen = json.loads(path.read_text(encoding="utf-8"))
+            if not isinstance(seen, dict):
+                return False  # unreadable marker: assume sent
+        if stage in seen:
+            return False
+        if stage == "installed" and not _fresh_install_consented():
+            return False
+        if stage == "connected" and "installed" not in seen:
+            return False
+        seen[stage] = int(time.time())
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(seen), encoding="utf-8")
+        return True
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def milestone(stage, *, cfg=None, flush_now: bool = True) -> None:
+    """Record an install milestone once per machine. Never raises; same spool
+    and wire as emit(), so an offline machine sends it on a later flush."""
+    try:
+        if not milestones_enabled(cfg):
+            return
+        event = build_milestone(stage)
+        if event is None or not _claim_milestone(stage):
+            return
+        _append_spool(event)
+        if flush_now:
+            flush(cfg=cfg)
+    except Exception:  # noqa: BLE001
+        pass
+
+
 def _read_events(path: Path) -> list[dict]:
     out = []
     try:
@@ -443,7 +573,8 @@ def flush(cfg=None, timeout=None) -> None:
     if timeout is None:
         timeout = FLUSH_TIMEOUT
     try:
-        if not is_enabled(cfg):
+        failures_on, milestones_on = is_enabled(cfg), milestones_enabled(cfg)
+        if not (failures_on or milestones_on):
             return
         claims = _adoptable_claims()
         spool = _spool_path()
@@ -457,6 +588,11 @@ def flush(cfg=None, timeout=None) -> None:
                 claim_path.unlink()
             except OSError:
                 pass
+            # Each event travels only under its own consent: a spooled failure
+            # from before `failures = false` is dropped, not sent under the
+            # installs answer (and vice versa).
+            events = [e for e in events
+                      if (milestones_on if e.get("kind") == MILESTONE_KIND else failures_on)]
             if not events:
                 continue
             try:

{firekeep_client-1.7.2 → firekeep_client-1.8.1}/firekeep_client/shim.py

@@ -159,8 +159,9 @@ class _StashSessionAuth(httpx.Auth):
                     # Tap-wired: what THIS process observed, or nothing.
                     sid = self._tap._session_id
                 else:
-                    stash = state.read_session_stash(self._agent)
-                    sid = (stash or {}).get("session_id")
+                    # Fresh stash first; under Studio, the report file survives
+                    # the stash clear a resumed runtime's session_start performs.
+                    sid = state.current_session_id(self._agent)
                 if sid:
                     request.headers["X-Session-Id"] = sid
         except Exception:
@@ -515,11 +516,15 @@ class _BridgeSessionTap:
                 return item
             name = params.get("name")
             rid = getattr(root, "id", None)
-            if rid is not None and (
-                name in self._CAPTURE_TOOLS
-                or name in self._END_TOOLS
-            ):
+            if rid is not None and name in self._CAPTURE_TOOLS:
                 self._pending[rid] = name
+            elif rid is not None and name in self._END_TOOLS:
+                # Remember WHICH session the call targets: an explicit id from
+                # the agent wins, else this process's captured id.
+                raw_args = params.get("arguments")
+                explicit = raw_args.get("session_id") if isinstance(raw_args, dict) else None
+                target = explicit if isinstance(explicit, str) and explicit else self._session_id
+                self._pending[rid] = (name, target)
             if name in self._INJECT_TOOLS:
                 args = params.get("arguments")
                 if isinstance(args, dict):
@@ -546,8 +551,16 @@ class _BridgeSessionTap:
             rid = getattr(root, "id", None)
             if rid is None or rid not in self._pending:
                 return item
-            name = self._pending.pop(rid)
+            entry = self._pending.pop(rid)
+            target = None
+            if isinstance(entry, tuple):
+                name, target = entry
+            else:
+                name = entry
             if name in self._END_TOOLS:
+                # Tombstone the session the call targeted before clearing.
+                if target:
+                    state.end_session_report(target)
                 self._session_id = None
                 state.clear_session_stash(self._agent)
                 return item
@@ -557,6 +570,9 @@ class _BridgeSessionTap:
                 # Keep writing the agent-keyed disk stash: hook cores in other
                 # processes still read it, and it is the restart fallback.
                 state.write_session_stash(self._agent, session_id=sid)
+                # Studio 0.5: tell the launching Studio session which Keep
+                # session this agent is in (no-op unless the env var is set).
+                state.append_session_report(sid)
         except Exception:
             pass
         return item

{firekeep_client-1.7.2 → firekeep_client-1.8.1}/firekeep_client/state.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import subprocess
 import sys
 import time
@@ -448,6 +449,90 @@ def clear_session_stash(agent_id: str) -> None:
         pass
 
 
+# Firekeep Studio 0.5 (spec 2026-10-11 §7.2): Studio launches each agent with
+# this variable naming a per-Studio-session file. The bridge tap appends every
+# Keep session id it captures, so Studio can build per-turn receipts from the
+# sessions the AGENT started — Studio never starts one itself.
+SESSION_REPORT_ENV = "FIREKEEP_SESSION_REPORT_FILE"
+# Ids travel in an HTTP header (X-Session-Id): no whitespace, no newline, ever.
+_SESSION_ID_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,127}")
+
+
+def _report_path() -> str | None:
+    raw = os.environ.get(SESSION_REPORT_ENV, "").strip()
+    return raw or None
+
+
+def append_session_report(session_id: str) -> None:
+    """Append a captured Keep session id to $FIREKEEP_SESSION_REPORT_FILE.
+    No-op when the variable is unset or the id is not header-safe. Never raises."""
+    try:
+        path = _report_path()
+        if not path or not isinstance(session_id, str) or not _SESSION_ID_RE.fullmatch(session_id):
+            return
+        with open(path, "a", encoding="utf-8", newline="\n") as fh:
+            fh.write(session_id + "\n")
+    except Exception:
+        pass
+
+
+def end_session_report(session_id: str) -> None:
+    """Mark a session as ended in $FIREKEEP_SESSION_REPORT_FILE by appending
+    '#ended <id>'. No-op when the variable is unset or the id is not header-safe.
+    Never raises."""
+    try:
+        path = _report_path()
+        if not path or not isinstance(session_id, str) or not _SESSION_ID_RE.fullmatch(session_id):
+            return
+        with open(path, "a", encoding="utf-8", newline="\n") as fh:
+            fh.write(f"#ended {session_id}\n")
+    except Exception:
+        pass
+
+
+def reported_session_id() -> str | None:
+    """The last active (not ended) header-safe id in $FIREKEEP_SESSION_REPORT_FILE.
+    A line '#ended <id>' marks an id as ended; scanning in order, the last active
+    id is returned, or None. A file whose mtime is older than the session stash
+    TTL is ignored (a stale file must not attribute a new day's work to a dead
+    session). Handles non-UTF-8 bytes gracefully."""
+    try:
+        path = _report_path()
+        if not path:
+            return None
+        if time.time() - os.path.getmtime(path) > _session_stash_ttl_seconds():
+            return None
+        last = None
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                line = line.strip()
+                if line.startswith("#ended "):
+                    # Extract the id after "#ended "
+                    ended_id = line[7:]  # len("#ended ") == 7
+                    # Deliberately fail-closed: a tombstone clears only the
+                    # most recent id, so "K1, K2, #ended K2" yields None even
+                    # if K1 is still live. Tracking a set of ended ids would
+                    # revive sessions that ended without writing a tombstone.
+                    if ended_id == last:
+                        last = None
+                elif _SESSION_ID_RE.fullmatch(line):
+                    last = line
+        return last
+    except Exception:
+        return None
+
+
+def current_session_id(agent_id: str) -> str | None:
+    """The Keep session this agent is working in: the fresh stash, else the
+    Studio report file (which survives the stash clear a resumed runtime's
+    session_start performs). Never raises."""
+    try:
+        stash = read_session_stash(agent_id) or {}
+        return stash.get("session_id") or reported_session_id()
+    except Exception:
+        return None
+
+
 # --- runbook bundle store (Enforced Runbooks Phase B) ------------------------
 #
 # Spec: docs/superpowers/specs/2026-08-15-enforced-runbooks-design.md ("Bundle").