agent-sessions-cli 0.2.0__tar.gz

agent_sessions_cli-0.2.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.DS_Store

agent_sessions_cli-0.2.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.2.0 — 2026-09-22
+
+Works across coding agents. The repo is now `agent-sessions`; the Claude plugin keeps its name `sessions`.
+
+- **Adapters**: Codex CLI (rollout JSONL, session index titles, `exec` command extraction, `apply_patch` files, compaction history) and OpenCode (SQLite, read-only, locked-db fallback, compaction parts, child sessions) join Claude Code. Gemini CLI ships as an experimental adapter built from its source schema. Copilot CLI and Cursor are detected and reported as not yet supported.
+- **Agent-neutral model**: adapters emit events with canonical tool kinds (shell, read, edit, write, search, web, agent, mcp, ask); the renderer, result policy, redaction and files-touched logic no longer know agent tool names.
+- **Live-session identification** without env vars: the locate call recognises itself as the shell call still running in exactly one session; otherwise it lists candidates and asks instead of guessing. Codex fork stubs are skipped.
+- **Re-push fix**: the transcript now stops at the last push invocation, so pushing the same session twice keeps everything after the first push.
+- **Portable skill** `agents-skills/agent-sessions/` (Agent Skills standard) with a bundled copy of the package, installed by `scripts/setup.sh --skills` into `~/.agents/skills/`, which Codex, OpenCode, Gemini CLI, Cursor and Copilot all read. `init --vendor-skill` copies it into a repo for teammates.
+- **Python package** `agent-sessions-cli` (`pip install agent-sessions-cli`, console script `agent-sessions`), CI on Linux, macOS and Windows, release workflow with PyPI trusted publishing.
+- `doctor` subcommand; `STATUS:` printed first and last; `SCRIPT:` line; `meta.json` gains `agent`, `agent_version`, `originator`, `parent_id`, `short_id`, `tokens`; commit trailer `Agent-Session: <agent>:<id>`; temp index inside the git dir for sandboxed agents.
+
+## 0.1.0 — 2026-09-21
+
+First release, Claude Code only.
+
+- `/sessions:push` writes a handoff summary, renders and redacts the transcript, commits under `.claude/sessions/` through a temporary index, and pushes.
+- `/sessions:pull` fetches, indexes sessions on the default branch and `HEAD`, and loads summaries into the chat.
+- `/sessions:init` fixes `.gitignore`, drops a README and `.gitattributes`, and registers the plugin in `.claude/settings.json`.
+- Renderer follows the active conversation path across rewinds and compaction, stubs MCP and file-read results, truncates other tool output, and collects files touched by subagents.
+- Redaction covers cloud and VCS tokens, JWTs, private keys, URL credentials, Azure storage and Entra secrets, connection-string passwords and SAS signatures, with keyword hits flagged for review.

agent_sessions_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prajwal P
+
+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.

agent_sessions_cli-0.2.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: agent-sessions-cli
+Version: 0.2.0
+Summary: Share coding-agent sessions (Claude Code, Codex CLI, OpenCode, Gemini CLI) with your team through git.
+Project-URL: Homepage, https://github.com/prajwalgajakesari/agent-sessions
+Project-URL: Repository, https://github.com/prajwalgajakesari/agent-sessions
+Project-URL: Changelog, https://github.com/prajwalgajakesari/agent-sessions/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/prajwalgajakesari/agent-sessions/issues
+Author: Prajwal P
+License: MIT
+License-File: LICENSE
+Keywords: claude-code,codex,gemini-cli,git,handoff,opencode,sessions,team,transcript
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# agent-sessions
+
+Share coding-agent sessions with your team through the git repo you already work in. One folder, `.claude/sessions/`, holds handoffs from **Claude Code, Codex CLI, OpenCode** and (experimentally) **Gemini CLI**; anyone on any agent can pull them back into their own chat.
+
+```
+/sessions:push "Reconcile fabric tables"        Claude Code, end of a session
+$agent-sessions pull reconcile                  a teammate in Codex, next morning
+```
+
+Coding agents keep sessions in private, undocumented, short-lived local stores. This tool turns one into three committed files and gives teammates one command to load them.
+
+## What a pushed session looks like
+
+```
+.claude/sessions/2026-09-22_reconcile-fabric-tables_prajwal-p_7dcecef6/
+├── summary.md      handoff the author's agent wrote at push time: goal, outcome, decisions and why,
+│                   files changed, commands and gotchas, open questions, a paste-ready handoff prompt (≤120 lines)
+├── transcript.md   the conversation as markdown along the active path (rewinds and compaction handled),
+│                   tool calls collapsed, secrets redacted, file reads and query results omitted
+└── meta.json       title, author, agent and version, branch, dates, files touched (subagents included), tags, outcome, tokens
+```
+
+Pull reads `summary.md` first and loads a transcript only when asked, so a teammate gets the reasoning without burning their context window.
+
+## Install
+
+| You use | Do this once |
+|---|---|
+| Claude Code | `/plugin marketplace add prajwalgajakesari/agent-sessions` then `/plugin install sessions@agent-sessions`. Repos set up with `init` prompt you automatically. |
+| Codex CLI, OpenCode, Gemini CLI, Cursor, Copilot | `scripts/setup.sh --skills` (or `scripts\setup.ps1 -Skills`) from a checkout. It copies the `agent-sessions` skill into `~/.agents/skills/`, which all of them read. |
+| Any terminal | `pip install agent-sessions-cli` or `uvx agent-sessions-cli`, then `agent-sessions doctor`. |
+
+Requirements: git and Python 3.9+ (`python3`, `python`, or the Windows `py` launcher). No Python packages.
+
+Then, in each repo you want to share sessions in: `/sessions:init` in Claude Code, or `$agent-sessions init` in Codex, or `agent-sessions init` in a terminal. It fixes a blanket `.claude/` ignore rule so only `.claude/sessions/` and `.claude/settings.json` are tracked, drops a README and `.gitattributes`, registers the Claude plugin in `.claude/settings.json`, and commits exactly those files. Add `--vendor-skill` to also copy the portable skill into `.agents/skills/` so every teammate's agent discovers it on clone.
+
+## Using it
+
+| Agent | Share this session | Read teammates' sessions |
+|---|---|---|
+| Claude Code | `/sessions:push [title] [--yes]` | `/sessions:pull [keyword]` |
+| Codex CLI | `$agent-sessions push [title] --yes` | `$agent-sessions pull [keyword]` |
+| OpenCode, Gemini CLI, Cursor, Copilot | "use the agent-sessions skill to push this session" | "use the agent-sessions skill to pull [keyword]" |
+| Terminal | `agent-sessions locate` → write `summary.md` → `export` → `commit --push` | `agent-sessions list` |
+
+Push flow, whichever agent runs it:
+
+1. `locate` finds this session in the agent's store, checks the repo (ignore rules, detached HEAD, merges in progress, missing upstream) and prints an outline of the conversation.
+2. The agent writes `summary.md` from the template, using the outline plus its own memory, through `write-summary` (agents' file tools tend to refuse `.claude/`).
+3. `export` renders and redacts the transcript, writes `meta.json`, renames the folder to the final title, and prints a redaction report.
+4. You see a short preview and confirm once. `--yes` skips it.
+5. `commit --push` builds the commit on a temporary index inside `.git` and pushes to your current branch. Your staged changes, working tree and any in-progress merge are untouched. `--branch` pushes to a new remote branch instead.
+
+Pushing the same session again updates the same folder and keeps everything after the first push.
+
+Pull flags: `--n N` how many summaries (default 3), `--full <id>` one full transcript, `--all-branches` sessions on unmerged branches, `--mine` your own.
+
+## How the live session is found
+
+No agent tells a shell command which session it belongs to, so `locate` never guesses:
+
+| Signal | Used by |
+|---|---|
+| `--session-id` passed by the skill | Claude Code (`${CLAUDE_SESSION_ID}` is substituted into the preflight) |
+| Environment variable | Claude Code (`CLAUDE_CODE_SESSION_ID`); Codex if `CODEX_THREAD_ID` reaches child shells |
+| **Self-reference**: the `locate` call itself is the newest shell call in exactly one session and has no output yet | Codex, OpenCode, Claude Code |
+| A push invocation in the latest user turn | any |
+| Exactly one session for this repo | any |
+
+If more than one session still matches, `locate` prints `CANDIDATES:` and the skill asks you which one, then re-runs with `--agent` and `--session-id`. Codex fork and compaction stubs are skipped.
+
+## Where each agent keeps sessions
+
+| Agent | Store | Notes |
+|---|---|---|
+| Claude Code | `~/.claude/projects/<encoded-cwd>/<id>.jsonl` (+ `subagents/`) | active path via `parentUuid`, compaction boundaries, subagent edits counted |
+| Codex CLI | `$CODEX_HOME/sessions/YYYY/MM/DD/rollout-*.jsonl`, `session_index.jsonl` for titles | `exec` snippets parsed for `exec_command` and `apply_patch`; `compacted` history rendered once; developer messages and environment wrappers dropped |
+| OpenCode | `~/.local/share/opencode/opencode.db` (SQLite, WAL) | opened read-only, copied if locked; `compaction` parts; child sessions feed files touched; tokens and cost from the session row |
+| Gemini CLI | `~/.gemini/tmp/<hash>/chats/session-*.jsonl` | **experimental**: built from the source schema without a real sample; `$set`/`$rewindTo` applied |
+| Copilot CLI, Cursor | detected, not exported | pull and init work; push says so. Cursor's plain-text agent transcripts are the next adapter once a sample exists |
+
+## What is and is not redacted
+
+| Layer | What it does |
+|---|---|
+| Result policy | Results of file reads, web fetches and MCP tools are replaced by a one-line stub. Other tool output is cut to 30 lines or 2 KB. `--include-results` keeps up to 20 KB per result. |
+| Sensitive files | Any tool call that reads or edits `.env*`, `local.settings.json`, `appsettings*.json`, `secrets.json`, key and certificate files, Terraform state, `.netrc`, `.pypirc`, `.databrickscfg` or anything under `.azure/` has both input and result withheld. |
+| Pattern redaction | AWS keys, GitHub, Slack, OpenAI and Anthropic tokens, JWTs, private keys, credentials in URLs, Azure storage account keys, shared access keys and SAS signatures, Azure DevOps PATs, Entra client secrets, bearer tokens. Keyword hits such as `password=`, `client_secret=`, `-P` after `sqlcmd` are redacted too and listed for you to review. |
+
+GUIDs are never redacted. Placeholders like `${DB_PASSWORD}` and `<your-key>` are left alone. If a high-confidence pattern still matches after redaction, export deletes the transcript and refuses. Treat a pushed transcript the way you treat a chat log: read the preview before you say yes.
+
+## Sandboxes and permissions
+
+Codex's default sandbox blocks network access, so `commit --push` may fail; approve the escalation when Codex offers it, or run the printed `MANUAL` command in your own terminal. The temporary index lives inside `.git`, which stays writable. In OpenCode, allow the skill's script in `opencode.json` permissions to avoid a prompt per step.
+
+## Layout of this repo
+
+```
+agent_sessions/                   the package (stdlib only): cli.py, core.py, model.py, adapters/, templates/
+scripts/sessions.py, sessions.sh  entry point + shim (finds Python, always exits 0, prints STATUS)
+scripts/setup.sh, setup.ps1       teammate bootstrap: --claude, --skills, --repo <path>
+skills/{push,pull,init}/          the Claude Code plugin skills
+agents-skills/agent-sessions/     the portable Agent-Skills skill, with a bundled copy of the package
+tools/sync_bundle.py              keeps that copy identical (`--check` in CI)
+tests/                            python3 -m unittest discover -s tests
+.claude-plugin/                   plugin.json (name: sessions) and marketplace.json (name: agent-sessions)
+```
+
+Test the Claude plugin from a checkout with `claude --plugin-dir /path/to/agent-sessions`. Test the portable skill by copying `agents-skills/agent-sessions` into `~/.agents/skills/`.
+
+## Contributing an adapter
+
+An adapter is one file in `agent_sessions/adapters/` that turns a native store into `Session` events with canonical tool kinds (`shell`, `read`, `edit`, `write`, `search`, `web`, `agent`, `mcp`, `ask`). The renderer, result policy, redaction and files-touched logic never see agent names. Start from `gemini.py` (small) or `codex.py` (complete). A real session sample from your agent, with secrets removed, is the most useful contribution.
+
+## License
+
+MIT

agent_sessions_cli-0.2.0/README.md

@@ -0,0 +1,117 @@
+# agent-sessions
+
+Share coding-agent sessions with your team through the git repo you already work in. One folder, `.claude/sessions/`, holds handoffs from **Claude Code, Codex CLI, OpenCode** and (experimentally) **Gemini CLI**; anyone on any agent can pull them back into their own chat.
+
+```
+/sessions:push "Reconcile fabric tables"        Claude Code, end of a session
+$agent-sessions pull reconcile                  a teammate in Codex, next morning
+```
+
+Coding agents keep sessions in private, undocumented, short-lived local stores. This tool turns one into three committed files and gives teammates one command to load them.
+
+## What a pushed session looks like
+
+```
+.claude/sessions/2026-09-22_reconcile-fabric-tables_prajwal-p_7dcecef6/
+├── summary.md      handoff the author's agent wrote at push time: goal, outcome, decisions and why,
+│                   files changed, commands and gotchas, open questions, a paste-ready handoff prompt (≤120 lines)
+├── transcript.md   the conversation as markdown along the active path (rewinds and compaction handled),
+│                   tool calls collapsed, secrets redacted, file reads and query results omitted
+└── meta.json       title, author, agent and version, branch, dates, files touched (subagents included), tags, outcome, tokens
+```
+
+Pull reads `summary.md` first and loads a transcript only when asked, so a teammate gets the reasoning without burning their context window.
+
+## Install
+
+| You use | Do this once |
+|---|---|
+| Claude Code | `/plugin marketplace add prajwalgajakesari/agent-sessions` then `/plugin install sessions@agent-sessions`. Repos set up with `init` prompt you automatically. |
+| Codex CLI, OpenCode, Gemini CLI, Cursor, Copilot | `scripts/setup.sh --skills` (or `scripts\setup.ps1 -Skills`) from a checkout. It copies the `agent-sessions` skill into `~/.agents/skills/`, which all of them read. |
+| Any terminal | `pip install agent-sessions-cli` or `uvx agent-sessions-cli`, then `agent-sessions doctor`. |
+
+Requirements: git and Python 3.9+ (`python3`, `python`, or the Windows `py` launcher). No Python packages.
+
+Then, in each repo you want to share sessions in: `/sessions:init` in Claude Code, or `$agent-sessions init` in Codex, or `agent-sessions init` in a terminal. It fixes a blanket `.claude/` ignore rule so only `.claude/sessions/` and `.claude/settings.json` are tracked, drops a README and `.gitattributes`, registers the Claude plugin in `.claude/settings.json`, and commits exactly those files. Add `--vendor-skill` to also copy the portable skill into `.agents/skills/` so every teammate's agent discovers it on clone.
+
+## Using it
+
+| Agent | Share this session | Read teammates' sessions |
+|---|---|---|
+| Claude Code | `/sessions:push [title] [--yes]` | `/sessions:pull [keyword]` |
+| Codex CLI | `$agent-sessions push [title] --yes` | `$agent-sessions pull [keyword]` |
+| OpenCode, Gemini CLI, Cursor, Copilot | "use the agent-sessions skill to push this session" | "use the agent-sessions skill to pull [keyword]" |
+| Terminal | `agent-sessions locate` → write `summary.md` → `export` → `commit --push` | `agent-sessions list` |
+
+Push flow, whichever agent runs it:
+
+1. `locate` finds this session in the agent's store, checks the repo (ignore rules, detached HEAD, merges in progress, missing upstream) and prints an outline of the conversation.
+2. The agent writes `summary.md` from the template, using the outline plus its own memory, through `write-summary` (agents' file tools tend to refuse `.claude/`).
+3. `export` renders and redacts the transcript, writes `meta.json`, renames the folder to the final title, and prints a redaction report.
+4. You see a short preview and confirm once. `--yes` skips it.
+5. `commit --push` builds the commit on a temporary index inside `.git` and pushes to your current branch. Your staged changes, working tree and any in-progress merge are untouched. `--branch` pushes to a new remote branch instead.
+
+Pushing the same session again updates the same folder and keeps everything after the first push.
+
+Pull flags: `--n N` how many summaries (default 3), `--full <id>` one full transcript, `--all-branches` sessions on unmerged branches, `--mine` your own.
+
+## How the live session is found
+
+No agent tells a shell command which session it belongs to, so `locate` never guesses:
+
+| Signal | Used by |
+|---|---|
+| `--session-id` passed by the skill | Claude Code (`${CLAUDE_SESSION_ID}` is substituted into the preflight) |
+| Environment variable | Claude Code (`CLAUDE_CODE_SESSION_ID`); Codex if `CODEX_THREAD_ID` reaches child shells |
+| **Self-reference**: the `locate` call itself is the newest shell call in exactly one session and has no output yet | Codex, OpenCode, Claude Code |
+| A push invocation in the latest user turn | any |
+| Exactly one session for this repo | any |
+
+If more than one session still matches, `locate` prints `CANDIDATES:` and the skill asks you which one, then re-runs with `--agent` and `--session-id`. Codex fork and compaction stubs are skipped.
+
+## Where each agent keeps sessions
+
+| Agent | Store | Notes |
+|---|---|---|
+| Claude Code | `~/.claude/projects/<encoded-cwd>/<id>.jsonl` (+ `subagents/`) | active path via `parentUuid`, compaction boundaries, subagent edits counted |
+| Codex CLI | `$CODEX_HOME/sessions/YYYY/MM/DD/rollout-*.jsonl`, `session_index.jsonl` for titles | `exec` snippets parsed for `exec_command` and `apply_patch`; `compacted` history rendered once; developer messages and environment wrappers dropped |
+| OpenCode | `~/.local/share/opencode/opencode.db` (SQLite, WAL) | opened read-only, copied if locked; `compaction` parts; child sessions feed files touched; tokens and cost from the session row |
+| Gemini CLI | `~/.gemini/tmp/<hash>/chats/session-*.jsonl` | **experimental**: built from the source schema without a real sample; `$set`/`$rewindTo` applied |
+| Copilot CLI, Cursor | detected, not exported | pull and init work; push says so. Cursor's plain-text agent transcripts are the next adapter once a sample exists |
+
+## What is and is not redacted
+
+| Layer | What it does |
+|---|---|
+| Result policy | Results of file reads, web fetches and MCP tools are replaced by a one-line stub. Other tool output is cut to 30 lines or 2 KB. `--include-results` keeps up to 20 KB per result. |
+| Sensitive files | Any tool call that reads or edits `.env*`, `local.settings.json`, `appsettings*.json`, `secrets.json`, key and certificate files, Terraform state, `.netrc`, `.pypirc`, `.databrickscfg` or anything under `.azure/` has both input and result withheld. |
+| Pattern redaction | AWS keys, GitHub, Slack, OpenAI and Anthropic tokens, JWTs, private keys, credentials in URLs, Azure storage account keys, shared access keys and SAS signatures, Azure DevOps PATs, Entra client secrets, bearer tokens. Keyword hits such as `password=`, `client_secret=`, `-P` after `sqlcmd` are redacted too and listed for you to review. |
+
+GUIDs are never redacted. Placeholders like `${DB_PASSWORD}` and `<your-key>` are left alone. If a high-confidence pattern still matches after redaction, export deletes the transcript and refuses. Treat a pushed transcript the way you treat a chat log: read the preview before you say yes.
+
+## Sandboxes and permissions
+
+Codex's default sandbox blocks network access, so `commit --push` may fail; approve the escalation when Codex offers it, or run the printed `MANUAL` command in your own terminal. The temporary index lives inside `.git`, which stays writable. In OpenCode, allow the skill's script in `opencode.json` permissions to avoid a prompt per step.
+
+## Layout of this repo
+
+```
+agent_sessions/                   the package (stdlib only): cli.py, core.py, model.py, adapters/, templates/
+scripts/sessions.py, sessions.sh  entry point + shim (finds Python, always exits 0, prints STATUS)
+scripts/setup.sh, setup.ps1       teammate bootstrap: --claude, --skills, --repo <path>
+skills/{push,pull,init}/          the Claude Code plugin skills
+agents-skills/agent-sessions/     the portable Agent-Skills skill, with a bundled copy of the package
+tools/sync_bundle.py              keeps that copy identical (`--check` in CI)
+tests/                            python3 -m unittest discover -s tests
+.claude-plugin/                   plugin.json (name: sessions) and marketplace.json (name: agent-sessions)
+```
+
+Test the Claude plugin from a checkout with `claude --plugin-dir /path/to/agent-sessions`. Test the portable skill by copying `agents-skills/agent-sessions` into `~/.agents/skills/`.
+
+## Contributing an adapter
+
+An adapter is one file in `agent_sessions/adapters/` that turns a native store into `Session` events with canonical tool kinds (`shell`, `read`, `edit`, `write`, `search`, `web`, `agent`, `mcp`, `ask`). The renderer, result policy, redaction and files-touched logic never see agent names. Start from `gemini.py` (small) or `codex.py` (complete). A real session sample from your agent, with secrets removed, is the most useful contribution.
+
+## License
+
+MIT

agent_sessions_cli-0.2.0/agent_sessions/__init__.py

@@ -0,0 +1,3 @@
+"""agent-sessions: share coding-agent sessions with your team through git."""
+
+__version__ = "0.2.0"

agent_sessions_cli-0.2.0/agent_sessions/__main__.py

@@ -0,0 +1,3 @@
+from .cli import entry
+
+entry()

agent_sessions_cli-0.2.0/agent_sessions/adapters/__init__.py

@@ -0,0 +1,136 @@
+"""Adapter registry and the live-session identification algorithm."""
+
+from __future__ import annotations
+
+import os
+from typing import Dict, List, Optional, Tuple
+
+from ..model import PUSH_MARKER_RE
+from .base import Adapter, SessionRef, recent
+from .claude_code import ClaudeCodeAdapter
+
+REGISTRY: Dict[str, Adapter] = {}
+
+
+def register(adapter: Adapter) -> None:
+    REGISTRY[adapter.name] = adapter
+
+
+register(ClaudeCodeAdapter())
+
+try:  # optional adapters are added as they land; a broken import must not take the tool down
+    from .codex import CodexAdapter
+    register(CodexAdapter())
+except ImportError:  # pragma: no cover
+    pass
+try:
+    from .opencode import OpenCodeAdapter
+    register(OpenCodeAdapter())
+except ImportError:  # pragma: no cover
+    pass
+try:
+    from .gemini import GeminiAdapter
+    register(GeminiAdapter())
+except ImportError:  # pragma: no cover
+    pass
+
+AGENT_CHOICES = ["auto"] + list(REGISTRY.keys())
+RECENT_MINUTES = 15
+
+
+class Resolution:
+    def __init__(self, ref: Optional[SessionRef], how: str, candidates: List[SessionRef], adapter: Optional[Adapter]) -> None:
+        self.ref, self.how, self.candidates, self.adapter = ref, how, candidates, adapter
+
+
+def installed_adapters(agent: str = "auto") -> List[Adapter]:
+    if agent != "auto":
+        if agent not in REGISTRY:
+            raise KeyError(agent)
+        return [REGISTRY[agent]]
+    return [a for a in REGISTRY.values() if a.installed()]
+
+
+def resolve(agent: str, session_id: Optional[str], repo_root: str) -> Resolution:
+    """Find the live session. Never picks silently between several plausible ones."""
+    adapters = installed_adapters(agent)
+    if session_id:
+        for a in adapters:
+            ref = a.locate_by_id(session_id)
+            if ref:
+                return Resolution(ref, "session id", [], a)
+        # known id, no data yet: fresh session. Pick the adapter the environment proves, else the explicit one.
+        owner = REGISTRY[agent] if agent != "auto" else _env_agent(adapters)
+        if owner:
+            return Resolution(owner.pending_ref(session_id), "not written yet", [], owner)
+        return Resolution(None, "not found", [], None)
+
+    for a in adapters:
+        env_id = a.in_env()
+        if env_id:
+            ref = a.locate_by_id(env_id)
+            if ref:
+                return Resolution(ref, f"environment ({a.name})", [], a)
+            return Resolution(a.pending_ref(env_id), "not written yet", [], a)
+
+    all_cands: List[Tuple[Adapter, SessionRef]] = []
+    for a in adapters:
+        try:
+            for ref in a.candidates(repo_root, limit=5):
+                all_cands.append((a, ref))
+        except Exception:  # noqa: BLE001 - one broken store must not hide the others
+            continue
+    all_cands.sort(key=lambda ar: ar[1].updated.timestamp() if ar[1].updated else 0, reverse=True)
+
+    # self-referencing locate call still in flight
+    hits = []
+    for a, ref in all_cands:
+        if not recent(ref, RECENT_MINUTES):
+            continue
+        try:
+            sess = a.load(ref)
+        except Exception:  # noqa: BLE001
+            continue
+        ref.extra["session"] = sess
+        ref.title = ref.title or sess.title
+        if sess.has_pending_self_call():
+            hits.append((a, ref))
+    if len(hits) == 1:
+        return Resolution(hits[0][1], "self-referencing locate call", [], hits[0][0])
+
+    # push marker in the latest user turn
+    marks = []
+    for a, ref in all_cands:
+        sess = ref.extra.get("session")
+        if sess is None:
+            try:
+                sess = a.load(ref)
+                ref.extra["session"] = sess
+                ref.title = ref.title or sess.title
+            except Exception:  # noqa: BLE001
+                continue
+        if PUSH_MARKER_RE.search(sess.last_user_text() or "") or any(e.is_push_invocation for e in sess.events[-3:]):
+            marks.append((a, ref))
+    if len(marks) == 1:
+        return Resolution(marks[0][1], "push marker in latest user turn", [], marks[0][0])
+
+    if len(all_cands) == 1:
+        a, ref = all_cands[0]
+        how = "only recent session for this repo" if recent(ref, RECENT_MINUTES) else "only session for this repo (not recent; check it is the right one)"
+        return Resolution(ref, how, [], a)
+    if not all_cands:
+        return Resolution(None, "not found", [], None)
+    return Resolution(None, "ambiguous", [ref for _, ref in all_cands], None)
+
+
+def _env_agent(adapters: List[Adapter]) -> Optional[Adapter]:
+    for a in adapters:
+        if a.in_env() is not None:
+            return a
+    return None
+
+
+def adapter_for(agent: str) -> Adapter:
+    if agent not in REGISTRY:
+        raise KeyError(agent)
+    return REGISTRY[agent]

agent_sessions_cli-0.2.0/agent_sessions/adapters/base.py

@@ -0,0 +1,108 @@
+"""Adapter contract shared by every agent."""
+
+from __future__ import annotations
+
+import datetime as dt
+import os
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple
+
+from ..model import Session
+
+
+@dataclass
+class SessionRef:
+    agent: str
+    session_id: str
+    short_id: str
+    source: str                      # file path or "sqlite:<db>#<id>"; "" when not on disk yet
+    cwd: Optional[str] = None
+    updated: Optional[dt.datetime] = None
+    title: Optional[str] = None
+    extra: dict = field(default_factory=dict)
+
+    @property
+    def on_disk(self) -> bool:
+        return bool(self.source)
+
+
+class Adapter:
+    name = "base"
+    label = "Base"
+    env_ids: Tuple[str, ...] = ()           # env vars carrying the session id
+    env_presence: Tuple[str, ...] = ()      # env vars that merely prove we run inside this agent
+    tested_version: Optional[Tuple[int, ...]] = None
+
+    def data_dir(self) -> str:
+        raise NotImplementedError
+
+    def installed(self) -> bool:
+        return os.path.exists(self.data_dir())
+
+    def short_id(self, session_id: str) -> str:
+        return session_id[:8]
+
+    def locate_by_id(self, session_id: str) -> Optional[SessionRef]:
+        raise NotImplementedError
+
+    def candidates(self, repo_root: str, limit: int = 5) -> List[SessionRef]:
+        raise NotImplementedError
+
+    def load(self, ref: SessionRef) -> Session:
+        raise NotImplementedError
+
+    def ref_from_source(self, source: str) -> Optional[SessionRef]:
+        """Build a ref from a SOURCE string this adapter printed earlier, or None if it is not ours."""
+        return None
+
+    def pending_ref(self, session_id: str) -> SessionRef:
+        """A session we know the id of but that has no data on disk yet."""
+        return SessionRef(self.name, session_id, self.short_id(session_id), "")
+
+    def in_env(self) -> Optional[str]:
+        """Session id from the environment, or "" if the environment proves the agent but not the id."""
+        for var in self.env_ids:
+            val = os.environ.get(var, "").strip()
+            if val and not val.startswith("${"):
+                return val
+        for var in self.env_presence:
+            if os.environ.get(var):
+                return ""
+        return None
+
+
+def generic_label(name: str, kind: str, inp: object, paths: List[str]) -> str:
+    """Default one-line label. Built from full strings; the renderer redacts then truncates."""
+    d = inp if isinstance(inp, dict) else {}
+    if kind == "shell":
+        cmd = d.get("command") or d.get("cmd") or (inp if isinstance(inp, str) else "")
+        if isinstance(cmd, list):
+            cmd = "; ".join(str(c) for c in cmd)
+        desc = str(d.get("description") or "").strip()
+        return f"{name}: {desc or str(cmd).strip().split(chr(10))[0]}"
+    if kind in ("read", "edit", "write"):
+        target = paths[0] if paths else (d.get("filePath") or d.get("file_path") or d.get("path") or "")
+        return f"{name}: {target}"
+    if kind == "agent":
+        return f"{name}: {str(d.get('description') or d.get('prompt') or '')}"
+    if kind == "search":
+        return f"{name}: {str(d.get('pattern') or d.get('query') or d.get('path') or '')}"
+    if kind == "web":
+        return f"{name}: {str(d.get('url') or d.get('query') or d.get('prompt') or '')}"
+    if kind == "ask":
+        return f"{name}"
+    return name
+
+
+def strip_wrappers(text: str, tags: Tuple[str, ...]) -> str:
+    """Remove <tag ...>…</tag> blocks the harness injects around user text."""
+    import re
+    for tag in tags:
+        text = re.sub(rf"<{tag}\b[^>]*>[\s\S]*?</{tag}>", "", text, flags=re.I)
+    return text.strip()
+
+
+def recent(ref: SessionRef, minutes: int) -> bool:
+    if not ref.updated:
+        return True
+    return (dt.datetime.now(dt.timezone.utc) - ref.updated) <= dt.timedelta(minutes=minutes)