Skip to content
Merged
Show file tree
Hide file tree
Changes from 70 commits
Commits
Show all changes
82 commits
Select commit Hold shift + click to select a range
8c42d32
feat(engine): record where a turn's history starts and open the windo…
claude Oct 28, 2026
822db69
feat(core): historySummary capability and fold, and a capability hist…
claude Oct 28, 2026
f8afedb
feat(workforce,client): beforeAnswer step and historyStart on the cli…
claude Oct 28, 2026
966b1d9
FIX-2154: wire the Teammates lab to the real packages
claude Oct 28, 2026
830c32d
FIX-2154: record the goal's verdicts and controls, file the gaps
claude Oct 28, 2026
944bbca
FIX-2154: say user, not person, in the lab's comments
claude Oct 28, 2026
2fd0c09
FIX-2154: name the Teammates lab's server config as a fallow entry
claude Oct 28, 2026
95fe4cf
FIX-2154: keep host.mts's own constants unexported
claude Oct 28, 2026
4d397d8
FIX-2154: answer review on the adapter and the goal
claude Oct 28, 2026
0660cd6
FIX-2154: read the feed's snapshot again when the history moves while…
claude Oct 28, 2026
fa17caf
test(goals): history window goal check, and the changeset (FIX-1613)
claude Oct 28, 2026
ed88b9f
FIX-2154: hand the lab's Codex runs only the environment Codex needs
claude Oct 28, 2026
e8207d9
FIX-2154: follow a task's run by the session its card already names
claude Oct 28, 2026
e7ea812
FIX-2154: name the issue in the Codex pass-list changeset
claude Oct 28, 2026
76912b7
docs: summarizing turns past the history window (FIX-1613)
claude Oct 28, 2026
2b7d23d
fix(core): a failed fold records the oldest unfolded turn, so lost tu…
claude Oct 28, 2026
b4a59d6
Merge remote-tracking branch 'origin/fix/fix-1613' into claude/projec…
claude Oct 28, 2026
82caf8a
fix(engine): history after a mark that has not settled starts after i…
claude Oct 28, 2026
9812eaa
fix(core): a fold is stale when any other fold committed, not only on…
claude Oct 28, 2026
aace8e4
FIX-2154: the Teammates lab keeps what left its history window, and d…
claude Oct 28, 2026
6693940
fix(core): a fold keeps the summarizer's key points with its summary …
claude Oct 28, 2026
bb004bc
Merge remote-tracking branch 'origin/fix/fix-1613' into claude/projec…
claude Oct 28, 2026
ae48471
fix(core): FIX-1613 keep a turn sharing the mark's start time once th…
claude Oct 28, 2026
04cd8b9
fix(engine): FIX-1613 trim the window's extra row before reordering it
claude Oct 28, 2026
7c98af9
fix(engine): FIX-1613 order same-millisecond turns by id everywhere
claude Oct 28, 2026
4e01de4
FIX-2289: render worker text as Markdown in the Teammates lab
claude Oct 28, 2026
068ae50
FIX-2154: step 4 waits for each answer, and the summary keeps earlier…
claude Oct 28, 2026
920da34
FIX-2289: keep MessageResponse internal to the lab's Markdown component
claude Oct 28, 2026
0fa923c
fix(engine,core): FIX-1613 a summary mark newer than the loaded window
claude Oct 28, 2026
cac199d
fix(core): FIX-1613 waiting turns no longer take the fold's places
claude Oct 28, 2026
5c49f84
Merge remote-tracking branch 'origin/claude/project-thread-e54cfm' in…
claude Oct 28, 2026
e40aca5
FIX-2154: step 3 may redden under the step-4 controls, with the reason
claude Oct 28, 2026
a2caae9
FIX-2154: the lab's inventory table, current
claude Oct 28, 2026
649e971
FIX-2289: read the lab's entries as shown in the goal check
claude Oct 28, 2026
fd11163
Merge remote-tracking branch 'origin/claude/project-thread-e54cfm' in…
claude Oct 28, 2026
b854692
FIX-2154: step 4's verdict log
claude Oct 28, 2026
8d89ce6
Merge remote-tracking branch 'origin/fix/fix-1613' into claude/projec…
claude Oct 28, 2026
7102c9e
FIX-2289: show a worker's answer as it is written
claude Oct 28, 2026
c2b6995
Merge remote-tracking branch 'origin/main' into claude/project-thread…
claude Oct 28, 2026
0e07742
fix(engine): FIX-1613 a retried turn keeps its place in turns()
claude Oct 28, 2026
cb5024e
Merge remote-tracking branch 'origin/main' into fix/fix-1613
claude Oct 28, 2026
c295253
Merge main into FIX-2154 lab branch
claude Oct 28, 2026
7366a3c
Merge remote-tracking branch 'origin/claude/project-thread-e54cfm' in…
claude Oct 28, 2026
2fbbedc
FIX-2154: the lab's inventory table, current
claude Oct 28, 2026
14fa6b0
Merge remote-tracking branch 'origin/fix/fix-1613' into claude/projec…
claude Oct 28, 2026
6318c46
fix(core): FIX-1613 a resumed pending turn stays pending; lost check …
claude Oct 28, 2026
7bd40d0
Teammates lab: an unlinked task answer is not drawn as failed; lead n…
claude Oct 28, 2026
5ca7328
fix(engine): FIX-1613 a retried turn read by id has nothing to read
claude Oct 28, 2026
f00be8d
Merge remote-tracking branch 'origin/fix/fix-1613' into claude/projec…
claude Oct 28, 2026
00e8f07
FIX-2154: step 4 reads lead's answer once it is fully drawn
claude Oct 28, 2026
b82f66d
Teammates lab: researcher answers only through sendMessage; goal wait…
claude Oct 28, 2026
0ca38f2
fix(engine): FIX-1613 read turns by id fresh, and ended turns as empty
claude Oct 28, 2026
2c3596a
FIX-2154: record step 4's pass at 00e8f07
claude Oct 28, 2026
1f46ec3
Merge #4079 at b82f66de into claude/project-thread-6ydn0c
claude Oct 28, 2026
73315bd
Merge remote-tracking branch 'origin/fix/fix-1613' into claude/projec…
claude Oct 28, 2026
6cff931
FIX-2154: the lab's inventory table, current
claude Oct 28, 2026
a8a7e5f
FIX-1613: read a shared dependency's history once through dynamic uses
claude Oct 28, 2026
406590f
FIX-1613: say turns were lost when settled turns leave behind an olde…
claude Oct 28, 2026
d2034b1
FIX-1613: list a continuable interrupted turn as open
claude Oct 28, 2026
9074de4
Merge remote-tracking branch 'origin/fix/fix-1613' into claude/projec…
claude Oct 28, 2026
872a7c1
Merge remote-tracking branch 'origin/main' into fix/fix-1613
claude Oct 28, 2026
bf6daac
test(orchestration): a steer turn's stop reason says user, as FIX-215…
claude Oct 28, 2026
4af4dd3
Merge remote-tracking branch 'origin/fix/fix-1613' into claude/projec…
claude Oct 28, 2026
8fbfca6
Store a received worker message as a user line in the recipient's his…
jhoffner Oct 28, 2026
8daa709
FIX-1613: resolve a history mark that names the resuming request
claude Oct 28, 2026
1fde086
FIX-1613: a fold keeps the request running it pending when it moves p…
claude Oct 28, 2026
39a8c5c
Merge remote-tracking branch 'origin/fix/fix-1613' into claude/projec…
claude Oct 28, 2026
224f1ae
Merge main (with #4079) into claude/project-thread-6ydn0c
claude Oct 28, 2026
dd547f7
FIX-1613: list a turn that settled after the window loaded as open
claude Oct 28, 2026
bee72e8
Merge remote-tracking branch 'origin/fix/fix-1613' into claude/projec…
claude Oct 28, 2026
b734df3
FIX-1613: drop a pending turn that retention deleted before it settled
claude Oct 28, 2026
1840bd2
FIX-2154: place the divider by the order turns started
claude Oct 28, 2026
f04b409
Merge remote-tracking branch 'origin/fix/fix-1613' into claude/projec…
claude Oct 28, 2026
c9d25cc
Merge remote-tracking branch 'origin/main' into claude/project-thread…
claude Oct 28, 2026
129959f
FIX-2154: regenerate the Teammates lab inventory after merging main
claude Oct 28, 2026
741c030
FIX-2154: keep the summary's mark when it has a hole; the hole only d…
claude Oct 28, 2026
1202202
Merge remote-tracking branch 'origin/main' into claude/project-thread…
claude Oct 28, 2026
0ff68c4
Merge remote-tracking branch 'origin/main' into claude/project-thread…
claude Oct 29, 2026
5d93f27
FIX-2154: regenerate the Teammates lab inventory after merging main
claude Oct 29, 2026
0066eb7
Merge remote-tracking branch 'origin/main' into claude/project-thread…
claude Oct 29, 2026
5e1a3f9
FIX-2154: regenerate the Teammates lab inventory after merging main
claude Oct 29, 2026
792d751
FIX-2154: goal verdicts on the merged real-tools lab
claude Oct 29, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .changeset/a-conversation-remembers-past-its-window.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
"@flow-state-dev/core": minor
"@flow-state-dev/engine": minor
"@flow-state-dev/client": minor
"@flow-state-dev/workforce": minor
---

A conversation longer than its history window can keep what it said before the window (FIX-1613). `utility.historySummary({ summarize })` returns a `capability` for the generator that answers and a `fold` step to run before it: the fold writes the turns about to leave the window into a running summary, the capability hands that summary to the model and starts the generator's history after it. A capability preset may now declare `history` (a query added to that generator's history reads; generators only). The engine records `historyStart` on a request when earlier turns are out of view, exposes `ctx.session.window`, `ctx.session.items.turns()` and `history({ afterRequestId })`, and the client's request summary carries `historyStart`. Workforce's `defineAgentWorkerFlow` takes `beforeAnswer`, a block run before the worker answers.
78 changes: 77 additions & 1 deletion apps/docs/docs/advanced/generator-context.md
Original file line number Diff line number Diff line change
Expand Up @@ -320,7 +320,83 @@ Numeric turn limits are cheap and predictable: pick one when the conversation sh

A turn whose items are entirely sub-agent output, or any other items that don't contribute to LLM history, still counts against `{ turns: N }` but contributes no messages. This keeps the windowing logic at the request level. If sub-agent-heavy turns become common in your flow, prefer a token budget.

Tool-aware compaction (rewriting older tool calls into shorter summaries) and goal-aware pruning (dropping turns that aren't relevant to the current goal) are deliberately not part of this default. They belong to higher-level patterns that layer on top of this windowing primitive.
### Summarizing turns past the window

A turn that leaves the window is gone from the model's view. If the user said something important in turn 1 of a 60-turn conversation, a 50-turn window loses it. `utility.historySummary` keeps a running summary of the turns before the window and gives it to the answering generator.

It returns `{ capability, fold, resource }`:

- `capability` goes in the answering generator's `uses`. It puts the summary in that generator's context as an `<earlier-conversation>` section, and starts the generator's history reads after the last turn in the summary, so no turn is read twice.
- `fold` is a step you run before that generator. It adds turns to the summary before they leave the window.
- `resource` is the session-scoped resource that holds the summary.

```ts
import { defineFlow, generator, sequencer, utility } from "@flow-state-dev/core";
import { z } from "zod";

const earlier = utility.historySummary({
summarize: utility.summarizer({
name: "earlier-turns",
model: "openai/gpt-6-luna",
granularity: "detailed",
objectives: [
"The input's `summary` is the summary so far and `turns` are newer turns: write one summary of both, never of the turns alone.",
"Keep every name, code and number the user stated, word for word.",
],
}),
});

const answer = generator({
name: "answer",
model: "openai/gpt-6-luna",
prompt: "You are a helpful assistant.",
history: true,
uses: [earlier.capability],
});

const inputSchema = z.object({ message: z.string() });

defineFlow({
kind: "chat",
session: { historyWindow: { turns: 50 } },
actions: {
say: {
inputSchema,
block: sequencer({ name: "chat", inputSchema }).tap(earlier.fold).step(answer),
userMessage: (input) => input.message,
},
},
});
```

`summarize` is any block that takes `{ summary: string | null, turns: LLMMessage[] }` and returns `{ summary: string, keyPoints?: string[] }`. `summary` is the summary so far (`null` the first time) and `turns` are the turns being added, oldest first. Key points are kept as a list under the summary. Core's `utility.summarizer` fits as is. Give it an objective like the first one above that says what `summary` and `turns` are. Without it, a small model will sometimes summarize only the new turns and drop what the earlier summary held.

`historySummary` also takes `name`, the resource's name and storage key (default `historySummary`).

**When it folds.** Folding starts before turns leave. When a turn that isn't summarized yet drifts into the oldest quarter of the window, the fold summarizes up to a quarter of the window's turns at once. With a 50-turn window, that's 12 turns at a time. A turn that hasn't finished yet (still running, or waiting on an approval) is skipped and folded once it finishes.

**When summarizing fails.** A failed `summarize` call doesn't fail the turn. The turn answers with the summary it had, and the next turn tries again. Folding starts about a quarter of the window early, so `summarize` can fail on roughly that many turns in a row without losing anything. If it keeps failing longer than that, turns leave the window unsummarized, and the resource's `complete` turns `false` and stays `false`.

**When the fold step is missing.** If the capability is installed but `fold` never runs, the first turn after a turn has left the window throws an error that names the missing step.

**Showing it in a UI.** Each request in `client.sessions.requests(sessionId)` can carry `historyStart: { requestId }`: the oldest earlier turn its history window still held, when earlier turns had fallen out of it. It's absent while every earlier turn was in the window. Draw a divider above that turn; the turns above it are in the summary.

The resource exposes `throughRequestId` (the last turn in the summary), `complete` and `folds` to the client, under `snapshot.resources.session.historySummary.clientData` in `client.sessions.state(sessionId)`. `complete` is `false` while a skipped turn is still waiting to be folded, and stays `false` once a turn has left the window without being summarized (for example, when you add the summary to a conversation that was already past its window). Use `complete` to label the divider "earlier turns summarized" or "some earlier turns are missing".

To keep the summary in context but read the window's full history, switch off the narrowing: `uses: [earlier.capability.presets({ history: false })]`. The model then reads some turns twice, once in the summary and once word for word.

On a Workforce agent worker, pass the fold as `beforeAnswer` and the capability in `uses`:

```ts
import { defineAgentWorkerFlow } from "@flow-state-dev/workforce";

defineAgentWorkerFlow({
uses: [earlier.capability],
beforeAnswer: earlier.fold,
});
```

The summary covers whole turns. Rewriting older tool calls into shorter summaries, or dropping turns that aren't relevant to the current goal, is up to your own flow.

## Authoring the prompt as an external file

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
{
"colours": ["amber", "cobalt", "crimson", "jade", "ochre", "violet", "silver", "teal", "umber", "saffron"],
"animals": ["heron", "otter", "lynx", "badger", "falcon", "marmot", "gecko", "walrus", "ibis", "tapir"],
"numbers": [214, 377, 452, 519, 608, 731, 846, 903, 128, 265],
"fillers": [
"In one sentence, why does bread go stale?",
"Give me one tip for keeping houseplants alive.",
"In one sentence, how does a bicycle stay upright?",
"Name a good stretch for a stiff neck, briefly.",
"In one sentence, what makes a sourdough starter work?",
"Suggest a name for a small black cat.",
"In one sentence, why is the sea salty?",
"What is a quick way to chill a drink?",
"In one sentence, how do noise-cancelling headphones work?",
"Give me a one-line idea for a rainy Sunday.",
"In one sentence, why do onions make you cry?",
"What is one way to remember people's names?",
"In one sentence, how does a heat pump heat a house?",
"Suggest a simple breakfast with eggs, in one line.",
"In one sentence, why do leaves change colour in autumn?",
"Give me one tip for writing a clear email.",
"In one sentence, what does a thermostat do?",
"Name one board game for two players, briefly.",
"In one sentence, why does ice float?",
"What is a good habit for better sleep, in one line?"
]
}
26 changes: 26 additions & 0 deletions goals/history-window/remembers-turns-past-the-window/goal.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# history-window › it remembers turns past the window

**Issue:** FIX-1613 (with FIX-2154 G1)
**Outcome:** A conversation longer than its history window still answers from what was said before the window. The person tells the chat something in turn 1, talks about other things until turn 1 has left the window, then asks for it back and gets it.
**Input:** The goal's own chat flow: an answer generator with `history: true` that installs `utility.historySummary(...).capability` and runs its `fold` step first, with core's `summarizer` as the summarize block. SQLite store, no memory capability, a real model. The fact (a sailboat name of a colour, an animal and a number) is picked at run time and the filler questions are shuffled, from `fixtures/conversation.json`. Default window 8 and 14 turns; `GOAL_WINDOW=50 GOAL_TURNS=60` must pass too. Each conversation's host is disposed and started again on the same SQLite file the turn after the first fold.
**Signal:**
- `w:answer` the last answer holds all three words of the fact, in every run (`GOAL_RUNS`, default 3).
- `w:out-of-window` none of the user or assistant messages the answer model was sent on the last turn holds the fact; read from the model calls themselves, recorded by wrapping the model resolver.
- `w:mark` the last request in `client.sessions.requests` carries `historyStart` naming a turn of the session, and the session's `historySummary` resource, read through `client.sessions.state`, is `complete: true` through a turn of the session.
- `w:folds` at least `min(3, folds the rule predicts)` folds ran, at least one after the restart, and the stored summary is under 4,000 characters.
**Anti-game:** Nothing asserts on the summary's wording, and the summarize block is the real `summarizer` on the real model: a mocked summarizer, or a check on the summary text, passes while the answer generator never sees it. The flow has no memory and its prompt never holds the fact. Every graded list is floored with `tell.over`, so an empty read (no requests, no recorded model call, no answer) is CAN'T TELL, not PASS.
**Model:** real — openai/gpt-5.4-mini, through the AI Gateway (`goalModel`)
**Run:** `pnpm tsx goals/history-window/remembers-turns-past-the-window/run.mts`
**Controls:**
- `GOAL_CONTROL=no-summary` builds the flow without the capability and the fold step (the flow as it was before). Must fail `w:answer`.
- `GOAL_CONTROL=no-mark` patches out the engine's `historyStart` write (main before this change). Must fail `w:mark`.

The summarizer is configured with an objective that names its input: `summary` is the summary so far and `turns` the newer turns. Without it, `gpt-5.4-mini` sometimes summarized only the new turns and dropped the fact (2 of 8 conversations on 2026-10-28); with it, 6 of 6 kept it.

## Verdict log
| Date | Commit | Model | Verdict | Notes |
|------|--------|-------|---------|-------|
| 2026-10-28 | fa17caf | openai/gpt-5.4-mini | FAIL (expected) | `GOAL_CONTROL=no-summary`: `w:answer` "I don't have that information."; `w:mark` and `w:folds` fail too (no resource) |
| 2026-10-28 | fa17caf | openai/gpt-5.4-mini | FAIL (expected) | `GOAL_CONTROL=no-mark`: only `w:mark` fails, "the last request carries no historyStart"; the answer still held the fact |
| 2026-10-28 | fa17caf | openai/gpt-5.4-mini | PASS | 3 of 3 answers held the fact (6 of 6 earlier, before the answer's replies were kept in history); 4 folds each (1 before the restart), summaries 1,254–1,777 characters; the answer model read 11 messages, user and assistant, all after the mark |
| 2026-10-28 | fa17caf | openai/gpt-5.4-mini | PASS | `GOAL_WINDOW=50 GOAL_TURNS=60 GOAL_RUNS=1`: 2 folds, the second after the restart before turn 41; answer held the fact ("teal lynx 731"), rerun after the summarizer objective and `itemVisibility` were added |
Loading
Loading