@yahyahammad/venastine 0.3.12 → 0.3.14

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.
package/core/loop.py CHANGED
@@ -53,9 +53,11 @@ from core.client import (
53
53
  call_model_stream,
54
54
  context_window_for,
55
55
  effort_for,
56
+ reasoning_not_echoed,
56
57
  )
57
58
  from core.events import LoopEvent
58
59
  from core.memory import ConversationMemory
60
+ from core.replay import reasoning_text
59
61
  from safety.policy_enforcement import redact_diagnostic_text
60
62
 
61
63
  # §27 (T1). The loop is where a thread's kind is DECIDED -- it knows which
@@ -668,6 +670,87 @@ def _already_said(notices, kind: str) -> bool:
668
670
  n["kind"] == kind for n in notices)
669
671
 
670
672
 
673
+ # ROADMAP_v3 §95. A REASONING-ONLY reply: the step returned readable
674
+ # reasoning and neither text nor a tool call. Measured on an
675
+ # OpenAI-compatible provider, 33 of its 316 turns came back this way, every
676
+ # one right after a tool result, with the model's tool call written out in
677
+ # its own markup INSIDE the reasoning -- the server only turns markup into a
678
+ # call when it appears after the model's end-of-reasoning delimiter, and
679
+ # reasoning is all this loop received. Before §95 such a step ended the turn
680
+ # as `complete` and said nothing, to the person or to the model.
681
+ #
682
+ # RO2: the loop asks ONCE per run, through a harness row, and a second
683
+ # reasoning-only reply ends the turn with a notice. The row's first line is
684
+ # also the live notice's text, so the line a person sees while the turn
685
+ # runs is the line its replay draws (RO5).
686
+ HARNESS_REASONING_ONLY = "reasoning_only"
687
+ REASONING_ONLY_END = "reasoning_only_end"
688
+ REASONING_ONLY_HEADER = (
689
+ "[harness] The last reply was reasoning only: no answer and no tool "
690
+ "call reached the harness, so nothing ran.")
691
+ _REASONING_ONLY_NUDGE = (
692
+ REASONING_ONLY_HEADER + "\n"
693
+ "A tool call written inside reasoning is not run. Make the call through "
694
+ "the tool-calling interface, or write the answer as the reply itself.")
695
+ _REASONING_ONLY_AGAIN = (
696
+ "The model replied with reasoning only again after the harness asked, "
697
+ "so this turn ends without an answer.")
698
+ _REASONING_ONLY_LAST_STEP = (
699
+ "The model replied with reasoning only on the last step this turn "
700
+ "allows, so it ends without an answer.")
701
+ # (provider, model) pairs whose echo hint was logged this process (RO7).
702
+ # Keyed like context_limit()'s warn-once set and for its reason: a session
703
+ # that switches model must still hear about the second one.
704
+ _reasoning_only_warned: set = set()
705
+
706
+
707
+ def _reasoning_only(response) -> bool:
708
+ """RO1. Readable reasoning, no text and no tool call.
709
+
710
+ READABLE reasoning, through the replay's own reader: a Google signature
711
+ block or Anthropic's `redacted_thinking` carries no prose, and a step
712
+ that held only those had nothing in it to have gone missing. Text that
713
+ is only whitespace counts as none, because none of it reaches a person.
714
+ """
715
+ return (not response.tool_calls
716
+ and not (response.text or "").strip()
717
+ and bool(reasoning_text(response.thinking)))
718
+
719
+
720
+ def _reasoning_only_reply(memory, provider_name, model, notices, *,
721
+ nudge: bool, again: bool):
722
+ """RO2/RO5. Ask the model once more, or say why the turn ends here.
723
+
724
+ Persist before emit (#42): the harness row is written before the
725
+ notice that describes it is yielded. The row is a user-role entry
726
+ because that is the only shape the model can be handed between two
727
+ steps on every wire, and `mid_turn` keeps it from opening a turn (RO3):
728
+ the compaction floor and the reopening request both read a user row as
729
+ the start of one.
730
+ """
731
+ key = (provider_name, model)
732
+ if key not in _reasoning_only_warned and reasoning_not_echoed(
733
+ provider_name):
734
+ _reasoning_only_warned.add(key)
735
+ logger.warning(
736
+ "%s/%s replied with reasoning only: no text and no tool call. "
737
+ "Some models expect their earlier reasoning back during a tool "
738
+ "loop; if this one does, set \"echoes_reasoning\": true for %s "
739
+ "in providers.json.", provider_name, model, provider_name)
740
+ if nudge:
741
+ memory.add_harness_message(
742
+ _REASONING_ONLY_NUDGE,
743
+ {"kind": HARNESS_REASONING_ONLY, "mid_turn": True})
744
+ notice = {"kind": HARNESS_REASONING_ONLY,
745
+ "text": REASONING_ONLY_HEADER}
746
+ else:
747
+ notice = {"kind": REASONING_ONLY_END,
748
+ "text": (_REASONING_ONLY_AGAIN if again
749
+ else _REASONING_ONLY_LAST_STEP)}
750
+ notices.append(notice)
751
+ yield LoopEvent(notice=notice)
752
+
753
+
671
754
  def _compactor_depth(context) -> int:
672
755
  """Where a compaction started from THIS loop sits in the agent stack.
673
756
 
@@ -1894,7 +1977,12 @@ class RunAgentLoop:
1894
1977
  activity=activity, depth=_compactor_depth(context))
1895
1978
 
1896
1979
  response = None
1897
- for _ in range(max_steps):
1980
+ # ROADMAP_v3 §95 (RO2). Whether this run has already asked the model
1981
+ # to follow a reasoning-only reply. ONE ask per run: a model that
1982
+ # answers the ask with reasoning only again is not going to be
1983
+ # talked out of it by a second, and every ask is a billed step.
1984
+ nudged = False
1985
+ for step in range(max_steps):
1898
1986
  # §61 CN2, the step boundary -- and ABOVE the reset below,
1899
1987
  # which is the whole reason it sits here rather than at the
1900
1988
  # foot of the body. The response it reads is the PREVIOUS
@@ -2065,6 +2153,18 @@ class RunAgentLoop:
2065
2153
  return
2066
2154
 
2067
2155
  if not response.tool_calls:
2156
+ # ROADMAP_v3 §95. Below D20 and the budget stop, so the
2157
+ # reasoning-only step is persisted and paid for exactly
2158
+ # like any other, and a turn already over budget stops
2159
+ # rather than spending a step on the ask.
2160
+ if _reasoning_only(response):
2161
+ ask = not nudged and step < max_steps - 1
2162
+ yield from _reasoning_only_reply(
2163
+ memory, provider_name, model, notices,
2164
+ nudge=ask, again=nudged)
2165
+ if ask:
2166
+ nudged = True
2167
+ continue
2068
2168
  response.stop_reason = "complete"
2069
2169
  yield LoopEvent(
2070
2170
  final_response=response, stop_reason=response.stop_reason,
package/core/memory.py CHANGED
@@ -57,6 +57,7 @@ from storage import (
57
57
  pinned_through,
58
58
  save_message,
59
59
  set_pinned,
60
+ starts_turn,
60
61
  turn_start_ids,
61
62
  update_thread_extra,
62
63
  )
@@ -366,7 +367,9 @@ class ConversationMemory:
366
367
  """
367
368
  mark_turn_failed(self.thread_id, error)
368
369
  for entry in reversed(self._messages):
369
- if entry.get("role") == "user":
370
+ # The row storage chose (ROADMAP_v3 §95, RO3): a harness row
371
+ # the loop wrote inside the run did not start it.
372
+ if starts_turn(entry):
370
373
  entry["error"] = error
371
374
  break
372
375
 
@@ -204,6 +204,21 @@ def _check(raw_text: str, validate: Optional[Callable]) -> None:
204
204
 
205
205
 
206
206
  def _parse_corrective(error: ValueError, raw_text: str) -> str:
207
+ if not raw_text.strip():
208
+ # ROADMAP_v3 §95 (RO6). Nothing to quote, and quoting nothing under
209
+ # "Start of your failed output" was measured to mislead: a model
210
+ # whose whole reply had arrived as reasoning read the empty quote
211
+ # as its reasoning being the invalid output, and resolved to stop
212
+ # reasoning. Say what the harness actually received.
213
+ return (
214
+ "Your last response contained no text at all, so there was no "
215
+ "JSON to parse. Anything written only in your reasoning is not "
216
+ "part of the response, and a tool call written there is not "
217
+ "run.\n\n"
218
+ "Respond again with ONLY valid JSON -- no preamble, no prose, "
219
+ "no code fence, just the JSON your original instructions "
220
+ "asked for."
221
+ )
207
222
  return (
208
223
  f"Your last response did not parse as valid JSON.\n\n"
209
224
  f"Parse error:\n{error}\n\n"
@@ -225,7 +225,10 @@ def _translate(pass_id: str, stream, corpus=None):
225
225
  second rendering of a question already on
226
226
  screen is not observability.
227
227
  notice a pass's compaction notices, forwarded as
228
- trace LINES. M6 makes these backstop-only,
228
+ trace LINES -- and since §95 its
229
+ reasoning-only notices, labelled `notice`
230
+ rather than `compaction` (RO8). M6 makes
231
+ the compaction ones backstop-only,
229
232
  but "rare" is not "silent" -- §21's rule
230
233
  has no exception for the pipeline, and a
231
234
  backstop fold rewrites what the REST of
@@ -266,9 +269,15 @@ def _translate(pass_id: str, stream, corpus=None):
266
269
  yield PipelineEvent(kind="pass_activity", pass_id=pass_id,
267
270
  chars=streamed)
268
271
  if event.notice:
272
+ # ROADMAP_v3 §95 (RO8). Labelled by what the notice IS: the loop
273
+ # emits a reasoning-only notice inside a pass too, and the trace
274
+ # called every notice a compaction.
275
+ what = ("compaction"
276
+ if str(event.notice.get("kind", "")).startswith(
277
+ "compaction") else "notice")
269
278
  yield PipelineEvent(
270
279
  kind="trace_line",
271
- text=f"compaction during {pass_id}: {event.notice['text']}")
280
+ text=f"{what} during {pass_id}: {event.notice['text']}")
272
281
  if event.tool_call_start:
273
282
  name = event.tool_call_start.get("name")
274
283
  names[event.tool_call_start.get("id")] = name
package/main.py CHANGED
@@ -57,6 +57,8 @@ from core import ansi, config_loader, shell_sessions, workspace_trust
57
57
  from core.cancel import CancelToken
58
58
  from core.loop import (
59
59
  DEFAULT_PROVIDER,
60
+ HARNESS_REASONING_ONLY,
61
+ REASONING_ONLY_END,
60
62
  RunAgentLoop,
61
63
  advertisement_facts,
62
64
  agent_turn,
@@ -245,6 +247,10 @@ class _LiveTurn:
245
247
  # is popped out of its result and referenced by nothing else, so
246
248
  # its id could be reused by a later one.
247
249
  self._noticed: list = []
250
+ # ROADMAP_v3 §95 (RO5). The turn's last step already printed, ahead
251
+ # of the notice saying it ended the turn; `finish` then has only
252
+ # the notices left to print.
253
+ self._final_printed = False
248
254
 
249
255
  def __call__(self, event) -> None:
250
256
  try:
@@ -282,7 +288,25 @@ class _LiveTurn:
282
288
  return
283
289
  self._noticed.append(notice)
284
290
  text = notice.get("text") if isinstance(notice, dict) else None
285
- if text:
291
+ kind = notice.get("kind") if isinstance(notice, dict) else None
292
+ if kind in (HARNESS_REASONING_ONLY, REASONING_ONLY_END):
293
+ # ROADMAP_v3 §95 (RO5). Both describe the step that just
294
+ # FINISHED with no tool call, so nothing else will print it:
295
+ # print it first, in the order a replay draws it. Only what
296
+ # streamed -- a turn nobody watched has nothing held, and its
297
+ # last step still prints at `finish`.
298
+ reasoning = "".join(self._reasoning).strip()
299
+ held_text = "".join(self._text)
300
+ if reasoning or held_text:
301
+ self._step(reasoning, held_text, [])
302
+ self._final_printed = kind == REASONING_ONLY_END
303
+ if not text:
304
+ return
305
+ if kind == HARNESS_REASONING_ONLY:
306
+ # The first line of the row the harness wrote, which a replay
307
+ # prints in this role.
308
+ _print_entry("wake", text)
309
+ else:
286
310
  print(f"— {ansi.for_display(text)} —")
287
311
 
288
312
  def finish(self, response) -> None:
@@ -295,10 +319,13 @@ class _LiveTurn:
295
319
  self._notice(notice)
296
320
  calls = [{"id": c.id, "name": c.name, "input": c.input}
297
321
  for c in getattr(response, "tool_calls", None) or ()]
298
- if any(c["id"] in self._announced for c in calls):
322
+ if self._final_printed or any(c["id"] in self._announced
323
+ for c in calls):
299
324
  # This step's reasoning and text printed with its first tool
300
325
  # line: the turn ran out of steps or was stopped between its
301
- # tool calls, after the step itself had finished.
326
+ # tool calls, after the step itself had finished. Or, since
327
+ # §95, ahead of the notice that its reasoning-only reply ended
328
+ # the turn.
302
329
  reasoning, text = "", ""
303
330
  else:
304
331
  reasoning = reasoning_text(getattr(response, "thinking", None))
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yahyahammad/venastine",
3
- "version": "0.3.12",
3
+ "version": "0.3.14",
4
4
  "description": "A from-scratch agentic harness: tool-using chat plus a ten-pass self-critiquing research pipeline.",
5
5
  "keywords": [
6
6
  "agent",
package/pyproject.toml CHANGED
@@ -18,7 +18,7 @@ build-backend = "setuptools.build_meta"
18
18
 
19
19
  [project]
20
20
  name = "venastine-research-harness"
21
- version = "0.3.12"
21
+ version = "0.3.14"
22
22
  description = "A from-scratch agentic harness: tool-using chat plus a ten-pass self-critiquing research pipeline."
23
23
  readme = "README.md"
24
24
  # The same words as package.json's `keywords`, in the same order: what a
@@ -49,11 +49,17 @@ TIERED = "tiered"
49
49
  # containment constant would read as correct and match, so the Python
50
50
  # names must differ even though the strings cannot.
51
51
  CONTAINED_MODE = "contained"
52
+ # ROADMAP_v3 §56 (JV11). `tiered`, plus a decision model asked about the
53
+ # calls `tiered` would ask about -- and only the single, contained ones
54
+ # (JV12). `tiered` itself is unchanged (JV1): this is a mode beside it.
55
+ CLASSIFIED_MODE = "classified"
52
56
  NEVER = "never"
53
57
 
54
58
  # Strictest first. The order is what validate_mode's message lists, so a
55
59
  # reader of the error sees the modes the way config.yaml describes them.
56
- APPROVAL_MODES = (ALWAYS, TIERED, CONTAINED_MODE, NEVER)
60
+ # `classified` sits after `tiered` because it asks about a subset of what
61
+ # `tiered` asks about, and before `contained`, which asks about less.
62
+ APPROVAL_MODES = (ALWAYS, TIERED, CLASSIFIED_MODE, CONTAINED_MODE, NEVER)
57
63
 
58
64
 
59
65
  def validate_mode(value: str, setting_name: str) -> str:
@@ -111,6 +111,67 @@ import config
111
111
  # ---------------------------------------------------------------------------
112
112
 
113
113
 
114
+ @dataclass(frozen=True)
115
+ class ClassifierSettings:
116
+ """The `classified` mode's decision model, as launch bound it
117
+ (ROADMAP_v3 §56, JV8).
118
+
119
+ Frozen here beside `shell_approval_mode`, and for its reason: every one
120
+ of these is an authority key, and a value bound at import cannot be
121
+ moved by an environment variable or a `config.X = ...` later in the
122
+ process. `core/decision_classifier.py` is what asks the model; this is
123
+ only what it is told. No key: `credential` NAMES the providers.json
124
+ entry, which is read when a request is made and never held.
125
+ """
126
+
127
+ style: str = "systemone"
128
+ url: str = ""
129
+ model: str = ""
130
+ credential: str = ""
131
+ timeout_s: float = 10.0
132
+ on_fail: str = "ask"
133
+ # ((metric name, threshold), ...), in core/decision_classifier.METRICS
134
+ # order. A test holds the names and keys below against that table.
135
+ thresholds: tuple = ()
136
+
137
+ @property
138
+ def configured(self) -> bool:
139
+ """Whether there is anything to ask. An unconfigured classifier is
140
+ not a launch failure (JV20): every question it would have answered
141
+ asks, which is `tiered`, and `/classifier` and the badge say so."""
142
+ return bool(self.url.strip() and self.model.strip())
143
+
144
+ def threshold(self, name: str) -> float:
145
+ for metric_name, value in self.thresholds:
146
+ if metric_name == name:
147
+ return float(value)
148
+ raise KeyError(name)
149
+
150
+
151
+ #: (metric name, config.py name) for the four thresholds. The metric names
152
+ #: are core/decision_classifier.METRICS's, re-stated rather than imported
153
+ #: for the layering reason in ClassifierSettings' docstring, and pinned.
154
+ CLASSIFIER_THRESHOLD_KEYS = (
155
+ ("containedness", "SHELL_CLASSIFIER_MIN_CONTAINEDNESS"),
156
+ ("risk", "SHELL_CLASSIFIER_MAX_RISK"),
157
+ ("modification", "SHELL_CLASSIFIER_MAX_MODIFICATION"),
158
+ ("network", "SHELL_CLASSIFIER_MAX_NETWORK"),
159
+ )
160
+
161
+
162
+ def classifier_from_config() -> ClassifierSettings:
163
+ return ClassifierSettings(
164
+ style=config.SHELL_CLASSIFIER_STYLE,
165
+ url=config.SHELL_CLASSIFIER_URL,
166
+ model=config.SHELL_CLASSIFIER_MODEL,
167
+ credential=config.SHELL_CLASSIFIER_CREDENTIAL,
168
+ timeout_s=float(config.SHELL_CLASSIFIER_TIMEOUT_S),
169
+ on_fail=config.SHELL_CLASSIFIER_ON_FAIL,
170
+ thresholds=tuple((name, float(getattr(config, key)))
171
+ for name, key in CLASSIFIER_THRESHOLD_KEYS),
172
+ )
173
+
174
+
114
175
  @dataclass(frozen=True)
115
176
  class Posture:
116
177
  """What this process is allowed to do to itself and its host.
@@ -120,7 +181,8 @@ class Posture:
120
181
  legal statement anywhere in the process.
121
182
  """
122
183
 
123
- # "always" / "tiered" / "contained" / "never" -- validated at bind time, so a typo
184
+ # "always" / "tiered" / "classified" / "contained" / "never" --
185
+ # validated at bind time, so a typo
124
186
  # is a startup failure and never a policy that quietly means
125
187
  # something else (the argument capability.validate_mode makes).
126
188
  shell_approval_mode: str
@@ -160,6 +222,11 @@ class Posture:
160
222
  # real distinction: the constant is the permanent answer and this is
161
223
  # one run's, and the environment may only ever turn redaction OFF.
162
224
  redact_off_env: bool
225
+ # ROADMAP_v3 §56 (JV8). The decision model `classified` asks. Defaulted,
226
+ # unlike the fields above, because it is read only under one mode and
227
+ # every other mode is complete without it; `_from_config` always
228
+ # supplies it.
229
+ shell_classifier: ClassifierSettings = ClassifierSettings()
163
230
 
164
231
  def unsafe_reasons(self) -> list[tuple[str, str]]:
165
232
  """Every active posture that weakens the shipped defaults, as
@@ -201,6 +268,22 @@ class Posture:
201
268
  "in the container without network runs without asking, "
202
269
  "including code the agent wrote itself; host reads and "
203
270
  "network commands still ask"))
271
+ elif self.shell_approval_mode == "classified":
272
+ # ROADMAP_v3 §56 (JV11, JV12). The first layer in the harness
273
+ # that WIDENS rather than tightens, by design -- so it is on the
274
+ # badge whenever it is on, and says who decides.
275
+ settings = self.shell_classifier
276
+ who = (f"{settings.model} at {settings.url}"
277
+ if settings.configured else
278
+ "none is configured yet, so everything it would answer "
279
+ "asks, as under tiered")
280
+ reasons.append((
281
+ "shell: classified",
282
+ "SHELL_APPROVAL_MODE is 'classified' -- a decision model "
283
+ f"({who}) decides whether a single command that runs in the "
284
+ "container, and that tiered would ask about, runs without "
285
+ "asking; compound commands, host reads, the host fallback, "
286
+ "WSL and SSH still ask"))
204
287
  # §48 (CE6). Under "always" the pair is NOT "no ask": the mode check
205
288
  # returns before the fallback opt-in is ever read, so every command
206
289
  # asks, the host fallback included. Measured, and the badge said
@@ -305,6 +388,7 @@ def _from_config() -> Posture:
305
388
  allow_ssh_backend=bool(config.ALLOW_SSH_BACKEND),
306
389
  redact_tool_outputs=bool(config.REDACT_TOOL_OUTPUTS),
307
390
  redact_off_env=_redact_off_from_env(),
391
+ shell_classifier=classifier_from_config(),
308
392
  )
309
393
 
310
394
 
@@ -1622,6 +1622,30 @@ def _feed_sudo_password(proc, secret) -> None:
1622
1622
  # a reason to make the guard start its life with an exception.
1623
1623
  _SHELL_METACHARACTERS = re.compile(r"""[;|&$`><(){}!#~'"\\]""")
1624
1624
 
1625
+
1626
+ def single_command(command) -> bool:
1627
+ """Whether *command* is ONE command a decision model may be asked
1628
+ about (ROADMAP_v3 §56, JV12).
1629
+
1630
+ ROADMAP_v2 §28 recorded this limit before §56 existed -- "the model
1631
+ never sees compound shell" -- because routing compound commands to a
1632
+ model to save prompts "collapses the injection argument entirely". So:
1633
+ no shell metacharacter, quoting and escaping included, exactly the set
1634
+ `_is_inert` refuses; and no control or invisible character, because a
1635
+ newline is a command separator to `sh -c`, which every non-inert
1636
+ command reaches. The set above does not list one only because an INERT
1637
+ command never reaches a shell.
1638
+
1639
+ Total: the gate hands this whatever the model emitted.
1640
+ """
1641
+ if not isinstance(command, str):
1642
+ return False
1643
+ stripped = command.strip()
1644
+ if not stripped or _SHELL_METACHARACTERS.search(stripped):
1645
+ return False
1646
+ return all(ch == " " or (ch.isprintable() and not ch.isspace())
1647
+ for ch in stripped)
1648
+
1625
1649
  # Dangerous flags for commands that remain in INERT_COMMANDS.
1626
1650
  #
1627
1651
  # BATCH 117 MADE THIS TABLE TRUE, because it was not. The claim beside
package/storage.py CHANGED
@@ -660,6 +660,36 @@ def _decode_harness(raw):
660
660
  return value if isinstance(value, dict) and value.get("kind") else None
661
661
 
662
662
 
663
+ def starts_turn(row: dict) -> bool:
664
+ """Whether this row OPENS a turn: a user row, unless the harness wrote it
665
+ inside one (ROADMAP_v3 §95, RO3).
666
+
667
+ A turn starts at a user message -- the wrapper adds one, then the loop
668
+ appends assistant and tool rows until it stops -- and six readers were
669
+ written on that rule: the turn list behind `completed_turns`, the fold
670
+ boundaries and the pin cap in core/compaction.py, the request a
671
+ mid-turn watermark re-adds, and the row a failure is recorded on, here
672
+ and in core/memory.py. Since §95 the loop can write a user row
673
+ INSIDE a turn, to ask the model to follow a reasoning-only reply, and
674
+ such a row carries `mid_turn: true` in its harness record. Read as a
675
+ turn start, it would move the current-turn floor past the turn's own
676
+ earlier steps while the turn is still running -- the floor the mid-turn
677
+ compaction valve calls safe by construction -- and a mid-turn
678
+ watermark would re-add it in place of the person's request.
679
+
680
+ Takes either shape: an `_ordered_rows` dict, whose `harness` is the
681
+ stored JSON string, or a neutral message, whose `harness` is decoded.
682
+ `is True`, A29's rule: a record carrying a quoted "true" still opens a
683
+ turn, as every harness row did before §95.
684
+ """
685
+ if row.get("role") != "user":
686
+ return False
687
+ harness = row.get("harness")
688
+ if isinstance(harness, str):
689
+ harness = _decode_harness(harness)
690
+ return not (isinstance(harness, dict) and harness.get("mid_turn") is True)
691
+
692
+
663
693
  def _decode_images(raw):
664
694
  """A tool row's stored images (ROADMAP_v3 §81, IM2), or None.
665
695
 
@@ -874,10 +904,10 @@ def _turn_opener_index(rows: list[dict], span: list[dict]) -> list[int]:
874
904
  """
875
905
  if not span or len(span) >= len(rows):
876
906
  return []
877
- if rows[len(span)]["role"] == "user":
907
+ if starts_turn(rows[len(span)]):
878
908
  return []
879
909
  for index in range(len(span) - 1, -1, -1):
880
- if span[index]["role"] == "user":
910
+ if starts_turn(span[index]):
881
911
  return [index]
882
912
  return []
883
913
 
@@ -995,13 +1025,14 @@ def turn_start_ids(thread_id: UUID) -> list[UUID]:
995
1025
  """Ids of the rows that BEGIN each turn, oldest first.
996
1026
 
997
1027
  A turn starts at a user message: the wrapper adds one, then the loop
998
- appends assistant and tool rows until it stops. §21's M4 needs this
1028
+ appends assistant and tool rows until it stops. `starts_turn` says
1029
+ which user rows, since §95 wrote one inside a turn. §21's M4 needs this
999
1030
  because a fold boundary that lands anywhere else can separate an
1000
1031
  assistant message from its tool results, and a tool_result with no
1001
1032
  preceding tool_use is an HTTP 400 on Anthropic -- a hard wire error,
1002
1033
  not a degraded answer. M5's "keep the last N turns" needs it too.
1003
1034
  """
1004
- return [m["id"] for m in _ordered_rows(thread_id) if m["role"] == "user"]
1035
+ return [m["id"] for m in _ordered_rows(thread_id) if starts_turn(m)]
1005
1036
 
1006
1037
 
1007
1038
  def message_ids_from(thread_id: UUID, message_id: UUID) -> list[UUID]:
@@ -1047,6 +1078,10 @@ def mark_turn_failed(thread_id: UUID, error: str) -> bool:
1047
1078
 
1048
1079
  Returns False for a thread with no user row. Does not stamp
1049
1080
  last_activity_at the way save_message does: a failure is not a message.
1081
+
1082
+ The newest row that STARTS a turn (ROADMAP_v3 §95, RO3), which skips a
1083
+ harness row the loop wrote inside the run -- the run did not start
1084
+ there, and replay draws the failure under the request that did.
1050
1085
  """
1051
1086
  with Session(engine) as session:
1052
1087
  statement = (
@@ -1055,7 +1090,9 @@ def mark_turn_failed(thread_id: UUID, error: str) -> bool:
1055
1090
  .where(MessageLog.role == "user")
1056
1091
  .order_by(MessageLog.created_at.desc(), MessageLog.id.desc())
1057
1092
  )
1058
- row = session.exec(statement).first()
1093
+ row = next((candidate for candidate in session.exec(statement)
1094
+ if starts_turn({"role": candidate.role,
1095
+ "harness": candidate.harness})), None)
1059
1096
  if row is None:
1060
1097
  return False
1061
1098
  row.error = error