devin-internals-spec 0.3.0__tar.gz

devin_internals_spec-0.3.0/LICENSE

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

devin_internals_spec-0.3.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: devin-internals-spec
+Version: 0.3.0
+Summary: Documented internals of Devin Desktop/CLI session stores, schema-version detection and test fixtures (unofficial)
+Author: Icaro0310
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+<img src="assets/banner.svg" alt="devin-internals-spec" width="100%"/>
+
+<a href="https://github.com/Icaro0310/devin-internals-spec/actions/workflows/tests.yml"><img src="https://github.com/Icaro0310/devin-internals-spec/actions/workflows/tests.yml/badge.svg" alt="tests"/></a>
+<a href="https://scorecard.dev/viewer/?uri=github.com/Icaro0310/devin-internals-spec"><img src="https://api.scorecard.dev/projects/github.com/Icaro0310/devin-internals-spec/badge" alt="OpenSSF Scorecard"/></a>
+
+
+</div>
+
+# devin-internals-spec
+
+> **Unofficial community project.** Not affiliated with, endorsed by, or
+> sponsored by Cognition AI. "Devin" is a trademark of Cognition AI.
+
+**[Português (BR)](README.pt-BR.md)** · English
+
+A documented map of Devin's local session stores — the CLI `sessions.db`, the
+Desktop GUI `acp-messages/*.db` and `state.vscdb` — plus a schema-version
+detector and deterministic synthetic fixtures, so tooling fails loudly instead
+of silently misreading your data.
+
+## The problem
+
+Everything Devin stores on your disk is kept in undocumented SQLite databases
+whose schema **changes without notice**: `sessions.db` has already gone through
+**17 migrations** (v1–v15 on 2026-05-06, v16 on 2026-07-05, v17 on 2026-09-14).
+Any tool that reads these stores has to reverse-engineer the format — and when
+Cognition ships the next migration, those tools break *silently*: wrong counts,
+missed rows, or corrupted interpretation, with no error raised.
+
+The Devin Desktop app is worse off than the CLI: its stores
+(`acp-messages/*.db`, `state.vscdb`, session locks, the
+`refinery_schema_history` migration ledger) are not documented anywhere.
+
+## Prior art
+
+Session-log tooling exists for other agent CLIs — e.g. **tokmesh** and
+**UniSessions** document and parse Devin's CLI `sessions.db`. This project does
+not reinvent that: it borrows the same idea (SQLite schema → typed parsing) and
+extends it to what those tools don't cover — the Desktop GUI stores — and adds
+the piece they lack: an explicit **schema-version gate** so a parser refuses to
+run against a schema it has never seen.
+
+## What makes it Devin-native
+
+The differentiator, in one sentence: *it's the map of what Devin keeps on your
+disk — and it warns you when that changes.*
+
+1. **Side-by-side:** it covers `acp-messages/*.db`, `state.vscdb`
+   (`windsurfSpace.*` keys) and `refinery_schema_history`, which no existing
+   tool documents.
+2. **No-Devin:** remove Devin and there is no store to document — the extra
+   disappears entirely.
+3. **Loud failure:** `detect_schema_version()` returns a version contract and
+   raises on anything unknown, instead of guessing at bytes.
+
+## Install
+
+Python ≥ 3.10 and `pipx` are required. **Windows (PowerShell):** install `pipx` with `py -m pip install --user pipx`, run `py -m pipx ensurepath`, then reopen the terminal. **Linux (Debian/Ubuntu):** run `sudo apt install pipx python3-venv` and `pipx ensurepath`; reopen the terminal. Other Linux distributions should install `pipx` using their package manager.
+
+```bash
+pipx install "devin-internals-spec @ git+https://github.com/Icaro0310/devin-internals-spec.git"
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Usage
+
+```bash
+devin-inspect schema   <sessions.db>      # schema-detection contract (JSON)
+devin-inspect sessions <sessions.db>      # list sessions (id, title, cwd, …)
+devin-inspect health   <devin-data-dir>   # locate + check all three stores
+devin-inspect contract <devin-data-dir>   # unified drift check: schema +
+                                          # acp meta + usage shape, one report
+devin-inspect make-fixture <out>          # deterministic synthetic stores
+                                          # for tests/demos (--kind, --seed,
+                                          # --schema-version, --n-sessions)
+```
+
+`contract` is the single drift boundary for the whole catalog: it reports
+`sessions.db` schema version, `acp-messages` meta `schema_version` (observed:
+6; 1 on legacy DBs) and unexpected meta keys, and the verified usage shape
+(no cost persisted — `num_tokens_preceding` only). On Linux it resolves the
+split layout automatically (`~/.local/share/devin` data root +
+`~/.config/Devin` GUI root). Exit code is non-zero on any drift.
+
+`AcpMessagesStore.typed_meta()` decodes the `meta` table into a typed
+view (`schema_version` normalized to int, `message_count`, `truncated`,
+`title` from the `info` JSON blob) with `raw` as fallback.
+`devin_internals.projects` gives the canonical project key/path used to
+join sessions across tools, and `devin_internals.commits.commit_references()`
+extracts git commit SHAs (40-hex + `/commit/<sha>` URLs, with repo context)
+from `tool_call_state` payloads — short SHAs are ignored on purpose
+(precision over recall for graph joins).
+
+Every subcommand is read-only and accepts `--json`. The Python library is the
+supported interface — the CLI is a thin wrapper:
+
+```python
+import os
+import sys
+from pathlib import Path
+from devin_internals import detect_schema_version
+from devin_internals.parsers import SessionsStore
+
+if os.name == "nt":
+    root = Path(os.environ["APPDATA"]) / "devin"
+elif sys.platform == "darwin":
+    root = Path.home() / "Library" / "Application Support" / "devin"
+else:
+    data_home = Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local/share"))
+    root = data_home / "devin"
+sessions_db = root / "cli" / "sessions.db"
+
+detect_schema_version(sessions_db)
+# {"schema_version": 17, "known": True, "min_supported": 15, ...}
+
+with SessionsStore(sessions_db) as store:
+    store.sessions()  # typed dataclasses
+```
+
+## Works with Devin alone (Devin-only mode)
+
+The spec is documentation plus a small local validation library: it reads
+Devin's stores to report the schema version and gates tools when the version
+is newer than what is known — it stops loudly instead of misparsing. Purely
+local; nothing external is needed.
+
+## Platform support
+
+Pure stdlib Python — identical behavior on Windows, Linux and macOS. CI runs
+the suite on `windows-latest` + `ubuntu-latest`; the target file or
+directory is always an explicit argument, so there are no
+platform-specific paths.
+
+
+### `vscdb-scan` — shape-only audit (IS-1)
+
+`devin-internals vscdb-scan <state.vscdb>` audits the GUI key/value store
+and reports, per key: name, value *shape* (json-object/array/string/…),
+length, top-level JSON keys and risk flags (`sensitive-key-name`,
+`looks-like-jwt`, `large-blob`). **Values are never printed** — flags are
+heuristic and recall-biased; a real audit confirmed `state.vscdb` can
+hold auth tokens and PII. `--fail-on-flags` exits 1 for CI.
+
+## Limitations
+
+- **Private, volatile internals.** These stores are implementation details of
+  Devin; the schema can change in any release. Only what is marked "verified"
+  in `docs/SPEC.md` should be relied on.
+- **Verified against schema v17** only (the latest at time of writing). The
+  detector *refuses* versions it doesn't know — that's a feature, but it means
+  new Devin releases will break detection until the spec is updated.
+- **Read-only.** This project never writes to Devin's databases.
+- **Not a session exporter.** It documents and guards the format; it does not
+  dump your conversations (that is `devin-history`'s job).
+- Fixtures contain **synthetic data only** — no real session content is ever
+  copied, by design.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Ground rules in [CONTRIBUTING.md](CONTRIBUTING.md): fixtures before parsers,
+small commits, bilingual docs.
+
+## When to use this
+
+- You are building a tool that reads Devin's local stores and need the documented schema, not reverse-engineering.
+- You want a schema-version gate: `detect_schema_version()` refuses loudly on unknown versions instead of misparsing.
+- You need deterministic synthetic fixtures to test parsers — no real session data required.
+- You need typed, read-only access to `sessions.db` via `SessionsStore` in Python.
+
+## When NOT to use this
+
+- You want to export or dump sessions — this documents and guards the format; `devin-history` does the exporting.
+- Your Devin release ships a schema newer than v17 — the detector refuses by design until the spec catches up.
+- You need writes — every parser and subcommand is strictly read-only.
+
+## FAQ
+
+**What data does Devin store locally, and where?** Per this spec: a versioned `sessions.db` under `cli/` (sessions, tool-call state, transcripts), one `acp-messages/*.db` per GUI session, a `state.vscdb` KV store with `windsurfSpace.*` keys, `credentials.toml`, and a `refinery_schema_history` migration ledger. The verified details live in `docs/SPEC.md`.
+
+**What happens when Devin ships a new schema version?** Tools using this library fail loudly, not silently. `detect_schema_version()` returns a contract (`known`, `min_supported`) and raises on versions it does not recognize — verified against schema v17 at time of writing.
+
+**How is this different from other sessions.db parsers?** It also documents the Desktop GUI stores (`acp-messages/*.db`, `state.vscdb`, session locks, the migration ledger) that other tools don't cover, and adds the explicit schema-version gate. The library is the supported interface; `devin-inspect` is a thin CLI wrapper.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+
+---
+
+If this saved you debugging time, a ⭐ on the repo helps others find it.

devin_internals_spec-0.3.0/README.md

@@ -0,0 +1,204 @@
+<div align="center">
+
+<img src="assets/banner.svg" alt="devin-internals-spec" width="100%"/>
+
+<a href="https://github.com/Icaro0310/devin-internals-spec/actions/workflows/tests.yml"><img src="https://github.com/Icaro0310/devin-internals-spec/actions/workflows/tests.yml/badge.svg" alt="tests"/></a>
+<a href="https://scorecard.dev/viewer/?uri=github.com/Icaro0310/devin-internals-spec"><img src="https://api.scorecard.dev/projects/github.com/Icaro0310/devin-internals-spec/badge" alt="OpenSSF Scorecard"/></a>
+
+
+</div>
+
+# devin-internals-spec
+
+> **Unofficial community project.** Not affiliated with, endorsed by, or
+> sponsored by Cognition AI. "Devin" is a trademark of Cognition AI.
+
+**[Português (BR)](README.pt-BR.md)** · English
+
+A documented map of Devin's local session stores — the CLI `sessions.db`, the
+Desktop GUI `acp-messages/*.db` and `state.vscdb` — plus a schema-version
+detector and deterministic synthetic fixtures, so tooling fails loudly instead
+of silently misreading your data.
+
+## The problem
+
+Everything Devin stores on your disk is kept in undocumented SQLite databases
+whose schema **changes without notice**: `sessions.db` has already gone through
+**17 migrations** (v1–v15 on 2026-05-06, v16 on 2026-07-05, v17 on 2026-09-14).
+Any tool that reads these stores has to reverse-engineer the format — and when
+Cognition ships the next migration, those tools break *silently*: wrong counts,
+missed rows, or corrupted interpretation, with no error raised.
+
+The Devin Desktop app is worse off than the CLI: its stores
+(`acp-messages/*.db`, `state.vscdb`, session locks, the
+`refinery_schema_history` migration ledger) are not documented anywhere.
+
+## Prior art
+
+Session-log tooling exists for other agent CLIs — e.g. **tokmesh** and
+**UniSessions** document and parse Devin's CLI `sessions.db`. This project does
+not reinvent that: it borrows the same idea (SQLite schema → typed parsing) and
+extends it to what those tools don't cover — the Desktop GUI stores — and adds
+the piece they lack: an explicit **schema-version gate** so a parser refuses to
+run against a schema it has never seen.
+
+## What makes it Devin-native
+
+The differentiator, in one sentence: *it's the map of what Devin keeps on your
+disk — and it warns you when that changes.*
+
+1. **Side-by-side:** it covers `acp-messages/*.db`, `state.vscdb`
+   (`windsurfSpace.*` keys) and `refinery_schema_history`, which no existing
+   tool documents.
+2. **No-Devin:** remove Devin and there is no store to document — the extra
+   disappears entirely.
+3. **Loud failure:** `detect_schema_version()` returns a version contract and
+   raises on anything unknown, instead of guessing at bytes.
+
+## Install
+
+Python ≥ 3.10 and `pipx` are required. **Windows (PowerShell):** install `pipx` with `py -m pip install --user pipx`, run `py -m pipx ensurepath`, then reopen the terminal. **Linux (Debian/Ubuntu):** run `sudo apt install pipx python3-venv` and `pipx ensurepath`; reopen the terminal. Other Linux distributions should install `pipx` using their package manager.
+
+```bash
+pipx install "devin-internals-spec @ git+https://github.com/Icaro0310/devin-internals-spec.git"
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Usage
+
+```bash
+devin-inspect schema   <sessions.db>      # schema-detection contract (JSON)
+devin-inspect sessions <sessions.db>      # list sessions (id, title, cwd, …)
+devin-inspect health   <devin-data-dir>   # locate + check all three stores
+devin-inspect contract <devin-data-dir>   # unified drift check: schema +
+                                          # acp meta + usage shape, one report
+devin-inspect make-fixture <out>          # deterministic synthetic stores
+                                          # for tests/demos (--kind, --seed,
+                                          # --schema-version, --n-sessions)
+```
+
+`contract` is the single drift boundary for the whole catalog: it reports
+`sessions.db` schema version, `acp-messages` meta `schema_version` (observed:
+6; 1 on legacy DBs) and unexpected meta keys, and the verified usage shape
+(no cost persisted — `num_tokens_preceding` only). On Linux it resolves the
+split layout automatically (`~/.local/share/devin` data root +
+`~/.config/Devin` GUI root). Exit code is non-zero on any drift.
+
+`AcpMessagesStore.typed_meta()` decodes the `meta` table into a typed
+view (`schema_version` normalized to int, `message_count`, `truncated`,
+`title` from the `info` JSON blob) with `raw` as fallback.
+`devin_internals.projects` gives the canonical project key/path used to
+join sessions across tools, and `devin_internals.commits.commit_references()`
+extracts git commit SHAs (40-hex + `/commit/<sha>` URLs, with repo context)
+from `tool_call_state` payloads — short SHAs are ignored on purpose
+(precision over recall for graph joins).
+
+Every subcommand is read-only and accepts `--json`. The Python library is the
+supported interface — the CLI is a thin wrapper:
+
+```python
+import os
+import sys
+from pathlib import Path
+from devin_internals import detect_schema_version
+from devin_internals.parsers import SessionsStore
+
+if os.name == "nt":
+    root = Path(os.environ["APPDATA"]) / "devin"
+elif sys.platform == "darwin":
+    root = Path.home() / "Library" / "Application Support" / "devin"
+else:
+    data_home = Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local/share"))
+    root = data_home / "devin"
+sessions_db = root / "cli" / "sessions.db"
+
+detect_schema_version(sessions_db)
+# {"schema_version": 17, "known": True, "min_supported": 15, ...}
+
+with SessionsStore(sessions_db) as store:
+    store.sessions()  # typed dataclasses
+```
+
+## Works with Devin alone (Devin-only mode)
+
+The spec is documentation plus a small local validation library: it reads
+Devin's stores to report the schema version and gates tools when the version
+is newer than what is known — it stops loudly instead of misparsing. Purely
+local; nothing external is needed.
+
+## Platform support
+
+Pure stdlib Python — identical behavior on Windows, Linux and macOS. CI runs
+the suite on `windows-latest` + `ubuntu-latest`; the target file or
+directory is always an explicit argument, so there are no
+platform-specific paths.
+
+
+### `vscdb-scan` — shape-only audit (IS-1)
+
+`devin-internals vscdb-scan <state.vscdb>` audits the GUI key/value store
+and reports, per key: name, value *shape* (json-object/array/string/…),
+length, top-level JSON keys and risk flags (`sensitive-key-name`,
+`looks-like-jwt`, `large-blob`). **Values are never printed** — flags are
+heuristic and recall-biased; a real audit confirmed `state.vscdb` can
+hold auth tokens and PII. `--fail-on-flags` exits 1 for CI.
+
+## Limitations
+
+- **Private, volatile internals.** These stores are implementation details of
+  Devin; the schema can change in any release. Only what is marked "verified"
+  in `docs/SPEC.md` should be relied on.
+- **Verified against schema v17** only (the latest at time of writing). The
+  detector *refuses* versions it doesn't know — that's a feature, but it means
+  new Devin releases will break detection until the spec is updated.
+- **Read-only.** This project never writes to Devin's databases.
+- **Not a session exporter.** It documents and guards the format; it does not
+  dump your conversations (that is `devin-history`'s job).
+- Fixtures contain **synthetic data only** — no real session content is ever
+  copied, by design.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Ground rules in [CONTRIBUTING.md](CONTRIBUTING.md): fixtures before parsers,
+small commits, bilingual docs.
+
+## When to use this
+
+- You are building a tool that reads Devin's local stores and need the documented schema, not reverse-engineering.
+- You want a schema-version gate: `detect_schema_version()` refuses loudly on unknown versions instead of misparsing.
+- You need deterministic synthetic fixtures to test parsers — no real session data required.
+- You need typed, read-only access to `sessions.db` via `SessionsStore` in Python.
+
+## When NOT to use this
+
+- You want to export or dump sessions — this documents and guards the format; `devin-history` does the exporting.
+- Your Devin release ships a schema newer than v17 — the detector refuses by design until the spec catches up.
+- You need writes — every parser and subcommand is strictly read-only.
+
+## FAQ
+
+**What data does Devin store locally, and where?** Per this spec: a versioned `sessions.db` under `cli/` (sessions, tool-call state, transcripts), one `acp-messages/*.db` per GUI session, a `state.vscdb` KV store with `windsurfSpace.*` keys, `credentials.toml`, and a `refinery_schema_history` migration ledger. The verified details live in `docs/SPEC.md`.
+
+**What happens when Devin ships a new schema version?** Tools using this library fail loudly, not silently. `detect_schema_version()` returns a contract (`known`, `min_supported`) and raises on versions it does not recognize — verified against schema v17 at time of writing.
+
+**How is this different from other sessions.db parsers?** It also documents the Desktop GUI stores (`acp-messages/*.db`, `state.vscdb`, session locks, the migration ledger) that other tools don't cover, and adds the explicit schema-version gate. The library is the supported interface; `devin-inspect` is a thin CLI wrapper.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+
+---
+
+If this saved you debugging time, a ⭐ on the repo helps others find it.

devin_internals_spec-0.3.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "devin-internals-spec"
+version = "0.3.0"
+description = "Documented internals of Devin Desktop/CLI session stores, schema-version detection and test fixtures (unofficial)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Icaro0310" }]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+devin-inspect = "devin_internals.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

devin_internals_spec-0.3.0/setup.cfg

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

devin_internals_spec-0.3.0/src/devin_internals/__init__.py

@@ -0,0 +1,20 @@
+__version__ = "0.3.0"
+
+from devin_internals.schema import (
+    LATEST_KNOWN_SCHEMA,
+    MIN_SUPPORTED_SCHEMA,
+    SchemaDetectionError,
+    SchemaError,
+    UnknownSchemaVersionError,
+    detect_schema_version,
+)
+
+__all__ = [
+    "LATEST_KNOWN_SCHEMA",
+    "MIN_SUPPORTED_SCHEMA",
+    "SchemaDetectionError",
+    "SchemaError",
+    "UnknownSchemaVersionError",
+    "detect_schema_version",
+    "__version__",
+]