session-glue 0.1.0__tar.gz

session_glue-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## Summary
+
+<!-- What changed and why? -->
+
+## Verification
+
+<!-- Commands run, or explain why not run. -->
+
+## Sensitive Information Check
+
+- [ ] I did not include API keys, tokens, cookies, passwords, private keys, or `.env` contents.
+- [ ] I did not include private customer data, private repo contents, or proprietary logs.
+- [ ] I used generic paths/placeholders instead of personal local paths where possible.
+- [ ] Any fixtures, screenshots, handoff examples, or logs are safe for a public repository.
+
+## Scope Check
+
+- [ ] This PR stays within the linked issue scope.
+- [ ] This PR does not add a daemon, MCP dependency, embeddings, database, watcher, product UI, telemetry, or cloud sync unless maintainers explicitly approved a scope change.

session_glue-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.DS_Store
+.env
+.env.*
+*.local
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.log
+dist/
+build/
+*.egg-info/
+.agent-history/
+/docs/

session_glue-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing
+
+Session Glue is intended to be an open-source project. Keep all project content safe to publish.
+
+## Sensitive Information Policy
+
+Do not include:
+
+- API keys, access tokens, cookies, session IDs, passwords, or private keys
+- `.env` file contents
+- production credentials or secret-dependent command output
+- private customer data, private repo contents, or proprietary logs
+- personal local paths when a generic path is enough
+- screenshots that reveal secrets, account identifiers, dashboards, or private chats
+
+Use placeholders instead:
+
+- `/path/to/project`
+- `<API_KEY>`
+- `<TOKEN>`
+- `<PRIVATE_REPO>`
+- `<REDACTED>`
+
+## Pull Request Expectations
+
+Before opening a PR:
+
+- run the relevant tests
+- keep scope tied to one issue when practical
+- update docs when behavior changes
+- check that new fixtures and examples contain no real credentials or private data
+- avoid adding daemons, MCP dependencies, embeddings, databases, watchers, product UI, telemetry, or cloud sync unless maintainers explicitly approve a scope change first
+
+## Issues And Comments
+
+GitHub issues and PR comments are public once the repository is public. Do not paste raw agent transcripts, local handoff files, logs, or screenshots unless they have been checked for sensitive content.

session_glue-0.1.0/LICENSE

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

session_glue-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: session-glue
+Version: 0.1.0
+Summary: A zero-daemon, repo-local session-continuity protocol and CLI for coding agents.
+Project-URL: Homepage, https://github.com/realproject7/session-glue
+Project-URL: Repository, https://github.com/realproject7/session-glue
+Author: Session Glue
+License: MIT License
+        
+        Copyright (c) 2026 realproject7
+        
+        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.
+License-File: LICENSE
+Keywords: agent,claude,cli,codex,continuity,handoff,memory,session
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Session Glue
+
+Session Glue is a lightweight session-continuity protocol and CLI for coding agents.
+
+Its goal is simple: when an agent session gets too long, create a compact local handoff that lets the next session resume without dragging the full chat history forward.
+
+## Status
+
+Pre-MVP founding repository.
+
+## Product Boundary
+
+Session Glue v1 is intentionally small:
+
+- repo-local `.agent-history/` handoffs
+- markdown handoff files with YAML frontmatter
+- `LATEST.md`, archived session files, `INDEX.yaml`, and `RESUME_PROMPT.txt`
+- lightweight Python CLI
+- no daemon
+- no MCP dependency
+- no embeddings
+- no vector database
+- no file watcher
+- no product UI
+
+## Planned CLI
+
+Primary executable:
+
+```bash
+glue
+```
+
+Fallback executable:
+
+```bash
+session-glue
+```
+
+Planned commands:
+
+```bash
+glue create
+glue validate
+glue status
+glue resume-prompt
+glue install codex --dry-run
+glue install claude --dry-run
+glue install cursor --dry-run
+glue install gemini --dry-run
+```
+
+### `glue create`
+
+`glue create` archives an agent-composed handoff into the repository-local
+`.agent-history/` directory. The agent writes the handoff document (YAML
+frontmatter plus a narrative body — see the fixtures under
+`tests/fixtures/handoffs/`); the CLI persists it:
+
+```bash
+glue create --input handoff.md          # or pipe via stdin: glue create < handoff.md
+glue create --input handoff.md --repo-root /path/to/project
+```
+
+It creates or updates:
+
+- `.agent-history/sessions/<session>.md` — the archived session
+- `.agent-history/LATEST.md` — a copy of the newest handoff
+- `.agent-history/RESUME_PROMPT.txt` — the copy-paste resume prompt
+- `.agent-history/INDEX.yaml` — compact metadata and a session list
+
+The handoff is validated first: a missing required field or a resume-mechanic
+`next_todo_items[0]` is rejected before anything is written. `glue create` never
+accesses the network or the OS clipboard.
+
+### `glue validate`
+
+`glue validate` checks that an existing `.agent-history/` is internally
+consistent:
+
+```bash
+glue validate                              # validate ./.agent-history/
+glue validate --repo-root /path/to/project
+glue validate --sessions                   # also validate archived session files
+```
+
+It verifies that `LATEST.md` has valid frontmatter, that its `next_todo_items[0]`
+is a productive action (not a resume mechanic such as "paste the prompt" or
+"read `LATEST.md`"), that `RESUME_PROMPT.txt` exists, and that
+`INDEX.yaml.first_next_action` matches `LATEST.md`'s `next_todo_items[0]`. It
+exits non-zero and prints each problem when validation fails. Like the rest of
+the CLI, it never touches the network or an LLM.
+
+### `glue status` and `glue resume-prompt`
+
+Two compact, read-only commands for orienting a new session:
+
+```bash
+glue status           # latest session metadata + a cheap validation summary
+glue resume-prompt    # print .agent-history/RESUME_PROMPT.txt exactly
+```
+
+`glue status` reads `INDEX.yaml` and prints the latest session id, latest file,
+current branch, head commit, and first next action, plus a one-line validation
+summary. It deliberately does **not** print the full session narrative, so it
+orients you without recreating context bloat, and it handles a missing
+`.agent-history/` gracefully. `glue resume-prompt` prints the exact contents of
+`.agent-history/RESUME_PROMPT.txt`. Both are strictly read-only.
+
+### `glue install <agent> --dry-run`
+
+`glue install` shows the managed instruction block Session Glue would add to a
+coding agent's global instruction file, so agents know how to respond to
+`/glue`, `/freeze`, `/handoff`, and `/checkpoint`:
+
+```bash
+glue install codex --dry-run
+glue install claude --dry-run
+glue install cursor --dry-run
+glue install gemini --dry-run
+glue install all --dry-run
+```
+
+It prints the target path and the proposed block (delimited by stable
+`<!-- BEGIN/END SESSION GLUE (managed) -->` markers so a future updater can
+replace it idempotently). **Only `--dry-run` is supported** — it never modifies
+your home directory, and real installation is intentionally not implemented
+(operator-gated). Running `glue install <agent>` without `--dry-run` exits with
+an error.
+
+## Development
+
+Keep the MVP small. Do not add daemons, background sync, retrieval services, or UI surfaces unless the project scope explicitly changes first.
+
+Session Glue targets Python 3.10+ and has **no required runtime dependencies** — the CLI is built on the standard library so it can be installed and trusted immediately.
+
+### Local install
+
+Create and activate a virtual environment, then install the package in editable mode with the development extras:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+python -m pip install -e ".[dev]"
+```
+
+### Verify the CLI
+
+```bash
+glue --help
+glue --version
+session-glue --help              # fallback executable
+python -m session_glue --help    # module invocation
+```
+
+### Run the tests
+
+```bash
+pytest
+```
+
+### Lint (optional)
+
+```bash
+ruff check .
+```
+
+## Contributing
+
+Read [`CONTRIBUTING.md`](CONTRIBUTING.md) before opening issues or pull requests. All public content must avoid credentials, private logs, `.env` contents, and personal local paths.
+
+For vulnerability reports, see [`SECURITY.md`](SECURITY.md).

session_glue-0.1.0/README.md

@@ -0,0 +1,172 @@
+# Session Glue
+
+Session Glue is a lightweight session-continuity protocol and CLI for coding agents.
+
+Its goal is simple: when an agent session gets too long, create a compact local handoff that lets the next session resume without dragging the full chat history forward.
+
+## Status
+
+Pre-MVP founding repository.
+
+## Product Boundary
+
+Session Glue v1 is intentionally small:
+
+- repo-local `.agent-history/` handoffs
+- markdown handoff files with YAML frontmatter
+- `LATEST.md`, archived session files, `INDEX.yaml`, and `RESUME_PROMPT.txt`
+- lightweight Python CLI
+- no daemon
+- no MCP dependency
+- no embeddings
+- no vector database
+- no file watcher
+- no product UI
+
+## Planned CLI
+
+Primary executable:
+
+```bash
+glue
+```
+
+Fallback executable:
+
+```bash
+session-glue
+```
+
+Planned commands:
+
+```bash
+glue create
+glue validate
+glue status
+glue resume-prompt
+glue install codex --dry-run
+glue install claude --dry-run
+glue install cursor --dry-run
+glue install gemini --dry-run
+```
+
+### `glue create`
+
+`glue create` archives an agent-composed handoff into the repository-local
+`.agent-history/` directory. The agent writes the handoff document (YAML
+frontmatter plus a narrative body — see the fixtures under
+`tests/fixtures/handoffs/`); the CLI persists it:
+
+```bash
+glue create --input handoff.md          # or pipe via stdin: glue create < handoff.md
+glue create --input handoff.md --repo-root /path/to/project
+```
+
+It creates or updates:
+
+- `.agent-history/sessions/<session>.md` — the archived session
+- `.agent-history/LATEST.md` — a copy of the newest handoff
+- `.agent-history/RESUME_PROMPT.txt` — the copy-paste resume prompt
+- `.agent-history/INDEX.yaml` — compact metadata and a session list
+
+The handoff is validated first: a missing required field or a resume-mechanic
+`next_todo_items[0]` is rejected before anything is written. `glue create` never
+accesses the network or the OS clipboard.
+
+### `glue validate`
+
+`glue validate` checks that an existing `.agent-history/` is internally
+consistent:
+
+```bash
+glue validate                              # validate ./.agent-history/
+glue validate --repo-root /path/to/project
+glue validate --sessions                   # also validate archived session files
+```
+
+It verifies that `LATEST.md` has valid frontmatter, that its `next_todo_items[0]`
+is a productive action (not a resume mechanic such as "paste the prompt" or
+"read `LATEST.md`"), that `RESUME_PROMPT.txt` exists, and that
+`INDEX.yaml.first_next_action` matches `LATEST.md`'s `next_todo_items[0]`. It
+exits non-zero and prints each problem when validation fails. Like the rest of
+the CLI, it never touches the network or an LLM.
+
+### `glue status` and `glue resume-prompt`
+
+Two compact, read-only commands for orienting a new session:
+
+```bash
+glue status           # latest session metadata + a cheap validation summary
+glue resume-prompt    # print .agent-history/RESUME_PROMPT.txt exactly
+```
+
+`glue status` reads `INDEX.yaml` and prints the latest session id, latest file,
+current branch, head commit, and first next action, plus a one-line validation
+summary. It deliberately does **not** print the full session narrative, so it
+orients you without recreating context bloat, and it handles a missing
+`.agent-history/` gracefully. `glue resume-prompt` prints the exact contents of
+`.agent-history/RESUME_PROMPT.txt`. Both are strictly read-only.
+
+### `glue install <agent> --dry-run`
+
+`glue install` shows the managed instruction block Session Glue would add to a
+coding agent's global instruction file, so agents know how to respond to
+`/glue`, `/freeze`, `/handoff`, and `/checkpoint`:
+
+```bash
+glue install codex --dry-run
+glue install claude --dry-run
+glue install cursor --dry-run
+glue install gemini --dry-run
+glue install all --dry-run
+```
+
+It prints the target path and the proposed block (delimited by stable
+`<!-- BEGIN/END SESSION GLUE (managed) -->` markers so a future updater can
+replace it idempotently). **Only `--dry-run` is supported** — it never modifies
+your home directory, and real installation is intentionally not implemented
+(operator-gated). Running `glue install <agent>` without `--dry-run` exits with
+an error.
+
+## Development
+
+Keep the MVP small. Do not add daemons, background sync, retrieval services, or UI surfaces unless the project scope explicitly changes first.
+
+Session Glue targets Python 3.10+ and has **no required runtime dependencies** — the CLI is built on the standard library so it can be installed and trusted immediately.
+
+### Local install
+
+Create and activate a virtual environment, then install the package in editable mode with the development extras:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+python -m pip install -e ".[dev]"
+```
+
+### Verify the CLI
+
+```bash
+glue --help
+glue --version
+session-glue --help              # fallback executable
+python -m session_glue --help    # module invocation
+```
+
+### Run the tests
+
+```bash
+pytest
+```
+
+### Lint (optional)
+
+```bash
+ruff check .
+```
+
+## Contributing
+
+Read [`CONTRIBUTING.md`](CONTRIBUTING.md) before opening issues or pull requests. All public content must avoid credentials, private logs, `.env` contents, and personal local paths.
+
+For vulnerability reports, see [`SECURITY.md`](SECURITY.md).

session_glue-0.1.0/SECURITY.md

@@ -0,0 +1,13 @@
+# Security Policy
+
+## Reporting A Vulnerability
+
+Please report security issues privately to the repository owner instead of opening a public issue.
+
+Do not include live credentials in reports. Redact tokens, cookies, keys, and customer data.
+
+## Handoff Data Warning
+
+Session Glue writes local handoff files that may describe implementation details. Projects should decide whether `.agent-history/` belongs in git.
+
+The default repository `.gitignore` excludes `.agent-history/` so handoffs stay local unless a project intentionally changes that policy.

session_glue-0.1.0/codex-skills/session-glue/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: session-glue
+description: >-
+  Use when the operator asks to glue, freeze, hand off, checkpoint, or resume a
+  coding-agent session, including /glue, /freeze, /handoff, /checkpoint,
+  "세션 붙여줘", "세션 얼려줘", or "create a Session Glue handoff".
+---
+
+# Session Glue
+
+Session Glue creates a compact repo-local handoff for restarting a long coding
+agent session without carrying the whole chat forward.
+
+## Glue A Session
+
+When the operator asks to glue, freeze, hand off, checkpoint, or prepare a new
+session:
+
+1. Stop the active task at a clean boundary.
+2. Compose a high-density handoff markdown document for the next agent.
+3. Prefer the installed CLI:
+
+```bash
+glue create --repo-root . --input <handoff.md>
+```
+
+4. If `glue` is unavailable, read `references/protocol.md` and write the same
+   `.agent-history/` files directly with the fallback protocol.
+5. Run `glue validate --repo-root .` when the CLI is available.
+6. Print the exact contents of `.agent-history/RESUME_PROMPT.txt` in a fenced
+   code block so the operator can paste it into the next session.
+
+Do not request OS clipboard access. Do not add MCP, a daemon, a watcher, a
+database, or an external service.
+
+## Resume A Session
+
+When the operator asks to resume or pastes a Session Glue resume prompt:
+
+1. Read `.agent-history/LATEST.md` first.
+2. Run `git status --short` and report drift from the handoff.
+3. Inspect active context files from the handoff before broad repo search.
+4. Continue from the first productive `next_todo_items` entry.
+
+Use `glue status --repo-root .` for a compact orientation and
+`glue resume-prompt --repo-root .` to print the canonical prompt exactly.

session_glue-0.1.0/codex-skills/session-glue/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Session Glue"
+  short_description: "Create and resume compact agent handoffs."
+  default_prompt: "Use $session-glue to create a compact handoff for this coding session."
+policy:
+  allow_implicit_invocation: true

session_glue-0.1.0/codex-skills/session-glue/references/protocol.md

@@ -0,0 +1,118 @@
+# Session Glue Fallback Protocol
+
+Use this only when the `glue` CLI is unavailable. The CLI is canonical.
+
+## File Layout
+
+Write all files under the current repository root:
+
+```text
+.agent-history/
+  LATEST.md
+  RESUME_PROMPT.txt
+  INDEX.yaml
+  sessions/
+    <session_id>.md
+```
+
+Never write outside `.agent-history/`. Refuse to follow symlinks that would
+redirect these writes outside the repository.
+
+## Handoff Markdown
+
+`LATEST.md` and `sessions/<session_id>.md` must contain the same markdown
+document. Start with YAML frontmatter using these required fields:
+
+```yaml
+session_id: 2026-07-01-1200-short-slug
+session_date: 2026-07-01
+generated_at: 2026-07-01T12:00:00Z
+schema_version: 1
+project_root: /path/to/project
+repo_root: /path/to/project
+current_branch: main
+head_commit: abc1234
+agent: codex
+status: IN_PROGRESS
+active_context_files:
+  - path/to/file.py
+completed_tasks:
+  - Concrete completed work item.
+next_todo_items:
+  - First productive action after the next agent reads the handoff.
+known_issues:
+  - Known blocker or risk.
+```
+
+The first entry, next_todo_items[0], must be productive work, not resume mechanics. Do not use
+phrases such as "paste the prompt", "start a new session", "read LATEST.md",
+"inspect the handoff", or "verify the new agent reads the handoff".
+
+Below the frontmatter, include these sections:
+
+- `# Resume Prompt`
+- `# What We Did`
+- `# Current State`
+- `# Decisions Made`
+- `# Failed Attempts / Dead Ends`
+- `# Next-Agent Instructions`
+- `# Commands And Validation`
+- `# Risks And Constraints`
+
+## RESUME_PROMPT.txt
+
+Write a short paste-ready prompt:
+
+```text
+Continue the previous coding session.
+
+Project root: /path/to/project
+First, read: .agent-history/LATEST.md
+Prompt artifact: .agent-history/RESUME_PROMPT.txt
+Then follow the Resume Prompt and continue from the first next_todo_items entry.
+
+First productive next action (next_todo_items[0]):
+<next_todo_items[0]>
+
+Before editing, run git status --short and report any drift from the handoff.
+Do not scan the whole repository unless the handoff is stale or insufficient.
+```
+
+After writing the files, print the exact prompt in a fenced code block.
+
+## Dogfood Harness Guidance
+
+When testing Session Glue with a fresh agent, keep two roles separate:
+
+- The outer observer starts fresh-agent trials and records behavior.
+- The trial subject only resumes from the handoff and reports what it did.
+
+Do not make the trial subject's first productive action "run a fresh agent
+trial" or "start another agent". That can create a meta-loop where the resumed
+agent launches another resumed agent instead of being the test subject.
+
+## INDEX.yaml
+
+Write compact metadata only. Do not duplicate the narrative:
+
+```yaml
+schema_version: 1
+latest_session: 2026-07-01-1200-short-slug
+latest_file: sessions/2026-07-01-1200-short-slug.md
+repo_root: /path/to/project
+current_branch: main
+head_commit: abc1234
+first_next_action: First productive action after the next agent reads the handoff.
+sessions:
+  - session_id: 2026-07-01-1200-short-slug
+    file: sessions/2026-07-01-1200-short-slug.md
+    session_date: 2026-07-01
+    generated_at: 2026-07-01T12:00:00Z
+    agent: codex
+    project_root: /path/to/project
+    repo_root: /path/to/project
+    current_branch: main
+    head_commit: abc1234
+    status: IN_PROGRESS
+    first_next_action: First productive action after the next agent reads the handoff.
+```