Nothing yet — the agent’s notes, expectations, and open questions appear here as it works.
';
+ return;
+ }
+
+ const qHtml = questions.map(it => `
+ Nothing yet — the agent’s expectations, watchpoints, and open questions appear here as it works.
';
+ 'Nothing yet — the agent’s notes, expectations, and open questions appear here as it works.
';
return;
}
@@ -59,8 +65,17 @@ const ContextSurface = (() => {
${hc ? 'Notebook unavailable.
';
+ return;
+ }
+ const notes = data.notes || [];
+ if (!notes.length) {
+ list.innerHTML =
+ 'No notes yet — the notebook fills as the agent ' +
+ 'records observations, findings, and open questions.
';
+ return;
+ }
+ list.innerHTML = '';
+ notes.forEach(n => list.appendChild(card(n)));
+ }
+
+ function setupFilters() {
+ document.querySelectorAll('#notebook-content [data-nb-kind]').forEach(btn => {
+ btn.addEventListener('click', () => {
+ kindFilter = btn.dataset.nbKind;
+ document.querySelectorAll('#notebook-content [data-nb-kind]')
+ .forEach(b => b.classList.toggle('active', b === btn));
+ loadNotes();
+ });
+ });
+ }
+
+ // ── Ask the notebook ───────────────────────────────────────────────
+ function renderAskResult(data) {
+ const box = $('nb-ask-result');
+ if (!box) return;
+ box.hidden = false;
+ if (!data || data.available === false) {
+ box.innerHTML = 'The notebook is unavailable right now.
';
+ return;
+ }
+ const cov = data.coverage || 'covered';
+ const covLabel = { covered: 'Grounded in the notebook', partial: 'Partially covered', not_in_notebook: 'Not in the notebook yet' }[cov] || cov;
+ const points = (data.points || []).map(p => `
+ Something went wrong asking the notebook.
';
+ }
+ }
+
+ function setupAsk() {
+ const go = $('nb-ask-go'), input = $('nb-ask-input');
+ if (go) go.addEventListener('click', ask);
+ if (input) input.addEventListener('keydown', e => { if (e.key === 'Enter') { e.preventDefault(); ask(); } });
+ }
+
+ function esc(s) {
+ return (typeof escapeHtml === 'function') ? escapeHtml(String(s == null ? '' : s))
+ : String(s == null ? '' : s).replace(/[&<>"]/g, c => ({ '&': '&', '<': '<', '>': '>', '"': '"' }[c]));
+ }
+
+ function refresh() { loadThreads(); loadNotes(); }
+
+ function init() {
+ if (inited) { refresh(); return; }
+ inited = true;
+ setupFilters();
+ setupAsk();
+ refresh();
+ // Notebook writes ride the CONTEXT_UPDATED event — live-refresh if visible.
+ if (typeof ClientEventBus !== 'undefined') {
+ ClientEventBus.on('CONTEXT_UPDATED', () => {
+ if (typeof state !== 'undefined' && state.tab === 'notebook') refresh();
+ });
+ }
+ }
+
+ return { init };
+})();
diff --git a/gently/ui/web/static/js/utils.js b/gently/ui/web/static/js/utils.js
index 8b4a3d79..b321506c 100644
--- a/gently/ui/web/static/js/utils.js
+++ b/gently/ui/web/static/js/utils.js
@@ -3,7 +3,7 @@
// ══════════════════════════════════════════════════════════
// Tab and view name constants
-const TABS = { HOME: 'home', EMBRYOS: 'embryos', CALIBRATION: 'calibration', EVENTS: 'events', PLANS: 'plans', SESSIONS: 'sessions', DEVICES: 'devices', EXPERIMENT: 'experiment' };
+const TABS = { HOME: 'home', EMBRYOS: 'embryos', CALIBRATION: 'calibration', EVENTS: 'events', PLANS: 'plans', SESSIONS: 'sessions', DEVICES: 'devices', EXPERIMENT: 'experiment', NOTEBOOK: 'notebook' };
/**
* Extract the XY firmware fence (the addressable stage box) from a device-state
diff --git a/gently/ui/web/templates/_navbar.html b/gently/ui/web/templates/_navbar.html
index 33d5f675..ed02ba49 100644
--- a/gently/ui/web/templates/_navbar.html
+++ b/gently/ui/web/templates/_navbar.html
@@ -23,6 +23,7 @@
@@ -785,6 +812,7 @@
Properties
+
diff --git a/tests/test_notebook_api.py b/tests/test_notebook_api.py
new file mode 100644
index 00000000..1d18333b
--- /dev/null
+++ b/tests/test_notebook_api.py
@@ -0,0 +1,148 @@
+"""Tests for the notebook read API."""
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from gently.harness.memory.notebook import Note, NoteKind, NoteStatus
+
+
+def _make_app(context_store):
+ from gently.ui.web.routes.notebook import create_router
+
+ app = FastAPI()
+
+ class _Server:
+ pass
+
+ server = _Server()
+ server.context_store = context_store
+ app.include_router(create_router(server))
+ return app
+
+
+def _seed(cs):
+ nb = cs.notebook
+ nb.write_note(Note(id="o1", kind=NoteKind.OBSERVATION, body="ring formed", strains=["N2"]))
+ nb.write_note(Note(id="f1", kind=NoteKind.FINDING, body="rings by comma",
+ status=NoteStatus.PROPOSED, strains=["N2"], threads=["t1"]))
+ return cs
+
+
+class TestListNotes:
+ def test_no_store_available_false(self):
+ client = TestClient(_make_app(None))
+ data = client.get("/api/notebook/notes").json()
+ assert data == {"available": False, "notes": []}
+
+ def test_list_all(self, file_context_store):
+ client = TestClient(_make_app(_seed(file_context_store)))
+ data = client.get("/api/notebook/notes").json()
+ assert data["available"] is True
+ assert {n["id"] for n in data["notes"]} == {"o1", "f1"}
+
+ def test_filter_by_kind(self, file_context_store):
+ client = TestClient(_make_app(_seed(file_context_store)))
+ data = client.get("/api/notebook/notes?kind=finding").json()
+ assert {n["id"] for n in data["notes"]} == {"f1"}
+
+ def test_filter_by_strain(self, file_context_store):
+ client = TestClient(_make_app(_seed(file_context_store)))
+ data = client.get("/api/notebook/notes?strain=N2").json()
+ assert {n["id"] for n in data["notes"]} == {"o1", "f1"}
+
+ def test_invalid_kind_is_ignored(self, file_context_store):
+ client = TestClient(_make_app(_seed(file_context_store)))
+ data = client.get("/api/notebook/notes?kind=bogus").json()
+ assert {n["id"] for n in data["notes"]} == {"o1", "f1"}
+
+
+class TestGetNote:
+ def test_get_existing(self, file_context_store):
+ client = TestClient(_make_app(_seed(file_context_store)))
+ data = client.get("/api/notebook/notes/o1").json()
+ assert data["id"] == "o1"
+ assert data["body"] == "ring formed"
+
+ def test_get_missing_404(self, file_context_store):
+ client = TestClient(_make_app(_seed(file_context_store)))
+ resp = client.get("/api/notebook/notes/nope")
+ assert resp.status_code == 404
+
+
+class TestThreads:
+ def test_no_store(self):
+ client = TestClient(_make_app(None))
+ assert client.get("/api/notebook/threads").json() == {"available": False, "threads": []}
+
+ def test_thread_counts(self, file_context_store):
+ cs = file_context_store
+ nb = cs.notebook
+ nb.write_note(Note(id="a", kind=NoteKind.QUESTION, body="q", threads=["t1"]))
+ nb.write_note(Note(id="b", kind=NoteKind.FINDING, body="f", threads=["t1", "t2"]))
+ client = TestClient(_make_app(cs))
+ data = client.get("/api/notebook/threads").json()
+ assert data["available"] is True
+ assert data["threads"] == [{"id": "t1", "count": 2}, {"id": "t2", "count": 1}]
+
+
+class TestLimit:
+ def test_limit_returns_newest(self, file_context_store):
+ client = TestClient(_make_app(_seed(file_context_store)))
+ data = client.get("/api/notebook/notes?limit=1").json()
+ assert len(data["notes"]) == 1 # newest-first, capped
+
+
+class _AskBlock:
+ def __init__(self, inp):
+ self.type = "tool_use"
+ self.input = inp
+
+
+class _AskResp:
+ def __init__(self, inp):
+ self.content = [_AskBlock(inp)]
+ self.stop_reason = "tool_use"
+
+
+class _AskMessages:
+ def __init__(self, inp):
+ self._inp = inp
+
+ async def create(self, **kwargs):
+ return _AskResp(self._inp)
+
+
+class _AskClient:
+ def __init__(self, inp):
+ self.messages = _AskMessages(inp)
+
+
+def _make_app_with_client(context_store, client):
+ from gently.ui.web.routes.notebook import create_router
+
+ app = FastAPI()
+
+ class _Server:
+ pass
+
+ server = _Server()
+ server.context_store = context_store
+ server.claude_async = client
+ app.include_router(create_router(server))
+ return app
+
+
+class TestAsk:
+ def test_ask_returns_grounded_answer(self, file_context_store):
+ cs = _seed(file_context_store)
+ canned = {"answer": "A ring formed.", "points": [{"text": "ring", "note_ids": ["o1"]}],
+ "suggested_next": [], "coverage": "covered"}
+ client = TestClient(_make_app_with_client(cs, _AskClient(canned)))
+ resp = client.post("/api/notebook/ask", json={"question": "what happened?"})
+ assert resp.status_code == 200
+ assert resp.json()["coverage"] == "covered"
+
+ def test_ask_no_store(self):
+ client = TestClient(_make_app(None))
+ resp = client.post("/api/notebook/ask", json={"question": "x"})
+ assert resp.json() == {"available": False}
diff --git a/tests/test_notebook_ask.py b/tests/test_notebook_ask.py
new file mode 100644
index 00000000..9f501090
--- /dev/null
+++ b/tests/test_notebook_ask.py
@@ -0,0 +1,87 @@
+"""Tests for 'Ask the notebook' — retrieval + grounded synthesis."""
+
+import asyncio
+
+from gently.harness.memory.notebook import Note, NoteKind
+from gently.harness.memory.notebook_ask import (
+ ASK_TOOL,
+ answer_question,
+ build_ask_messages,
+ select_notes,
+)
+
+
+def _seed(cs):
+ nb = cs.notebook
+ nb.write_note(Note(id="o1", kind=NoteKind.OBSERVATION, body="ring formed", strains=["N2"], threads=["t1"]))
+ nb.write_note(Note(id="f1", kind=NoteKind.FINDING, body="12 min/degC", strains=["N2"], threads=["t1"]))
+ nb.write_note(Note(id="x1", kind=NoteKind.OBSERVATION, body="unrelated", strains=["OH904"]))
+ return nb
+
+
+class TestSelectNotes:
+ def test_scope_by_thread(self, file_context_store):
+ nb = _seed(file_context_store)
+ ids = {n.id for n in select_notes(nb, thread="t1")}
+ assert ids == {"o1", "f1"}
+
+ def test_scope_by_strain(self, file_context_store):
+ nb = _seed(file_context_store)
+ ids = {n.id for n in select_notes(nb, strain="OH904")}
+ assert ids == {"x1"}
+
+ def test_no_scope_returns_recent_capped(self, file_context_store):
+ nb = _seed(file_context_store)
+ notes = select_notes(nb, limit=2)
+ assert len(notes) == 2 # newest-first, capped
+
+
+class _FakeBlock:
+ def __init__(self, inp):
+ self.type = "tool_use"
+ self.input = inp
+
+
+class _FakeResp:
+ def __init__(self, inp):
+ self.content = [_FakeBlock(inp)]
+ self.stop_reason = "tool_use"
+
+
+class _FakeMessages:
+ def __init__(self, captured, inp):
+ self._captured, self._inp = captured, inp
+
+ async def create(self, **kwargs):
+ self._captured.update(kwargs)
+ return _FakeResp(self._inp)
+
+
+class _FakeClient:
+ def __init__(self, inp):
+ self.captured = {}
+ self.messages = _FakeMessages(self.captured, inp)
+
+
+class TestAnswerQuestion:
+ def test_build_messages_embeds_note_ids(self):
+ notes = [Note(id="o1", kind=NoteKind.OBSERVATION, body="ring formed")]
+ msgs = build_ask_messages("what formed?", notes)
+ text = msgs[0]["content"]
+ assert "o1" in text and "ring formed" in text and "what formed?" in text
+
+ def test_answer_returns_structured_and_forces_tool(self):
+ canned = {"answer": "A ring formed.", "points": [{"text": "ring formed", "note_ids": ["o1"]}],
+ "suggested_next": [], "coverage": "covered"}
+ client = _FakeClient(canned)
+ notes = [Note(id="o1", kind=NoteKind.OBSERVATION, body="ring formed")]
+ out = asyncio.run(answer_question(client, "m", "what formed?", notes))
+ assert out == canned
+ assert client.captured["tool_choice"] == {"type": "tool", "name": ASK_TOOL["name"]}
+ assert client.captured["model"] == "m"
+
+ def test_answer_no_notes_short_circuits_without_api(self):
+ client = _FakeClient({"should": "not be used"})
+ out = asyncio.run(answer_question(client, "m", "anything?", []))
+ assert out["coverage"] == "not_in_notebook"
+ assert client.captured == {} # no API call when nothing to ground on
diff --git a/tests/test_notebook_store.py b/tests/test_notebook_store.py
new file mode 100644
index 00000000..4fdd48f7
--- /dev/null
+++ b/tests/test_notebook_store.py
@@ -0,0 +1,218 @@
+"""Tests for the shared lab notebook: Note model + NotebookStore."""
+
+from datetime import datetime
+
+from gently.harness.memory.model import Confidence, Learning, Observation
+from gently.harness.memory.notebook import (
+ Author,
+ Note,
+ NoteKind,
+ NoteStatus,
+ NotebookStore,
+ learning_to_note,
+ note_from_dict,
+ note_to_dict,
+ observation_to_note,
+)
+
+
+class TestNoteModel:
+ def test_round_trip_minimal(self):
+ n = Note(id="abc123", kind=NoteKind.OBSERVATION, body="dim rings at 10 ms")
+ d = note_to_dict(n)
+ assert d["kind"] == "observation"
+ assert d["author"] == "agent" # default
+ assert d["status"] == "confirmed" # default
+ back = note_from_dict(d)
+ assert back == n
+
+ def test_round_trip_full(self):
+ n = Note(
+ id="def456",
+ kind=NoteKind.FINDING,
+ body="temperature shifts timing ~12 min/degC",
+ author=Author.AGENT,
+ title="Temp shifts timing",
+ status=NoteStatus.PROPOSED,
+ confidence=Confidence.MEDIUM,
+ strains=["N2", "OH904"],
+ embryos=["emb_0007"],
+ sessions=["20260615_1432_x"],
+ threads=["q_division_temp"],
+ basis=["obs_1", "obs_2"],
+ links=[{"rel": "supports", "to": "q_division_temp"}],
+ artifacts=[{"kind": "projection", "session": "s1", "embryo": "emb_0007", "t": 42}],
+ created_at=datetime(2026, 6, 16, 11, 0, 0),
+ updated_at=datetime(2026, 6, 16, 11, 0, 0),
+ )
+ back = note_from_dict(note_to_dict(n))
+ assert back == n
+ assert note_to_dict(n)["confidence"] == "medium"
+
+
+class TestNotebookStoreReadWrite:
+ def test_write_assigns_id_and_persists(self, tmp_path):
+ store = NotebookStore(tmp_path / "notebook")
+ n = Note(id="", kind=NoteKind.OBSERVATION, body="bean stage at t40")
+ note_id = store.write_note(n)
+ assert note_id # non-empty id assigned
+ files = list((tmp_path / "notebook" / "notes").glob("*.yaml"))
+ assert len(files) == 1
+ assert files[0].name.startswith(note_id + "_")
+
+ def test_get_note_round_trip(self, tmp_path):
+ store = NotebookStore(tmp_path / "notebook")
+ n = Note(id="", kind=NoteKind.FINDING, body="x", strains=["N2"], threads=["t1"])
+ note_id = store.write_note(n)
+ got = store.get_note(note_id)
+ assert got is not None
+ assert got.id == note_id
+ assert got.kind == NoteKind.FINDING
+ assert got.strains == ["N2"]
+
+ def test_get_missing_returns_none(self, tmp_path):
+ store = NotebookStore(tmp_path / "notebook")
+ assert store.get_note("nope") is None
+
+
+class TestNotebookIndex:
+ def test_index_updated_on_write(self, tmp_path):
+ store = NotebookStore(tmp_path / "notebook")
+ a = store.write_note(Note(id="", kind=NoteKind.OBSERVATION, body="a", strains=["N2"]))
+ b = store.write_note(Note(id="", kind=NoteKind.OBSERVATION, body="b", strains=["N2", "OH904"]))
+ assert set(store.ids_for_strain("N2")) == {a, b}
+ assert store.ids_for_strain("OH904") == [b]
+ assert store.ids_for_strain("missing") == []
+
+ def test_index_by_embryo_and_thread(self, tmp_path):
+ store = NotebookStore(tmp_path / "notebook")
+ a = store.write_note(Note(id="", kind=NoteKind.FINDING, body="a",
+ embryos=["e1"], threads=["t1"]))
+ assert store.ids_for_embryo("e1") == [a]
+ assert store.ids_for_thread("t1") == [a]
+
+ def test_rebuild_index_from_disk(self, tmp_path):
+ store = NotebookStore(tmp_path / "notebook")
+ a = store.write_note(Note(id="", kind=NoteKind.OBSERVATION, body="a", strains=["N2"]))
+ # a fresh store over the same dir must rebuild the index by scanning notes/
+ store2 = NotebookStore(tmp_path / "notebook")
+ assert store2.ids_for_strain("N2") == [a]
+
+
+class TestNotebookQuery:
+ def _seed(self, tmp_path):
+ store = NotebookStore(tmp_path / "notebook")
+ store.write_note(Note(id="o1", kind=NoteKind.OBSERVATION, body="o", strains=["N2"]))
+ store.write_note(Note(id="f1", kind=NoteKind.FINDING, body="f",
+ status=NoteStatus.PROPOSED, strains=["N2"], threads=["t1"]))
+ store.write_note(Note(id="q1", kind=NoteKind.QUESTION, body="q",
+ status=NoteStatus.OPEN, threads=["t1"]))
+ return store
+
+ def test_query_by_kind(self, tmp_path):
+ store = self._seed(tmp_path)
+ ids = {n.id for n in store.query_notes(kind=NoteKind.FINDING)}
+ assert ids == {"f1"}
+
+ def test_query_by_thread_scope(self, tmp_path):
+ store = self._seed(tmp_path)
+ ids = {n.id for n in store.query_notes(thread="t1")}
+ assert ids == {"f1", "q1"}
+
+ def test_query_by_thread_and_kind(self, tmp_path):
+ store = self._seed(tmp_path)
+ ids = {n.id for n in store.query_notes(thread="t1", kind=NoteKind.QUESTION)}
+ assert ids == {"q1"}
+
+ def test_query_by_status(self, tmp_path):
+ store = self._seed(tmp_path)
+ ids = {n.id for n in store.query_notes(status=NoteStatus.OPEN)}
+ assert ids == {"q1"}
+
+ def test_query_all_sorted_newest_first(self, tmp_path):
+ store = self._seed(tmp_path)
+ notes = store.query_notes()
+ assert len(notes) == 3
+ ts = [n.created_at for n in notes]
+ assert ts == sorted(ts, reverse=True)
+
+
+class TestNotebookLinkSupersede:
+ def test_link_notes_adds_typed_edge(self, tmp_path):
+ store = NotebookStore(tmp_path / "notebook")
+ a = store.write_note(Note(id="", kind=NoteKind.FINDING, body="a"))
+ b = store.write_note(Note(id="", kind=NoteKind.QUESTION, body="b"))
+ store.link_notes(a, "supports", b)
+ got = store.get_note(a)
+ assert {"rel": "supports", "to": b} in got.links
+
+ def test_supersede_marks_old_and_points_new(self, tmp_path):
+ store = NotebookStore(tmp_path / "notebook")
+ old = store.write_note(Note(id="", kind=NoteKind.FINDING, body="old claim"))
+ new = store.write_note(Note(id="", kind=NoteKind.FINDING, body="better claim"))
+ store.supersede_note(old, new)
+ old_n = store.get_note(old)
+ new_n = store.get_note(new)
+ assert old_n.status == NoteStatus.SUPERSEDED
+ assert old_n.superseded_by == new
+ assert {"rel": "refines", "to": old} in new_n.links
+
+
+class TestConverters:
+ def test_observation_to_note(self):
+ obs = Observation(
+ id="o1", timestamp=datetime(2026, 6, 16, 9, 0, 0), type="milestone",
+ content="nerve ring formed", embryo_id="e1", session_id="s1",
+ relates_to=["o0"], gently_refs={"kind": "projection", "t": 42},
+ )
+ n = observation_to_note(obs)
+ assert n.id == "o1"
+ assert n.kind == NoteKind.OBSERVATION
+ assert n.body == "nerve ring formed"
+ assert n.author == Author.AGENT
+ assert n.embryos == ["e1"]
+ assert n.sessions == ["s1"]
+ assert {"rel": "relates_to", "to": "o0"} in n.links
+ assert n.artifacts == [{"kind": "projection", "t": 42}]
+ assert n.created_at == datetime(2026, 6, 16, 9, 0, 0)
+
+ def test_learning_to_note(self):
+ lrn = Learning(id="l1", content="rings form by comma", confidence=Confidence.HIGH)
+ n = learning_to_note(lrn)
+ assert n.id == "l1"
+ assert n.kind == NoteKind.FINDING
+ assert n.body == "rings form by comma"
+ assert n.status == NoteStatus.PROPOSED # agent-drafted, awaits confirm
+ assert n.confidence == Confidence.HIGH
+
+
+class TestContextStoreNotebook:
+ def test_notebook_property_rooted_under_agent_dir(self, file_context_store):
+ nb = file_context_store.notebook
+ assert nb.root == file_context_store.agent_dir / "notebook"
+
+ def test_notebook_property_is_cached(self, file_context_store):
+ assert file_context_store.notebook is file_context_store.notebook
+
+
+class TestApplyUpdatesMirror:
+ def test_apply_updates_mirrors_observations_and_learnings(self, file_context_store):
+ from gently.harness.memory.model import ContextUpdates
+
+ cs = file_context_store
+ obs = Observation(id="o1", timestamp=datetime(2026, 6, 16, 9, 0, 0),
+ type="milestone", content="ring formed", embryo_id="e1")
+ lrn = Learning(id="l1", content="rings form by comma", confidence=Confidence.HIGH)
+ cs.apply_updates(ContextUpdates(new_observations=[obs], new_learnings=[lrn]))
+
+ bodies = {n.body for n in cs.notebook.query_notes()}
+ assert "ring formed" in bodies
+ assert "rings form by comma" in bodies
+ assert cs.notebook.ids_for_embryo("e1") == ["o1"]
+
+ def test_apply_updates_empty_is_noop_for_notebook(self, file_context_store):
+ from gently.harness.memory.model import ContextUpdates
+
+ cs = file_context_store
+ cs.apply_updates(ContextUpdates())
+ assert cs.notebook.query_notes() == []