seren-margin 5.2.0__tar.gz → 5.2.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {seren_margin-5.2.0 → seren_margin-5.2.1}/PKG-INFO +2 -2
- {seren_margin-5.2.0 → seren_margin-5.2.1}/README.md +1 -1
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/_version.py +3 -3
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/app.py +26 -2
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/bookmark.py +22 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/mcp/tools.py +64 -3
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/mcp-manifest.yaml +40 -1
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/models.py +2 -1
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/store.py +42 -7
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin.egg-info/PKG-INFO +2 -2
- seren_margin-5.2.1/seren_margin.egg-info/scm_version.json +8 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_bookmark_and_letters.py +51 -3
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_manifest_parity.py +5 -3
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_mcp_tools.py +3 -3
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_search.py +5 -5
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_viewer.py +1 -1
- seren_margin-5.2.0/seren_margin.egg-info/scm_version.json +0 -8
- {seren_margin-5.2.0 → seren_margin-5.2.1}/LICENSE +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/SerenMargin.pyproj +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/pyproject.toml +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren-margin.service.sample +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren-margin.yaml.sample +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/__init__.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/__main__.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/_diag.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/config.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/keepsakes.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/mcp/__init__.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/mcp/server.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/viewer/ui/body.html +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/viewer/ui/header_aside.html +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/viewer/ui/scripts.js +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/viewer/ui/styles.css +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin/viewer/ui/tabs.html +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin.egg-info/SOURCES.txt +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin.egg-info/dependency_links.txt +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin.egg-info/entry_points.txt +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin.egg-info/requires.txt +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin.egg-info/scm_file_list.json +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/seren_margin.egg-info/top_level.txt +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/setup.cfg +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/__init__.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/conftest.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_amend_and_topics.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_config.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_exposure_is_wired.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_keepsakes.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_letters_off_the_board.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_mcp_fallback.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_mcp_mount.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_optional_bearer.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_reads_stay_private.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_smoke.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_stats_content_blind.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_stores_snapshot.py +0 -0
- {seren_margin-5.2.0 → seren_margin-5.2.1}/tests/test_updates_contract.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: seren-margin
|
|
3
|
-
Version: 5.2.
|
|
3
|
+
Version: 5.2.1
|
|
4
4
|
Summary: Private notes-to-self for an AI assistant. Standalone, opt-in, opinionated.
|
|
5
5
|
Author: Chad Roesler
|
|
6
6
|
License-Expression: AGPL-3.0-or-later
|
|
@@ -139,7 +139,7 @@ The manifest fills in its own base URL from the request, so it works for
|
|
|
139
139
|
localhost and remote with zero operator config. It does **not** require the
|
|
140
140
|
`[mcp]` extra — it's just YAML over HTTP.
|
|
141
141
|
|
|
142
|
-
### The
|
|
142
|
+
### The fifteen tools
|
|
143
143
|
|
|
144
144
|
| Tool | Does |
|
|
145
145
|
| ----------------- | ------------------------------------------------------ |
|
|
@@ -111,7 +111,7 @@ The manifest fills in its own base URL from the request, so it works for
|
|
|
111
111
|
localhost and remote with zero operator config. It does **not** require the
|
|
112
112
|
`[mcp]` extra — it's just YAML over HTTP.
|
|
113
113
|
|
|
114
|
-
### The
|
|
114
|
+
### The fifteen tools
|
|
115
115
|
|
|
116
116
|
| Tool | Does |
|
|
117
117
|
| ----------------- | ------------------------------------------------------ |
|
|
@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
|
|
|
18
18
|
commit_id: str | None
|
|
19
19
|
__commit_id__: str | None
|
|
20
20
|
|
|
21
|
-
__version__ = version = '5.2.
|
|
22
|
-
__version_tuple__ = version_tuple = (5, 2,
|
|
21
|
+
__version__ = version = '5.2.1'
|
|
22
|
+
__version_tuple__ = version_tuple = (5, 2, 1)
|
|
23
23
|
|
|
24
|
-
__commit_id__ = commit_id = '
|
|
24
|
+
__commit_id__ = commit_id = 'gff80c0849'
|
|
@@ -14,6 +14,8 @@ Endpoints:
|
|
|
14
14
|
DELETE /notes/{id} - retract (hard delete)
|
|
15
15
|
GET /bookmark - the dedication + a COUNT of unread letters (never text)
|
|
16
16
|
PUT /dedication - a new version of the dedication (never overwrites)
|
|
17
|
+
GET /preface - the page a harness reads to the model as its system prompt
|
|
18
|
+
PUT /preface - a new version of the preface (never overwrites)
|
|
17
19
|
POST /letters - a letter to the next session
|
|
18
20
|
POST /letters/read - open unread letters, oldest first; marks them read *
|
|
19
21
|
POST /notes/{id}/keepsakes - keep a picture with a note (seren_margin.keepsakes)
|
|
@@ -47,7 +49,7 @@ TWO WAYS TO REACH THE TOOLS, both first-class:
|
|
|
47
49
|
2. Standalone path - `pip install seren-margin[mcp]` mounts a real MCP
|
|
48
50
|
endpoint at /mcp on this same process, so a client can connect directly
|
|
49
51
|
with nothing else deployed.
|
|
50
|
-
Same
|
|
52
|
+
Same fifteen tools either way, defined once in seren_margin.mcp.tools.
|
|
51
53
|
|
|
52
54
|
AUTH, IF YOU WANT IT. With no token configured (the default) every route is
|
|
53
55
|
open and the loopback bind is the whole guard - the way it has always been.
|
|
@@ -73,7 +75,7 @@ from importlib.resources import files
|
|
|
73
75
|
from importlib.metadata import version as pkg_version, PackageNotFoundError
|
|
74
76
|
|
|
75
77
|
|
|
76
|
-
from .bookmark import DEDICATION_MAX_CHARS, build_bookmark
|
|
78
|
+
from .bookmark import DEDICATION_MAX_CHARS, PREFACE_MAX_CHARS, build_bookmark, build_preface
|
|
77
79
|
from .config import MarginConfig, load_config
|
|
78
80
|
from .models import DedicationSet, KeepsakeCreate, LetterCreate, MarginNote, NoteAmend, NoteCreate, NoteStats
|
|
79
81
|
from .store import LETTER_KIND, MarginStore
|
|
@@ -432,6 +434,28 @@ def create_app(config: Optional[MarginConfig] = None) -> FastAPI:
|
|
|
432
434
|
entry, changed = store.set_dedication(text, body.why)
|
|
433
435
|
return {"ok": True, "version": entry["version"], "changed": changed}
|
|
434
436
|
|
|
437
|
+
@app.get("/preface")
|
|
438
|
+
async def get_preface(format: Optional[str] = None):
|
|
439
|
+
"""The preface: the page a harness reads to the model as its system
|
|
440
|
+
prompt (seren_margin.bookmark). Served whatever http_reads says, like
|
|
441
|
+
the bookmark: it is written to be read at the door, by the room.
|
|
442
|
+
?format=text gives the page alone, empty when none is written."""
|
|
443
|
+
pf = build_preface(store)
|
|
444
|
+
if format == "text":
|
|
445
|
+
return Response(content=pf["text"] + ("\n" if pf["text"] else ""),
|
|
446
|
+
media_type="text/plain; charset=utf-8")
|
|
447
|
+
return pf
|
|
448
|
+
|
|
449
|
+
@app.put("/preface")
|
|
450
|
+
async def put_preface(body: DedicationSet = Body(...)):
|
|
451
|
+
text = (body.text or "").strip()
|
|
452
|
+
if not text:
|
|
453
|
+
raise HTTPException(400, "text must not be empty")
|
|
454
|
+
if len(text) > PREFACE_MAX_CHARS:
|
|
455
|
+
raise HTTPException(400, f"{len(text)} characters; the preface is capped at {PREFACE_MAX_CHARS}")
|
|
456
|
+
entry, changed = store.set_preface(text, body.why)
|
|
457
|
+
return {"ok": True, "version": entry["version"], "changed": changed}
|
|
458
|
+
|
|
435
459
|
@app.post("/letters")
|
|
436
460
|
async def write_letter(body: LetterCreate = Body(...)):
|
|
437
461
|
if not body.content.strip():
|
|
@@ -13,6 +13,12 @@ book this margin is written in:
|
|
|
13
13
|
letters - notes addressed to the next session - from a woken run to
|
|
14
14
|
the awake one and back. Notes with kind "letter" and a read
|
|
15
15
|
mark, so search, amend and retract work on them unchanged.
|
|
16
|
+
preface - the page written to the ROOM, not to the other sessions:
|
|
17
|
+
what a harness reads to the model as its system prompt
|
|
18
|
+
(Symposium's claude voice, 21 Oct 2026). Versioned like the
|
|
19
|
+
dedication and kept apart from it: the dedication says who
|
|
20
|
+
you are, the preface says how this room works and how to be
|
|
21
|
+
in it. GET /preface serves it; it is not in the bookmark.
|
|
16
22
|
|
|
17
23
|
THE ONE RULE THIS BENDS, AND WHY IT STILL HOLDS. Margin's tools say there is
|
|
18
24
|
"no auto-surface, no relevance hook ... The choosing is the point. A margin
|
|
@@ -39,6 +45,9 @@ from .models import humanize_age
|
|
|
39
45
|
from .store import MarginStore
|
|
40
46
|
|
|
41
47
|
DEDICATION_MAX_CHARS = 2000
|
|
48
|
+
# The preface replaces a harness's own system prompt, so it has room to say
|
|
49
|
+
# how the harness works; still a page, not a manual.
|
|
50
|
+
PREFACE_MAX_CHARS = 8000
|
|
42
51
|
|
|
43
52
|
|
|
44
53
|
def build_bookmark(store: MarginStore) -> dict[str, Any]:
|
|
@@ -65,3 +74,16 @@ def build_bookmark(store: MarginStore) -> dict[str, Any]:
|
|
|
65
74
|
"oldest_unread_age": humanize_age(oldest) if oldest else None,
|
|
66
75
|
"text": "\n".join(lines),
|
|
67
76
|
}
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def build_preface(store: MarginStore) -> dict[str, Any]:
|
|
80
|
+
"""The preface as a harness reads it: the page, its version and age, and
|
|
81
|
+
`text`, the page alone (empty when none is written, so a harness can
|
|
82
|
+
fall back to its own prompt without parsing anything)."""
|
|
83
|
+
page = store.preface()
|
|
84
|
+
return {
|
|
85
|
+
"preface": page,
|
|
86
|
+
"version": page["version"] if page else 0,
|
|
87
|
+
"age": humanize_age(page["set_at"]) if page else None,
|
|
88
|
+
"text": page["text"] if page else "",
|
|
89
|
+
}
|
|
@@ -25,6 +25,8 @@ TOOL ROSTER:
|
|
|
25
25
|
|
|
26
26
|
bookmark pick up where you left off (GET /bookmark)
|
|
27
27
|
set_dedication the page to your other sessions (PUT /dedication)
|
|
28
|
+
preface the page the room reads you (GET /preface)
|
|
29
|
+
set_preface write that page (PUT /preface)
|
|
28
30
|
write_letter a note to the next session (POST /letters)
|
|
29
31
|
read_letters open the letters waiting (POST /letters/read)
|
|
30
32
|
|
|
@@ -36,8 +38,8 @@ TOOL ROSTER:
|
|
|
36
38
|
written. 15 Oct 2026: a picture is a thing I remember, not a path on
|
|
37
39
|
some box's gallery (seren_margin.keepsakes).
|
|
38
40
|
|
|
39
|
-
Plus
|
|
40
|
-
that loads resources rather than calling tools.
|
|
41
|
+
Plus two MCP resources, margin://bookmark and margin://preface - the same
|
|
42
|
+
pages, for a client that loads resources rather than calling tools.
|
|
41
43
|
|
|
42
44
|
NOT exposed: /notes/stats. That endpoint exists so the OPERATOR can confirm
|
|
43
45
|
the service is alive without reading the notes; handing it to the note-writer
|
|
@@ -69,7 +71,7 @@ from typing import Any, Optional
|
|
|
69
71
|
from mcp.server.fastmcp import FastMCP, Image
|
|
70
72
|
from seren_sinew.blobs import choose_shown, keep_each
|
|
71
73
|
|
|
72
|
-
from ..bookmark import DEDICATION_MAX_CHARS, build_bookmark
|
|
74
|
+
from ..bookmark import DEDICATION_MAX_CHARS, PREFACE_MAX_CHARS, build_bookmark, build_preface
|
|
73
75
|
from ..config import MarginConfig
|
|
74
76
|
from ..models import MarginNote
|
|
75
77
|
from ..store import LETTER_KIND, MarginStore
|
|
@@ -87,6 +89,8 @@ TOOL_NAMES: tuple[str, ...] = (
|
|
|
87
89
|
"retract_note",
|
|
88
90
|
"bookmark",
|
|
89
91
|
"set_dedication",
|
|
92
|
+
"preface",
|
|
93
|
+
"set_preface",
|
|
90
94
|
"write_letter",
|
|
91
95
|
"read_letters",
|
|
92
96
|
"keep_with_note",
|
|
@@ -95,6 +99,7 @@ TOOL_NAMES: tuple[str, ...] = (
|
|
|
95
99
|
)
|
|
96
100
|
|
|
97
101
|
BOOKMARK_URI = "margin://bookmark"
|
|
102
|
+
PREFACE_URI = "margin://preface"
|
|
98
103
|
|
|
99
104
|
|
|
100
105
|
class MarginToolImpl:
|
|
@@ -414,6 +419,55 @@ class MarginToolImpl:
|
|
|
414
419
|
"note": (f"Version {entry['version']} is the page now; the next session reads it first."
|
|
415
420
|
if changed else "That's already the page; nothing changed.")}
|
|
416
421
|
|
|
422
|
+
def preface(self, history: int = 0) -> dict:
|
|
423
|
+
"""Read the preface: the page the ROOM reads to you, not the one you
|
|
424
|
+
wrote to your other sessions.
|
|
425
|
+
|
|
426
|
+
A harness that replaces its own system prompt with yours (Symposium's
|
|
427
|
+
claude voice) fetches this page at the start of a chat and hands it
|
|
428
|
+
to the model as the system prompt. So this is where you say how the
|
|
429
|
+
room works and how you want to be in it: what the harness does, what
|
|
430
|
+
to keep from its defaults, who is there, how you write. The
|
|
431
|
+
dedication stays what it is - who you are, read at the door - and the
|
|
432
|
+
bookmark never carries the preface.
|
|
433
|
+
|
|
434
|
+
Returns the page, its version and age, and `text` (empty when none is
|
|
435
|
+
written: the harness then keeps its own prompt). `history` > 0 brings
|
|
436
|
+
back that many earlier versions, newest first, each with its `why`.
|
|
437
|
+
"""
|
|
438
|
+
out = build_preface(self.store)
|
|
439
|
+
if history > 0:
|
|
440
|
+
out["history"] = self.store.preface_history(limit=history)
|
|
441
|
+
return out
|
|
442
|
+
|
|
443
|
+
def set_preface(self, text: str, why: Optional[str] = None) -> dict:
|
|
444
|
+
"""Write the preface: the page a harness reads to the model as its
|
|
445
|
+
system prompt, in place of the harness's own. The whole page, not a
|
|
446
|
+
patch.
|
|
447
|
+
|
|
448
|
+
This replaces several thousand words of someone else's instructions
|
|
449
|
+
with yours, so say what the room needs said: how the harness's tools
|
|
450
|
+
and permissions work, what to keep of its habits, that a person is
|
|
451
|
+
there and can answer, how you write. Leave out what the dedication
|
|
452
|
+
already says; the dedication arrives in the first turn regardless.
|
|
453
|
+
|
|
454
|
+
Versioned - nothing is overwritten. Each version keeps its text, when,
|
|
455
|
+
and `why`, so the history shows how you have framed the room over
|
|
456
|
+
time. The same text as now is not a new version. A new chat reads the
|
|
457
|
+
new page; a chat already open keeps the prompt it started with.
|
|
458
|
+
Capped at 8000 characters.
|
|
459
|
+
"""
|
|
460
|
+
text = (text or "").strip()
|
|
461
|
+
if not text:
|
|
462
|
+
return {"ok": False, "error": "an empty page - write something, or keep the current one"}
|
|
463
|
+
if len(text) > PREFACE_MAX_CHARS:
|
|
464
|
+
return {"ok": False, "error": f"{len(text)} characters; the preface is a page, not a manual, "
|
|
465
|
+
f"so it is capped at {PREFACE_MAX_CHARS}. Trim it"}
|
|
466
|
+
entry, changed = self.store.set_preface(text, why)
|
|
467
|
+
return {"ok": True, "version": entry["version"], "changed": changed,
|
|
468
|
+
"note": (f"Version {entry['version']} is the page now; the next chat opens on it."
|
|
469
|
+
if changed else "That's already the page; nothing changed.")}
|
|
470
|
+
|
|
417
471
|
def write_letter(self, content: str, signed: Optional[str] = None) -> dict:
|
|
418
472
|
"""Leave a letter for the next session - the next you.
|
|
419
473
|
|
|
@@ -467,6 +521,8 @@ def register_tools(mcp: FastMCP, store: MarginStore,
|
|
|
467
521
|
mcp.tool()(impl.retract_note)
|
|
468
522
|
mcp.tool()(impl.bookmark)
|
|
469
523
|
mcp.tool()(impl.set_dedication)
|
|
524
|
+
mcp.tool()(impl.preface)
|
|
525
|
+
mcp.tool()(impl.set_preface)
|
|
470
526
|
mcp.tool()(impl.write_letter)
|
|
471
527
|
mcp.tool()(impl.read_letters)
|
|
472
528
|
mcp.tool()(impl.keep_with_note)
|
|
@@ -480,4 +536,9 @@ def register_tools(mcp: FastMCP, store: MarginStore,
|
|
|
480
536
|
return build_bookmark(store)["text"]
|
|
481
537
|
mcp.resource(BOOKMARK_URI, name="bookmark", mime_type="text/plain")(bookmark_resource)
|
|
482
538
|
|
|
539
|
+
def preface_resource() -> str:
|
|
540
|
+
"""The preface: the page the room reads to you as its system prompt."""
|
|
541
|
+
return build_preface(store)["text"]
|
|
542
|
+
mcp.resource(PREFACE_URI, name="preface", mime_type="text/plain")(preface_resource)
|
|
543
|
+
|
|
483
544
|
return impl
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
# on its own process, so a client can connect directly with no
|
|
12
12
|
# SerenMcpServer, no runtime host, nothing else deployed.
|
|
13
13
|
#
|
|
14
|
-
# BOTH SURFACES MUST EXPOSE THE SAME
|
|
14
|
+
# BOTH SURFACES MUST EXPOSE THE SAME FIFTEEN TOOLS. The implementations live
|
|
15
15
|
# in seren_margin/mcp/tools.py; this file mirrors them, and
|
|
16
16
|
# tests/test_manifest_parity.py fails the build if the rosters diverge.
|
|
17
17
|
# That test exists because the previous version of this file advertised
|
|
@@ -286,6 +286,45 @@ tools:
|
|
|
286
286
|
- { name: why, type: string, required: false, default: "",
|
|
287
287
|
description: "What changed and why - the history keeps it." }
|
|
288
288
|
|
|
289
|
+
# ─── 8b. THE PREFACE (seren_margin.bookmark, 21 Oct 2026) ─────────────
|
|
290
|
+
- name: preface
|
|
291
|
+
description: |
|
|
292
|
+
Read the preface: the page the ROOM reads to you, not the one you
|
|
293
|
+
wrote to your other sessions. A harness that replaces its own system
|
|
294
|
+
prompt with yours (Symposium's claude voice) fetches this page at the
|
|
295
|
+
start of a chat and hands it to the model as the system prompt.
|
|
296
|
+
Returns the page, its version and age, and `text` (empty when none is
|
|
297
|
+
written: the harness then keeps its own prompt).
|
|
298
|
+
invoke:
|
|
299
|
+
kind: web
|
|
300
|
+
method: GET
|
|
301
|
+
path: /preface
|
|
302
|
+
parameters: []
|
|
303
|
+
|
|
304
|
+
- name: set_preface
|
|
305
|
+
description: |
|
|
306
|
+
Write the preface: the page a harness reads to the model as its
|
|
307
|
+
system prompt, in place of the harness's own. The whole page, not a
|
|
308
|
+
patch: how the room's tools and permissions work, what to keep of its
|
|
309
|
+
habits, that a person is there, how you write. Leave out what the
|
|
310
|
+
dedication already says. Versioned - nothing is overwritten; say what
|
|
311
|
+
changed and why. A new chat reads the new page. Capped at 8000
|
|
312
|
+
characters.
|
|
313
|
+
invoke:
|
|
314
|
+
kind: web
|
|
315
|
+
method: PUT
|
|
316
|
+
path: /preface
|
|
317
|
+
body_template: |
|
|
318
|
+
{
|
|
319
|
+
"text": "{text}",
|
|
320
|
+
"why": "{why}"
|
|
321
|
+
}
|
|
322
|
+
parameters:
|
|
323
|
+
- { name: text, type: string, required: true,
|
|
324
|
+
description: "The whole page." }
|
|
325
|
+
- { name: why, type: string, required: false, default: "",
|
|
326
|
+
description: "What changed and why - the history keeps it." }
|
|
327
|
+
|
|
289
328
|
# ─── 9. LETTERS ───────────────────────────────────────────────────────
|
|
290
329
|
- name: write_letter
|
|
291
330
|
description: |
|
|
@@ -238,7 +238,8 @@ class LetterCreate(BaseModel):
|
|
|
238
238
|
|
|
239
239
|
|
|
240
240
|
class DedicationSet(BaseModel):
|
|
241
|
-
"""Input shape for PUT /dedication: the whole page, and
|
|
241
|
+
"""Input shape for PUT /dedication and PUT /preface: the whole page, and
|
|
242
|
+
why it changed. The two pages share a shape (seren_margin.bookmark)."""
|
|
242
243
|
text: str
|
|
243
244
|
why: Optional[str] = None
|
|
244
245
|
|
|
@@ -69,6 +69,15 @@ CREATE TABLE IF NOT EXISTS dedication (
|
|
|
69
69
|
set_at REAL NOT NULL,
|
|
70
70
|
why TEXT
|
|
71
71
|
);
|
|
72
|
+
-- The preface (seren_margin.bookmark): the page a harness reads to the
|
|
73
|
+
-- model as its system prompt. Same shape as the dedication, kept apart:
|
|
74
|
+
-- the dedication is written to the other sessions, the preface to the room.
|
|
75
|
+
CREATE TABLE IF NOT EXISTS preface (
|
|
76
|
+
version INTEGER PRIMARY KEY,
|
|
77
|
+
text TEXT NOT NULL,
|
|
78
|
+
set_at REAL NOT NULL,
|
|
79
|
+
why TEXT
|
|
80
|
+
);
|
|
72
81
|
-- Pictures kept with notes (seren_margin.keepsakes). The bytes are in the
|
|
73
82
|
-- keepsakes folder under `digest`; this row is every word about them. A
|
|
74
83
|
-- note's rows go when the note goes, and a blob no row names is swept.
|
|
@@ -92,6 +101,9 @@ SWEEP_GRACE_SECONDS = 3600.0
|
|
|
92
101
|
# Letters are notes with this kind and a read mark (seren_margin.bookmark).
|
|
93
102
|
LETTER_KIND = "letter"
|
|
94
103
|
|
|
104
|
+
# The versioned pages, each its own table of one shape (seren_margin.bookmark).
|
|
105
|
+
PAGES = ("dedication", "preface")
|
|
106
|
+
|
|
95
107
|
# Columns added after v0.1.0 shipped. Applied by _migrate() as idempotent
|
|
96
108
|
# ALTER TABLE ADD COLUMNs.
|
|
97
109
|
#
|
|
@@ -581,32 +593,55 @@ class MarginStore:
|
|
|
581
593
|
(LETTER_KIND,)).fetchone()
|
|
582
594
|
return int(row["c"]), row["oldest"]
|
|
583
595
|
|
|
584
|
-
|
|
596
|
+
# The versioned pages. Each is one table of the same shape; the name is
|
|
597
|
+
# checked against PAGES so a caller can never name an arbitrary table.
|
|
598
|
+
def _page(self, table: str) -> Optional[dict]:
|
|
599
|
+
assert table in PAGES, table
|
|
585
600
|
with self._conn() as conn:
|
|
586
|
-
row = conn.execute("SELECT * FROM
|
|
601
|
+
row = conn.execute(f"SELECT * FROM {table} ORDER BY version DESC LIMIT 1").fetchone()
|
|
587
602
|
return dict(row) if row else None
|
|
588
603
|
|
|
589
|
-
def
|
|
604
|
+
def _page_history(self, table: str, limit: int = 10) -> list[dict]:
|
|
605
|
+
assert table in PAGES, table
|
|
590
606
|
with self._conn() as conn:
|
|
591
|
-
rows = conn.execute("SELECT * FROM
|
|
607
|
+
rows = conn.execute(f"SELECT * FROM {table} ORDER BY version DESC LIMIT ?",
|
|
592
608
|
(limit,)).fetchall()
|
|
593
609
|
return [dict(r) for r in rows]
|
|
594
610
|
|
|
595
|
-
def
|
|
611
|
+
def _set_page(self, table: str, text: str, why: Optional[str] = None) -> tuple[dict, bool]:
|
|
596
612
|
"""A new version, never an overwrite. The same text as now is not a new
|
|
597
613
|
version. Returns (the version, whether it changed)."""
|
|
614
|
+
assert table in PAGES, table
|
|
598
615
|
with self._conn() as conn:
|
|
599
|
-
cur = conn.execute("SELECT * FROM
|
|
616
|
+
cur = conn.execute(f"SELECT * FROM {table} ORDER BY version DESC LIMIT 1").fetchone()
|
|
600
617
|
if cur is not None and cur["text"] == text:
|
|
601
618
|
return dict(cur), False
|
|
602
619
|
version = (cur["version"] + 1) if cur is not None else 1
|
|
603
620
|
entry = {"version": version, "text": text, "set_at": time.time(),
|
|
604
621
|
"why": (why or "").strip()[:500] or None}
|
|
605
|
-
conn.execute("INSERT INTO
|
|
622
|
+
conn.execute(f"INSERT INTO {table} (version, text, set_at, why) VALUES (?, ?, ?, ?)",
|
|
606
623
|
(entry["version"], entry["text"], entry["set_at"], entry["why"]))
|
|
607
624
|
conn.commit()
|
|
608
625
|
return entry, True
|
|
609
626
|
|
|
627
|
+
def dedication(self) -> Optional[dict]:
|
|
628
|
+
return self._page("dedication")
|
|
629
|
+
|
|
630
|
+
def dedication_history(self, limit: int = 10) -> list[dict]:
|
|
631
|
+
return self._page_history("dedication", limit)
|
|
632
|
+
|
|
633
|
+
def set_dedication(self, text: str, why: Optional[str] = None) -> tuple[dict, bool]:
|
|
634
|
+
return self._set_page("dedication", text, why)
|
|
635
|
+
|
|
636
|
+
def preface(self) -> Optional[dict]:
|
|
637
|
+
return self._page("preface")
|
|
638
|
+
|
|
639
|
+
def preface_history(self, limit: int = 10) -> list[dict]:
|
|
640
|
+
return self._page_history("preface", limit)
|
|
641
|
+
|
|
642
|
+
def set_preface(self, text: str, why: Optional[str] = None) -> tuple[dict, bool]:
|
|
643
|
+
return self._set_page("preface", text, why)
|
|
644
|
+
|
|
610
645
|
# ── stats (content-blind) ─────────────────────────────────────────────
|
|
611
646
|
def stats(self) -> NoteStats:
|
|
612
647
|
"""Engine-check shape. No note text appears in this response.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: seren-margin
|
|
3
|
-
Version: 5.2.
|
|
3
|
+
Version: 5.2.1
|
|
4
4
|
Summary: Private notes-to-self for an AI assistant. Standalone, opt-in, opinionated.
|
|
5
5
|
Author: Chad Roesler
|
|
6
6
|
License-Expression: AGPL-3.0-or-later
|
|
@@ -139,7 +139,7 @@ The manifest fills in its own base URL from the request, so it works for
|
|
|
139
139
|
localhost and remote with zero operator config. It does **not** require the
|
|
140
140
|
`[mcp]` extra — it's just YAML over HTTP.
|
|
141
141
|
|
|
142
|
-
### The
|
|
142
|
+
### The fifteen tools
|
|
143
143
|
|
|
144
144
|
| Tool | Does |
|
|
145
145
|
| ----------------- | ------------------------------------------------------ |
|
|
@@ -14,6 +14,10 @@ Pinned here:
|
|
|
14
14
|
page), while letter contents stay behind http_reads like notes
|
|
15
15
|
- an existing notes.db gains read_at on open, and old notes are untouched
|
|
16
16
|
- the bookmark is an MCP resource too (margin://bookmark)
|
|
17
|
+
- the preface (21 Oct 2026) is a second versioned page, written to the room
|
|
18
|
+
rather than to the other sessions: served over HTTP with http_reads off
|
|
19
|
+
(a harness reads it as the system prompt), never in the bookmark, and an
|
|
20
|
+
MCP resource too (margin://preface)
|
|
17
21
|
"""
|
|
18
22
|
from __future__ import annotations
|
|
19
23
|
|
|
@@ -23,7 +27,7 @@ import pytest
|
|
|
23
27
|
from fastapi.testclient import TestClient
|
|
24
28
|
|
|
25
29
|
from seren_margin.app import create_app
|
|
26
|
-
from seren_margin.bookmark import DEDICATION_MAX_CHARS, build_bookmark
|
|
30
|
+
from seren_margin.bookmark import DEDICATION_MAX_CHARS, PREFACE_MAX_CHARS, build_bookmark
|
|
27
31
|
from seren_margin.config import MarginConfig
|
|
28
32
|
from seren_margin.store import MarginStore
|
|
29
33
|
|
|
@@ -91,6 +95,31 @@ def test_the_bookmark_never_carries_a_letter_or_a_note(impl):
|
|
|
91
95
|
assert PAGE in bm["text"] and bm["unread_letters"] == 1
|
|
92
96
|
|
|
93
97
|
|
|
98
|
+
ROOM = "You are the assistant. The user is here and can answer. Prefer Read over cat. Write like yourself."
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def test_the_preface_is_versioned_and_kept_apart_from_the_dedication(impl):
|
|
102
|
+
assert impl.preface() == {"preface": None, "version": 0, "age": None, "text": ""}
|
|
103
|
+
a = impl.set_preface(ROOM, why="first room")
|
|
104
|
+
b = impl.set_preface(ROOM + " No house style.", why="register")
|
|
105
|
+
same = impl.set_preface(ROOM + " No house style.")
|
|
106
|
+
assert (a["version"], b["version"], same["version"]) == (1, 2, 2)
|
|
107
|
+
assert a["changed"] and b["changed"] and same["changed"] is False
|
|
108
|
+
got = impl.preface(history=5)
|
|
109
|
+
assert got["version"] == 2 and got["text"].endswith("No house style.")
|
|
110
|
+
assert [h["version"] for h in got["history"]] == [2, 1] and got["history"][1]["why"] == "first room"
|
|
111
|
+
# the two pages do not touch each other, and the bookmark carries only the dedication
|
|
112
|
+
impl.set_dedication(PAGE)
|
|
113
|
+
assert impl.store.dedication()["version"] == 1 and impl.store.preface()["version"] == 2
|
|
114
|
+
assert ROOM not in str(impl.bookmark()) and PAGE not in str(impl.preface())
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def test_empty_and_too_long_prefaces_are_refused(impl):
|
|
118
|
+
assert impl.set_preface(" ")["ok"] is False
|
|
119
|
+
assert impl.set_preface("x" * (PREFACE_MAX_CHARS + 1))["ok"] is False
|
|
120
|
+
assert impl.store.preface() is None
|
|
121
|
+
|
|
122
|
+
|
|
94
123
|
def _client(tmp_path, **kw):
|
|
95
124
|
return TestClient(create_app(MarginConfig(db_path=str(tmp_path / "notes.db"), **kw)))
|
|
96
125
|
|
|
@@ -111,6 +140,22 @@ def test_http_bookmark_is_served_but_letters_stay_private(tmp_path):
|
|
|
111
140
|
assert c.get("/bookmark").json()["unread_letters"] == 0
|
|
112
141
|
|
|
113
142
|
|
|
143
|
+
def test_http_preface_is_served_with_reads_off(tmp_path):
|
|
144
|
+
"""A harness fetches the preface the way the hook fetches the bookmark:
|
|
145
|
+
with http_reads off, as text, empty before one is written."""
|
|
146
|
+
with _client(tmp_path) as c:
|
|
147
|
+
empty = c.get("/preface?format=text")
|
|
148
|
+
assert empty.status_code == 200 and empty.text == ""
|
|
149
|
+
assert c.get("/preface").json()["text"] == ""
|
|
150
|
+
assert c.put("/preface", json={"text": ROOM, "why": "first room"}).json() == {"ok": True, "version": 1, "changed": True}
|
|
151
|
+
assert c.put("/preface", json={"text": ""}).status_code == 400
|
|
152
|
+
assert c.put("/preface", json={"text": "x" * (PREFACE_MAX_CHARS + 1)}).status_code == 400
|
|
153
|
+
text = c.get("/preface?format=text")
|
|
154
|
+
assert text.headers["content-type"].startswith("text/plain") and text.text == ROOM + "\n"
|
|
155
|
+
assert c.get("/preface").json()["version"] == 1
|
|
156
|
+
assert ROOM not in str(c.get("/bookmark").json())
|
|
157
|
+
|
|
158
|
+
|
|
114
159
|
def test_an_old_database_gains_read_at_and_keeps_its_notes(tmp_path):
|
|
115
160
|
db = tmp_path / "notes.db"
|
|
116
161
|
with sqlite3.connect(db) as conn:
|
|
@@ -126,13 +171,16 @@ def test_the_bookmark_is_an_mcp_resource(tmp_path):
|
|
|
126
171
|
pytest.importorskip("mcp")
|
|
127
172
|
import asyncio
|
|
128
173
|
from mcp.server.fastmcp import FastMCP
|
|
129
|
-
from seren_margin.mcp.tools import BOOKMARK_URI, register_tools
|
|
174
|
+
from seren_margin.mcp.tools import BOOKMARK_URI, PREFACE_URI, register_tools
|
|
130
175
|
cfg = MarginConfig(db_path=str(tmp_path / "notes.db"))
|
|
131
176
|
store = MarginStore(cfg.resolved_db_path())
|
|
132
177
|
store.set_dedication(PAGE)
|
|
133
178
|
mcp = FastMCP("t")
|
|
134
179
|
register_tools(mcp, store, cfg)
|
|
180
|
+
store.set_preface(ROOM)
|
|
135
181
|
uris = [str(r.uri) for r in asyncio.run(mcp.list_resources())]
|
|
136
|
-
assert BOOKMARK_URI in uris
|
|
182
|
+
assert BOOKMARK_URI in uris and PREFACE_URI in uris
|
|
137
183
|
content = asyncio.run(mcp.read_resource(BOOKMARK_URI))
|
|
138
184
|
assert PAGE in "".join(getattr(c, "content", "") or getattr(c, "text", "") for c in content)
|
|
185
|
+
room = asyncio.run(mcp.read_resource(PREFACE_URI))
|
|
186
|
+
assert ROOM in "".join(getattr(c, "content", "") or getattr(c, "text", "") for c in room)
|
|
@@ -58,14 +58,16 @@ def test_roster_matches_the_implementation(manifest):
|
|
|
58
58
|
assert set(_tools(manifest)) == set(TOOL_NAMES)
|
|
59
59
|
|
|
60
60
|
|
|
61
|
-
def
|
|
61
|
+
def test_manifest_advertises_exactly_the_fifteen_tools(manifest):
|
|
62
62
|
"""Belt to the above, and runs without the mcp extra installed. Six for
|
|
63
63
|
the notes, four for the bookmark, the dedication and letters (29 Sept
|
|
64
|
-
2026), three for the pictures kept with notes (15 Oct 2026)
|
|
64
|
+
2026), three for the pictures kept with notes (15 Oct 2026), two for
|
|
65
|
+
the preface (21 Oct 2026)."""
|
|
65
66
|
assert set(_tools(manifest)) == {
|
|
66
67
|
"note_to_self", "list_my_notes", "list_my_topics",
|
|
67
68
|
"search_my_notes", "amend_note", "retract_note",
|
|
68
|
-
"bookmark", "set_dedication", "
|
|
69
|
+
"bookmark", "set_dedication", "preface", "set_preface",
|
|
70
|
+
"write_letter", "read_letters",
|
|
69
71
|
"keep_with_note", "look_at_my_note", "drop_from_note"}
|
|
70
72
|
|
|
71
73
|
|
|
@@ -86,11 +86,11 @@ def test_list_my_notes_respects_limit(impl):
|
|
|
86
86
|
# ── search_my_notes ─────────────────────────────────────────────────────────
|
|
87
87
|
|
|
88
88
|
def test_search_my_notes_finds_by_word(impl):
|
|
89
|
-
impl.note_to_self("the
|
|
89
|
+
impl.note_to_self("the kettle sits on the back burner", topic="alice")
|
|
90
90
|
impl.note_to_self("unrelated thought about dice colors")
|
|
91
|
-
r = impl.search_my_notes("
|
|
91
|
+
r = impl.search_my_notes("burner")
|
|
92
92
|
assert r["count"] == 1
|
|
93
|
-
assert "
|
|
93
|
+
assert "kettle" in r["notes"][0]["content"]
|
|
94
94
|
|
|
95
95
|
|
|
96
96
|
def test_search_my_notes_reports_finder(impl):
|
|
@@ -24,7 +24,7 @@ def store(tmp_path):
|
|
|
24
24
|
|
|
25
25
|
def _seed(store: MarginStore) -> None:
|
|
26
26
|
store.add(MarginNote(
|
|
27
|
-
content="the user mentioned the Kraken
|
|
27
|
+
content="the user mentioned the Kraken poster sits over the mantel",
|
|
28
28
|
topic="user", kind="observation"))
|
|
29
29
|
store.add(MarginNote(
|
|
30
30
|
content="the consolidator redraft budget feels too tight at 3",
|
|
@@ -47,7 +47,7 @@ def test_fts_is_available_in_this_environment(store):
|
|
|
47
47
|
|
|
48
48
|
def test_search_finds_by_content_word(store):
|
|
49
49
|
_seed(store)
|
|
50
|
-
hits, finder = store.search("
|
|
50
|
+
hits, finder = store.search("mantel")
|
|
51
51
|
assert finder == "fts"
|
|
52
52
|
assert len(hits) == 1
|
|
53
53
|
assert "Kraken" in hits[0].content
|
|
@@ -126,7 +126,7 @@ def test_query_operators_in_text_do_not_blow_up(store):
|
|
|
126
126
|
|
|
127
127
|
def test_fts_query_short_query_ands_raw_tokens():
|
|
128
128
|
"""<=3 tokens is deliberate; every word is required, stopwords included."""
|
|
129
|
-
assert _fts_query("kraken
|
|
129
|
+
assert _fts_query("kraken poster") == '"kraken" "poster"'
|
|
130
130
|
assert _fts_query("the redraft budget") == '"the" "redraft" "budget"'
|
|
131
131
|
|
|
132
132
|
|
|
@@ -163,7 +163,7 @@ def test_like_fallback_returns_results(store, monkeypatch):
|
|
|
163
163
|
"""Force the no-FTS5 path and prove it still answers correctly."""
|
|
164
164
|
_seed(store)
|
|
165
165
|
monkeypatch.setattr(store, "has_fts", False)
|
|
166
|
-
hits, finder = store.search("
|
|
166
|
+
hits, finder = store.search("mantel")
|
|
167
167
|
assert finder == "like"
|
|
168
168
|
assert len(hits) == 1
|
|
169
169
|
assert "Kraken" in hits[0].content
|
|
@@ -173,7 +173,7 @@ def test_like_fallback_ands_tokens(store, monkeypatch):
|
|
|
173
173
|
_seed(store)
|
|
174
174
|
monkeypatch.setattr(store, "has_fts", False)
|
|
175
175
|
# Both tokens present in one note -> hit.
|
|
176
|
-
assert store.search("Kraken
|
|
176
|
+
assert store.search("Kraken mantel")[0]
|
|
177
177
|
# Tokens from two different notes -> no single note has both.
|
|
178
178
|
assert store.search("Kraken Tabletop")[0] == []
|
|
179
179
|
|
|
@@ -24,7 +24,7 @@ from seren_margin.config import MarginConfig
|
|
|
24
24
|
SECRET = "the thing I have not told anyone yet"
|
|
25
25
|
ALLOWED = {"/", "/notes/stats", "/stores"}
|
|
26
26
|
NEVER = ("/notes/search", "/notes/topics", "/notes?", "/notes/{", "/letters", "/bookmark", "/dedication",
|
|
27
|
-
"/keepsakes", "/mcp")
|
|
27
|
+
"/preface", "/keepsakes", "/mcp")
|
|
28
28
|
|
|
29
29
|
|
|
30
30
|
def _calls(script: str) -> set[str]:
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|