@yahyahammad/venastine 0.2.0 → 0.3.8

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.
Files changed (129) hide show
  1. package/.env.example +19 -14
  2. package/CONFIG_ARCHITECTURE.md +2002 -0
  3. package/NOTICE +1 -1
  4. package/README.md +233 -94
  5. package/agents/builtin/build.md +73 -0
  6. package/agents/builtin/general.md +80 -0
  7. package/agents/builtin/plan.md +23 -5
  8. package/agents/builtin/test.md +65 -0
  9. package/agents/builtin/writer.md +67 -0
  10. package/agents/manager.py +261 -195
  11. package/agents/subagent_tool.py +277 -43
  12. package/agents/tui_commands.py +7 -12
  13. package/bin/venastine.mjs +528 -382
  14. package/bin/venastine.py +71 -0
  15. package/cli_commands.py +835 -0
  16. package/config.py +95 -1198
  17. package/config.yaml +1090 -0
  18. package/config_edit.py +1301 -0
  19. package/config_schema.py +966 -0
  20. package/config_update.py +749 -0
  21. package/core/agent_activity.py +158 -20
  22. package/core/ansi.py +452 -0
  23. package/core/approval.py +27 -5
  24. package/core/call_view.py +364 -0
  25. package/core/cancel.py +121 -0
  26. package/core/chatgpt_auth.py +747 -0
  27. package/core/claims_view.py +107 -0
  28. package/core/client.py +1238 -82
  29. package/core/commands.py +454 -0
  30. package/core/compaction.py +830 -66
  31. package/core/config_loader.py +516 -97
  32. package/core/connect.py +686 -0
  33. package/core/events.py +68 -6
  34. package/core/file_mentions.py +280 -0
  35. package/core/interaction.py +87 -4
  36. package/core/line_pattern.py +128 -0
  37. package/core/loop.py +1516 -440
  38. package/core/memory.py +120 -8
  39. package/core/pipeline_models.py +23 -9
  40. package/core/provider_errors.py +234 -0
  41. package/core/reasoning/confidence_scoring.py +70 -54
  42. package/core/reasoning/json_retry.py +19 -1
  43. package/core/reasoning/orchestrator.py +232 -53
  44. package/core/reasoning/output_writer.py +90 -31
  45. package/core/reasoning/payload_validation.py +133 -7
  46. package/core/reasoning/pipeline_storage.py +427 -361
  47. package/core/reasoning/review.py +659 -615
  48. package/core/reasoning/scholar.py +38 -14
  49. package/core/reasoning/source_corpus.py +110 -4
  50. package/core/replay.py +158 -26
  51. package/core/session.py +36 -12
  52. package/core/session_view.py +259 -0
  53. package/core/session_wake.py +259 -0
  54. package/core/shell_sessions.py +1553 -0
  55. package/core/workspace_trust.py +1 -1
  56. package/credentials.py +308 -180
  57. package/database.py +82 -1
  58. package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
  59. package/docs/SECURITY.md +108 -0
  60. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  61. package/env_secrets.py +118 -77
  62. package/json_store.py +236 -16
  63. package/logging_setup.py +121 -11
  64. package/main.py +1671 -199
  65. package/mcp_client/client.py +257 -23
  66. package/mcp_client/config.py +484 -379
  67. package/mcp_client/registration.py +163 -2
  68. package/memories/manager.py +15 -0
  69. package/memories/tui_commands.py +7 -12
  70. package/package.json +234 -4
  71. package/project_init/config_files.py +4 -0
  72. package/project_init/generator.py +201 -37
  73. package/project_init/manifest.py +418 -406
  74. package/project_init/tui_commands.py +7 -4
  75. package/prompts/revalidate.md +1 -1
  76. package/prompts/revise.md +17 -15
  77. package/prompts/system_prompts.py +64 -10
  78. package/providers.json.example +94 -92
  79. package/pyproject.toml +51 -2
  80. package/requirements.txt +252 -29
  81. package/safety/policy_enforcement.py +353 -17
  82. package/security/askpass.py +419 -0
  83. package/security/capability.py +37 -7
  84. package/security/confine.py +484 -0
  85. package/security/hosted.py +182 -0
  86. package/security/permissions.py +54 -7
  87. package/security/posture.py +124 -12
  88. package/security/protected_paths.py +198 -6
  89. package/security/sandbox.py +3262 -139
  90. package/security/secrets.py +855 -0
  91. package/skills/tui_commands.py +3 -4
  92. package/storage.py +368 -35
  93. package/tools/base.py +465 -305
  94. package/tools/builtin/_math_common.py +306 -16
  95. package/tools/builtin/_net_common.py +267 -61
  96. package/tools/builtin/arxiv.py +681 -223
  97. package/tools/builtin/ask_user.py +231 -213
  98. package/tools/builtin/discrete_math.py +35 -4
  99. package/tools/builtin/fetch_url.py +239 -21
  100. package/tools/builtin/file_ops.py +341 -33
  101. package/tools/builtin/geometry.py +184 -148
  102. package/tools/builtin/get_time.py +2 -2
  103. package/tools/builtin/linear_algebra.py +66 -23
  104. package/tools/builtin/load_skill.py +10 -0
  105. package/tools/builtin/logic.py +171 -12
  106. package/tools/builtin/pin.py +46 -12
  107. package/tools/builtin/probability_stats.py +224 -228
  108. package/tools/builtin/project_docs.py +80 -21
  109. package/tools/builtin/remember.py +21 -4
  110. package/tools/builtin/shell.py +586 -67
  111. package/tools/builtin/shell_sessions.py +613 -0
  112. package/tools/builtin/symbolic_math.py +80 -10
  113. package/tools/builtin/todo.py +5 -3
  114. package/tools/builtin/web_search.py +329 -151
  115. package/tools/context.py +23 -0
  116. package/tools/isolation.py +387 -314
  117. package/tools/registry.py +347 -30
  118. package/tui/app.py +4645 -438
  119. package/tui/app.tcss +185 -2
  120. package/tui/commands.py +10 -154
  121. package/tui/diffs.py +286 -265
  122. package/tui/hosted_driver.py +102 -0
  123. package/tui/markdown.py +60 -10
  124. package/tui/meters.py +103 -7
  125. package/tui/screens.py +346 -92
  126. package/tui/themes.py +59 -19
  127. package/tui/widgets.py +1575 -111
  128. package/SECURITY.md +0 -88
  129. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -92,10 +92,29 @@ def doi_for(url: str) -> str | None:
92
92
  # ---- Pure scoring ---------------------------------------------------------
93
93
  # ---------------------------------------------------------------------------
94
94
 
95
+ def _obj(value) -> dict:
96
+ """`value` if OpenAlex sent an object there, else an empty one.
97
+
98
+ Batch 219 (#218). Every read of a record used to trust its shape --
99
+ `(x or {}).get(...)` survives a null and nothing else -- so one
100
+ non-object where an object was expected raised AttributeError out of
101
+ an optional stage and failed a run that had already grounded and
102
+ scored. Driven: 104 malformed shapes across ten keys. A shape this
103
+ module cannot read is a signal that is absent, and every term here
104
+ already knows how to drop an absent one.
105
+ """
106
+ return value if isinstance(value, dict) else {}
107
+
108
+
109
+ def _text(value) -> str:
110
+ """`value` if it is a string, else "" -- `_obj`'s rule for a leaf."""
111
+ return value if isinstance(value, str) else ""
112
+
113
+
95
114
  def _location_type(work: dict) -> str:
96
- location = work.get("primary_location") or {}
97
- source = location.get("source") or {}
98
- return (source.get("type") or "").lower()
115
+ location = _obj(work.get("primary_location"))
116
+ source = _obj(location.get("source"))
117
+ return _text(source.get("type")).lower()
99
118
 
100
119
 
101
120
  def is_peer_reviewed(work: dict) -> bool:
@@ -108,8 +127,8 @@ def is_peer_reviewed(work: dict) -> bool:
108
127
  publisher's own answer where there is one. A record has to survive all
109
128
  three to count.
110
129
  """
111
- location = work.get("primary_location") or {}
112
- if (work.get("type") or "").lower() == "preprint":
130
+ location = _obj(work.get("primary_location"))
131
+ if _text(work.get("type")).lower() == "preprint":
113
132
  return False
114
133
  if _location_type(work) not in ("journal", "conference", "book series"):
115
134
  return False
@@ -277,7 +296,7 @@ class ScholarLookup:
277
296
  "select": "id"})
278
297
  if not isinstance(payload, dict):
279
298
  return None
280
- count = (payload.get("meta") or {}).get("count")
299
+ count = _obj(payload.get("meta")).get("count")
281
300
  return count if isinstance(count, int) else None
282
301
 
283
302
  def citation_percentile(self, work: dict, today: date | None = None):
@@ -298,9 +317,10 @@ class ScholarLookup:
298
317
  if not isinstance(cites, int) or isinstance(cites, bool):
299
318
  return None, "insufficient_cohort"
300
319
 
301
- field = ((work.get("primary_topic") or {}).get("field") or {}).get("id")
302
- domain = ((work.get("primary_topic") or {}).get("domain") or {}).get("id")
303
- work_type = (work.get("type") or "").lower() or "article"
320
+ topic = _obj(work.get("primary_topic"))
321
+ field = _text(_obj(topic.get("field")).get("id")) or None
322
+ domain = _text(_obj(topic.get("domain")).get("id")) or None
323
+ work_type = _text(work.get("type")).lower() or "article"
304
324
  published = date.fromisoformat(work["publication_date"][:10])
305
325
 
306
326
  minimum = self.knobs.get("min_cohort_size", config.SCHOLAR_MIN_COHORT_SIZE)
@@ -327,9 +347,12 @@ class ScholarLookup:
327
347
  pass someone is waiting on.
328
348
  """
329
349
  ids = []
330
- for authorship in (work.get("authorships") or [])[:_MAX_AUTHORS]:
331
- author = (authorship or {}).get("author") or {}
332
- identifier = (author.get("id") or "").rsplit("/", 1)[-1]
350
+ authorships = work.get("authorships")
351
+ if not isinstance(authorships, list):
352
+ authorships = []
353
+ for authorship in authorships[:_MAX_AUTHORS]:
354
+ author = _obj(_obj(authorship).get("author"))
355
+ identifier = _text(author.get("id")).rsplit("/", 1)[-1]
333
356
  if identifier.startswith("A"):
334
357
  ids.append(identifier)
335
358
  if not ids:
@@ -339,8 +362,9 @@ class ScholarLookup:
339
362
  "select": "id,summary_stats", "per-page": len(ids)})
340
363
  if not isinstance(payload, dict):
341
364
  return None
342
- indexes = [((entry or {}).get("summary_stats") or {}).get("h_index")
343
- for entry in payload.get("results") or []]
365
+ results = payload.get("results")
366
+ indexes = [_obj(_obj(entry).get("summary_stats")).get("h_index")
367
+ for entry in (results if isinstance(results, list) else [])]
344
368
  return author_standing(
345
369
  indexes, self.knobs.get("h_saturation", config.SCHOLAR_H_SATURATION))
346
370
 
@@ -28,6 +28,17 @@ boundary -- nothing is stored by this module unredacted -- beats depending
28
28
  on a guarantee made two layers away that a later refactor could quietly
29
29
  drop. The second pass is a no-op on already-clean text.
30
30
 
31
+ AND IT IS NOT WHERE §52's SPLIT-CREDENTIAL FIX WENT, deliberately (RB4).
32
+ §51 made this module the one place where two pages of a document become
33
+ adjacent, so a credential straddling a page boundary was rejoined HERE --
34
+ reproduced end to end in batch 106, into `artifact_entries()` and therefore
35
+ into `sources/<sha256>.txt` and the window sent to the embedding provider.
36
+ The register's proposed fix was to re-redact the whole merged text on every
37
+ append. It was declined: `fetch_url` redacts before it cuts now, so the
38
+ halves never exist, and re-scanning up to 20,000 characters per page would
39
+ buy nothing this module can see -- while leaving unfixed the model's own two
40
+ tool results, which the producer-side fix does close.
41
+
31
42
  THIS MODULE OWNS URL IDENTITY for the pipeline. Two spellings of one arXiv
32
43
  paper are one source, and a model that cites `/abs/2005.14165v3` after
33
44
  fetching `/abs/2005.14165` must not be told its own citation has no text.
@@ -43,7 +54,7 @@ import hashlib
43
54
  import logging
44
55
  import re
45
56
  from dataclasses import dataclass, field
46
- from datetime import datetime, timezone
57
+ from datetime import UTC, datetime
47
58
  from urllib.parse import urlsplit, urlunsplit
48
59
 
49
60
  from safety.policy_enforcement import redact_output_text
@@ -99,6 +110,26 @@ class SourceDocument:
99
110
  tool: str = ""
100
111
  retrieved_at: str = ""
101
112
 
113
+ #: ROADMAP_v3 §51 (PG7). How far into the SOURCE document the held text
114
+ #: reaches, in the source's own character positions -- which is what
115
+ #: `fetch_url` pages by, and not the same as `len(text)`. 0 for a
116
+ #: document no paging tool produced.
117
+ #:
118
+ #: §52 (RB1) removed ONE of the two reasons those numbers differ.
119
+ #: Redaction used to happen here, on each page, so a page's held length
120
+ #: could be shorter than the span it covered; `fetch_url` now redacts
121
+ #: before it cuts, so its pages arrive clean and that gap is gone. What
122
+ #: still separates the two is `.strip()` and `MAX_DOCUMENT_CHARS`, both
123
+ #: of which change how much is HELD and neither of which moves where a
124
+ #: page sat in the document it came from.
125
+ #:
126
+ #: It is what stops a page being absorbed twice. Without it, a model
127
+ #: that re-reads page 2 -- which it will, because re-reading is how a
128
+ #: model checks itself -- would append it again and the corpus would
129
+ #: hold the same paragraph twice, which a similarity score then counts
130
+ #: twice.
131
+ next_offset: int = 0
132
+
102
133
  @property
103
134
  def sha256(self) -> str:
104
135
  return hashlib.sha256(self.text.encode("utf-8")).hexdigest()
@@ -116,7 +147,7 @@ class SourceDocument:
116
147
 
117
148
 
118
149
  def _now() -> str:
119
- return datetime.now(timezone.utc).isoformat(timespec="seconds")
150
+ return datetime.now(UTC).isoformat(timespec="seconds")
120
151
 
121
152
 
122
153
  def arxiv_id_from_url(url: str) -> str | None:
@@ -224,11 +255,19 @@ class SourceCorpus:
224
255
  # `url` is the URL that ANSWERED, after redirects -- which is what
225
256
  # fetch_url.py:89-95 says the grounding pass attributes the text
226
257
  # to, and therefore what the model will cite.
258
+ #
259
+ # `offset` is ROADMAP_v3 §51 (PG7). A result without one is a
260
+ # pre-§51 shape or a hand-built fixture, and 0 is the right reading
261
+ # of both: a whole document starting at the beginning.
262
+ offset = result.get("offset")
263
+ if not isinstance(offset, int) or offset < 0:
264
+ offset = 0
227
265
  return self._store(
228
266
  url=result.get("url"),
229
267
  text=result.get("content"),
230
268
  title="",
231
269
  tool="fetch_url",
270
+ offset=offset,
232
271
  )
233
272
 
234
273
  def _add_arxiv(self, result: dict) -> int:
@@ -270,19 +309,81 @@ class SourceCorpus:
270
309
  )
271
310
  return added
272
311
 
273
- def _store(self, url, text, title: str, tool: str) -> int:
312
+ def _store(self, url, text, title: str, tool: str, offset=None) -> int:
313
+ """Absorb one document, or one PAGE of one (ROADMAP_v3 §51, PG7).
314
+
315
+ `offset` is the source position this text starts at, or None from a
316
+ tool that does not page. None and 0 are NOT the same thing here:
317
+ None means "this is the whole of what that tool returns", 0 means
318
+ "this is the first page of something that may have more".
319
+
320
+ WHY THE PAGED CASE CANNOT USE LONGEST-WINS. Measured, batch 105,
321
+ before any of this was written: a corpus given page 1 and then page
322
+ 2 of one URL returned 1 then **0** -- `len(existing.text) >=
323
+ len(cleaned)` is 5000 >= 5000, so page 2 was DROPPED and the held
324
+ text stayed page 1. Paging would then have made the model better
325
+ informed and the grounding pass no better, and the divergence is
326
+ invisible from both sides: the model reads four pages and the score
327
+ is computed against the first. The near miss is worse than the
328
+ miss -- a page 2 one character longer REPLACED page 1 outright,
329
+ leaving the corpus holding the middle of a document and attributing
330
+ it to the whole URL.
331
+ """
274
332
  if not isinstance(url, str) or not isinstance(text, str):
275
333
  return 0
276
334
  key = normalize_url(url)
277
335
  if not key:
278
336
  return 0
279
337
 
338
+ existing = self.documents.get(key)
339
+
340
+ # A continuation extends what is held; anything else competes on
341
+ # length exactly as it did before §51.
342
+ continuing = (
343
+ offset is not None
344
+ and offset > 0
345
+ and existing is not None
346
+ and existing.tool == tool
347
+ )
348
+
349
+ if continuing:
350
+ # How much of this page is already held. Covers all three
351
+ # shapes with one subtraction: an exact continuation overlaps
352
+ # by nothing, a re-read of the same page overlaps entirely and
353
+ # contributes the empty string, and a page that starts inside
354
+ # what is held contributes only its tail. A page starting
355
+ # BEYOND the held text leaves a gap -- appended anyway, because
356
+ # the text is real and the alternative is losing it, and an
357
+ # incomplete document is what this corpus already holds for
358
+ # every source the byte cap cut.
359
+ #
360
+ # There is deliberately NO `if overlap >= len(text): return 0`
361
+ # above this. One was written, and a mutation pass showed it
362
+ # could be deleted with no test failing anywhere -- because the
363
+ # slice already yields "" in exactly the cases it guarded, and
364
+ # the empty-addition check below catches them. Batch 103's
365
+ # lesson applies to a guard that cannot fire as much as to one
366
+ # that fires in the wrong place: it reads as the thing
367
+ # protecting you.
368
+ overlap = existing.next_offset - offset
369
+ addition = redact_output_text(text[max(0, overlap):])
370
+ if not addition.strip():
371
+ return 0
372
+ merged = (existing.text + addition)[:MAX_DOCUMENT_CHARS]
373
+ if merged == existing.text:
374
+ return 0
375
+ self.documents[key] = SourceDocument(
376
+ url=key, text=merged, title=existing.title,
377
+ tool=tool, retrieved_at=_now(),
378
+ next_offset=max(existing.next_offset, offset + len(text)),
379
+ )
380
+ return 1
381
+
280
382
  cleaned = redact_output_text(text).strip()
281
383
  if len(cleaned) < MIN_DOCUMENT_CHARS:
282
384
  return 0
283
385
  cleaned = cleaned[:MAX_DOCUMENT_CHARS]
284
386
 
285
- existing = self.documents.get(key)
286
387
  if existing is not None and len(existing.text) >= len(cleaned):
287
388
  return 0
288
389
  if existing is None and len(self.documents) >= MAX_DOCUMENTS:
@@ -295,6 +396,11 @@ class SourceCorpus:
295
396
  self.documents[key] = SourceDocument(
296
397
  url=key, text=cleaned, title=title or (existing.title if existing else ""),
297
398
  tool=tool, retrieved_at=_now(),
399
+ # In the SOURCE's positions, so the next page's offset can be
400
+ # compared against it. `len(text)` and not `len(cleaned)`:
401
+ # redaction and stripping change how much is HELD, never where
402
+ # the page sat in the document it came from.
403
+ next_offset=(offset + len(text)) if offset is not None else 0,
298
404
  )
299
405
  return 1
300
406
 
package/core/replay.py CHANGED
@@ -52,15 +52,24 @@ material the conversation was about. The call is what says what happened,
52
52
  and `param_digest` says WHICH url or query -- redacted, because a tool
53
53
  argument can carry a credential and this is now the third place one could
54
54
  surface.
55
+
56
+ T4 IS UNCHANGED BY §55, AND §55 IS WHY IT CAN STAY. A result is still not
57
+ replayed into the conversation; it is now REACHABLE from the line that
58
+ produced it, because every tool line carries `(OPENS_CALL, call id)` and
59
+ `core/call_view.py` reads the same archive on demand (TR6/TR7). That is
60
+ the distinction worth keeping straight if either side is ever revisited:
61
+ T4 is about what a replay PUTS IN FRONT of a reader, and §55 is about what
62
+ a reader can ask for. A feature that inlined the output would be T4 undone
63
+ rather than extended.
55
64
  """
56
65
 
57
66
  from __future__ import annotations
58
67
 
59
- from typing import List, Optional, Tuple
68
+ from typing import Optional
60
69
  from uuid import UUID
61
70
 
62
- from tools.registry import registry
63
71
  from storage import archive_history
72
+ from tools.registry import registry
64
73
 
65
74
  #: One replayed entry: (role, text, links). The roles are transcript palette
66
75
  #: roles (tui/themes.role_styles), so the TUI can paint them with what it
@@ -76,42 +85,109 @@ from storage import archive_history
76
85
  #: the same characters as a live turn and quietly refuse to open them,
77
86
  #: which is the one conversation rendered two ways that Section 44 removed
78
87
  #: for thinking spans. Empty for every entry that is not a tool call.
79
- ReplayEntry = Tuple[str, str, Tuple[str, ...]]
88
+ #:
89
+ #: `opens` is §47's, widened by ROADMAP_v3 §49 (SS14) and again by §55
90
+ #: (TR7): `(kind, call id)` for a tool line, and `()` only where there is
91
+ #: no call id to carry. The id is the model's own id for the call that
92
+ #: drew the line, and the kind is `OPENS_THREAD`, `OPENS_SESSION` or
93
+ #: `OPENS_CALL` -- the registry is asked, so this file does not have to
94
+ #: know that `spawn_subagent` is special and cannot come to disagree with
95
+ #: the TUI about which lines are openable.
96
+ #:
97
+ #: SINCE §55 THE GATE IS THE ID, NOT THE KIND. `registry.opens()` has no
98
+ #: empty answer any more, so an unarmed line is one whose call the archive
99
+ #: cannot be asked about rather than one whose tool declared nothing.
100
+ #: It does not widen the sentence above either: a caller is still
101
+ #: rendering rather than reasoning about history, and what a line opened
102
+ #: is a fact about the LINE. Without it a resumed conversation would draw
103
+ #: `▸ spawn_subagent` exactly as the live turn did and refuse to open it
104
+ #: -- the same divergence §44 removed for thinking spans, and batch 65
105
+ #: for a truncated URL.
106
+ #:
107
+ #: IT CARRIES THE KIND, not just the id, and that is what SS14 needed:
108
+ #: a `▸ shell_background` line opens a SESSION, which is read from the
109
+ #: manager or rebuilt from the wake rows it wrote rather than replayed
110
+ #: from the archive. A bare id would have left the reader on the other
111
+ #: side of the click guessing, and guessing by tool name there is the
112
+ #: second copy this slot exists to avoid.
113
+ ReplayEntry = tuple[str, str, tuple[str, ...], tuple]
80
114
 
81
115
 
82
- def replay_entries(thread_id: UUID) -> List[ReplayEntry]:
116
+ def replay_entries(thread_id: UUID) -> list[ReplayEntry]:
83
117
  """A stored thread as display entries, oldest first (§27 T3/T4).
84
118
 
85
119
  Empty for a thread with no messages -- a `/new` thread that was never
86
120
  used is a real state, and the shells write their own "nothing here yet"
87
121
  line rather than this function inventing one.
88
122
  """
89
- entries: List[ReplayEntry] = []
123
+ entries: list[ReplayEntry] = []
90
124
  for message in archive_history(thread_id):
91
125
  role = message.get("role")
92
126
  if role == "user":
93
127
  text = _as_text(message.get("content"))
94
- if text:
95
- entries.append(("user", text, ()))
128
+ if message.get("harness"):
129
+ # ROADMAP_v3 §49 (SS5). The HARNESS wrote this row -- a
130
+ # background session's result -- so it must not replay under
131
+ # `you ›`, which is M8's mistake for the compaction summary.
132
+ # Its first line only, for T4's reason: the rest is program
133
+ # output the model was given, which can run to thousands of
134
+ # lines and would bury the conversation it interrupted.
135
+ header = text.split("\n", 1)[0].strip()
136
+ if header:
137
+ entries.append(("wake", header, (), ()))
138
+ elif text:
139
+ entries.append(("user", text, (), ()))
140
+ # Batch 91. The run this message started FAILED, and why. Right
141
+ # after it, because nothing else from that run was ever written:
142
+ # without this a subagent whose first call failed replays as its
143
+ # task and nothing else, which is indistinguishable from a run
144
+ # still thinking. `error` is a harness voice (META_ROLES), so
145
+ # /copy conversation leaves it out as it leaves out the live
146
+ # `[error: ...]` line.
147
+ failure = message.get("error")
148
+ if failure:
149
+ entries.append(("error", f"This run failed: {failure}", (), ()))
96
150
  elif role == "assistant":
97
- # BEFORE the answer, because that is the order it happened in
98
- # and the order the live transcript drew it in (§43 RM1 puts
99
- # one `venastine ›` above whichever came first). A replay that
100
- # reordered the turn would be the same defect as one that
101
- # reflowed it.
102
- reasoning = _reasoning_text(message.get("thinking"))
103
- if reasoning:
104
- entries.append(("thinking", reasoning, ()))
105
- text = _as_text(message.get("text"))
106
- if text:
107
- entries.append(("assistant", text, ()))
108
- for call in message.get("tool_calls") or []:
109
- entries.append(("tool", *_tool_marker(call)))
151
+ entries.extend(step_entries(
152
+ _reasoning_text(message.get("thinking")),
153
+ _as_text(message.get("text")),
154
+ message.get("tool_calls") or []))
110
155
  # role == "tool": skipped by T4. Not a gap -- see the module
111
156
  # docstring. The CALL above is the record that it happened.
112
157
  return entries
113
158
 
114
159
 
160
+ def step_entries(reasoning: str, text: str, tool_calls) -> list[ReplayEntry]:
161
+ """One model step as display entries: its reasoning, its text, then a
162
+ line per tool call.
163
+
164
+ BEFORE the answer, because that is the order it happened in and the
165
+ order the live transcript drew it in (§43 RM1 puts one `venastine ›`
166
+ above whichever came first). A replay that reordered the turn would be
167
+ the same defect as one that reflowed it.
168
+
169
+ PUBLIC SINCE ROADMAP_v3 §86 (A81), because the CLI's live turn prints
170
+ each step through this as it finishes. A replay and the turn it
171
+ replays are then one function's output over the same three things,
172
+ which is what keeps the CLI from showing a turn one way while it runs
173
+ and another way when its thread is resumed (#225).
174
+ """
175
+ entries: list[ReplayEntry] = []
176
+ if reasoning:
177
+ entries.append(("thinking", reasoning, (), ()))
178
+ if text:
179
+ entries.append(("assistant", text, (), ()))
180
+ for call in tool_calls:
181
+ entries.append(("tool", *_tool_marker(call)))
182
+ return entries
183
+
184
+
185
+ def reasoning_text(record) -> str:
186
+ """`_reasoning_text`, for a caller outside this module (§86, A81): the
187
+ CLI reads a live response's reasoning with the replay's own reader."""
188
+ return _reasoning_text(record)
189
+
190
+
115
191
  def _reasoning_text(record) -> str:
116
192
  """The displayable prose out of a stored thinking record (§44).
117
193
 
@@ -126,6 +202,11 @@ def _reasoning_text(record) -> str:
126
202
  opaque ciphertext meaningful only to the model, so rendering it would
127
203
  put a wall of base64 under a `venastine ›` label. It still travels on
128
204
  the wire; this function is about what a person sees.
205
+
206
+ The third shape arrived with ROADMAP_v3 §83 and cost the name it was
207
+ promised: a ChatGPT plan's `reasoning` item keeps its readable part in
208
+ `summary`, a list of `summary_text` parts, beside `encrypted_content`,
209
+ which contributes nothing for `redacted_thinking`'s reason.
129
210
  """
130
211
  if not isinstance(record, dict):
131
212
  return ""
@@ -133,14 +214,16 @@ def _reasoning_text(record) -> str:
133
214
  for block in record.get("blocks") or []:
134
215
  if not isinstance(block, dict):
135
216
  continue
136
- value = block.get("thinking") or block.get("text")
137
- if isinstance(value, str) and value.strip():
138
- parts.append(value.strip())
217
+ values = [block.get("thinking") or block.get("text")]
218
+ values += [part.get("text") for part in block.get("summary") or []
219
+ if isinstance(part, dict)]
220
+ parts.extend(value.strip() for value in values
221
+ if isinstance(value, str) and value.strip())
139
222
  return "\n\n".join(parts)
140
223
 
141
224
 
142
- def _tool_marker(call: dict) -> Tuple[str, Tuple[str, ...]]:
143
- """One line for one tool call, and its click targets.
225
+ def _tool_marker(call: dict) -> tuple[str, tuple[str, ...], str]:
226
+ """One line for one tool call, its click targets, and its own id.
144
227
 
145
228
  The line is the name, then a redacted param digest.
146
229
 
@@ -167,7 +250,20 @@ def _tool_marker(call: dict) -> Tuple[str, Tuple[str, ...]]:
167
250
  # (batch 65): a resumed thread that armed fewer URLs than the live
168
251
  # turn would be the archive disagreeing with the screen it came from.
169
252
  line = f"▸ {name} {digest}".rstrip() if digest else f"▸ {name}"
170
- return line, registry.call_links(name, params)
253
+ # §47, widened by §49 (SS14) and §55 (TR7). The registry is what says
254
+ # WHICH kind -- naming `spawn_subagent` here would be a second copy of
255
+ # a fact the tool already declares, free to disagree with the TUI's
256
+ # copy. `str()` because it crosses into style metadata.
257
+ #
258
+ # `if opens` SURVIVES AS A GUARD WITH NOTHING LEFT TO GUARD: TR7 gave
259
+ # `opens()` a fallback kind, so it is never empty now and the id below
260
+ # is the only thing that can leave a line unarmed. Kept rather than
261
+ # deleted because the tuple is indexed on the next line, and a reader
262
+ # who has not met TR7 should find the shape intact.
263
+ opens = registry.opens(name)
264
+ call_id = str(call.get("id") or "") if opens else ""
265
+ return (line, registry.call_links(name, params),
266
+ (opens[0], call_id) if call_id else ())
171
267
 
172
268
 
173
269
  def _as_text(value: Optional[object]) -> str:
@@ -181,3 +277,39 @@ def _as_text(value: Optional[object]) -> str:
181
277
  if value is None:
182
278
  return ""
183
279
  return value.strip() if isinstance(value, str) else str(value)
280
+
281
+
282
+ def tool_lines(thread_id: UUID) -> list[tuple[str, tuple]]:
283
+ """Every tool-call line a replay of `thread_id` draws, in order, with
284
+ what each one opens: `(line, (kind, call_id))`, the second slot empty
285
+ for a call with no id (ROADMAP_v3 §89, register item 45).
286
+
287
+ THE CLI'S ROUTE TO A CALL, and read off `replay_entries` rather than
288
+ walked separately: `/call` numbers these lines, and a second walk that
289
+ drew one line differently, or skipped one, would number a call the
290
+ reader cannot match to the line they are looking at.
291
+ """
292
+ return [(entry[1], entry[3]) for entry in replay_entries(thread_id)
293
+ if entry[0] == "tool"]
294
+
295
+
296
+ def thread_row(thread: dict) -> str:
297
+ """One row of a thread list: timestamp, first message, id (§27).
298
+
299
+ The TUI's picker draws it and the CLI's `/threads` prints it, so a
300
+ conversation reads the same in either list (moved from tui/screens.py
301
+ by §89).
302
+
303
+ `created_at` and `id` are INDEXED deliberately, not .get: a row
304
+ without either has nothing honest to render -- storage.list_threads()
305
+ always supplies both, and the id is the row's whole payload on
306
+ selection. Only `preview` is optional (.get): §27 added it, so
307
+ hand-built test rows predate it, and a missing preview degrades to an
308
+ id-only row rather than a KeyError in a test-only construction.
309
+ """
310
+ created = thread["created_at"]
311
+ stamp = (f"{created:%Y-%m-%d %H:%M}"
312
+ if hasattr(created, "strftime") else str(created))
313
+ preview = (thread.get("preview") or "").strip()
314
+ return f"{stamp} {preview} ({thread['id']})" if preview \
315
+ else f"{stamp} {thread['id']}"
package/core/session.py CHANGED
@@ -58,10 +58,27 @@ not extra_data, not anywhere. Restarting the harness is the guaranteed
58
58
  way back to the derived number.
59
59
 
60
60
  MODULE STATE, written from the UI thread and read from worker threads.
61
- Same posture as core/compaction.py's `_compacting` flag and for the same
62
- reason: these are single assignments of an int or a tuple, so there is no
63
- half-set state to observe. Tests clear it in an autouse fixture, which is
64
- the rule every other module-level cache in this project follows.
61
+ What makes a concurrent read safe here is not serialisation but the pair
62
+ binding: every entry is a single assignment of a tuple, and a peer run
63
+ reading it gets a value only if the (provider, model) it asks about is the
64
+ one that was set -- so another agent's number is not merely unlikely to be
65
+ read, it does not match. Tests clear it in an autouse fixture, which is the
66
+ rule every other module-level cache in this project follows.
67
+
68
+ THIS USED TO CITE core/compaction.py's `_compacting` FLAG as the same
69
+ posture, and that symbol has not existed since batch 75 -- which batch 148
70
+ is where anyone noticed. It was replaced by
71
+ `_reentrancy = threading.local()` with `_is_compacting()` /
72
+ `_set_compacting()`, deliberately NOT aliased -- the comment there says why:
73
+ "`if _compacting:` against a callable is always true, so a reader left
74
+ holding the old name has to fail at import instead of quietly disabling
75
+ every compaction in the process". So the precedent had been reversed from a
76
+ module flag to per-thread state, because NA9 removed the premise that one
77
+ agent runs at a time, and a reader checking this module against its stated
78
+ example found an argument against the sentence that sent them there. The
79
+ precedent is still worth citing -- for the DIFFERENCE: compaction's state is
80
+ a re-entrancy flag, where a second reader must see what the first did, and
81
+ these are per-pair bindings, where it must not.
65
82
  """
66
83
 
67
84
  import logging
@@ -113,14 +130,21 @@ def trigger_any() -> Optional[int]:
113
130
  """The trigger override IGNORING the pair binding.
114
131
 
115
132
  Exists for exactly one caller: compaction.pin_measurements, which
116
- computes #89's cap as PIN_MAX_TRIGGER_FRACTION x the trigger and has
117
- no model in scope to match against. That caller takes the MINIMUM of
118
- this and the configured trigger, which is safe under every binding --
119
- a raised session trigger leaves the cap stricter than it needs to be,
120
- and a lowered one pulls the cap down with it. Reading the configured
121
- trigger alone would let `/trigger 12k` leave pins capped at 20k, able
122
- to floor a thread permanently above its own trigger, which is the
123
- defect #89 exists to prevent.
133
+ computes #89's cap as PIN_MAX_TRIGGER_FRACTION x the trigger. That
134
+ caller takes the MINIMUM of this and the configured trigger, which is
135
+ safe under every binding -- a raised session trigger leaves the cap
136
+ stricter than it needs to be, and a lowered one pulls the cap down with
137
+ it. Reading the configured trigger alone would let `/trigger 12k` leave
138
+ pins capped at 20k, able to floor a thread permanently above its own
139
+ trigger, which is the defect #89 exists to prevent.
140
+
141
+ ITS FALLBACK, SINCE BATCH 148, rather than its only answer. That caller
142
+ had no model in scope and now takes an optional one, because #89's cap
143
+ is a fraction of the trigger that FIRES and since batch 44 that is
144
+ derived per model (batch 148). With the pair it resolves the trigger
145
+ through thresholds(), which reads the correctly-BOUND session override;
146
+ this read is what remains for a call from outside a run, where there is
147
+ no pair to bind against.
124
148
 
125
149
  Do not reach for this anywhere the pair IS available.
126
150
  """