Skip to content

fix(api): page list routes, refuse unknown session/end, fill the Recall token budget - #48

Merged
possiblyneal merged 9 commits into
mainfrom
fix/api-bounds
Sep 22, 2026
Merged

possiblyneal merged 9 commits into
mainfrom
fix/api-bounds

Conversation

@possiblyneal

@possiblyneal possiblyneal commented Sep 22, 2026 •

Copy link
Copy Markdown
Owner

Summary

API cluster of #31 (tickets #40, #41, #42). Branched from fix/llm-timeout-hard-cap, so the diff against main also shows that branch's commits until it merges.

Audit: other kv.update callers that do not check the key first

kv.update on the in-process Engine creates a missing key as an empty object (SqliteState.update). Every caller in src/:

Caller Scope Checks first? Note
api::session::end (src/triggers/api.ts) sessions now yes this PR
mem::observe (src/functions/observe.ts) sessions yes reads the row; when missing and the payload carries project + cwd it creates the Session deliberately (implicit create), otherwise no-op
event::session::ended (src/triggers/events.ts) sessions no subscriber on topic agentmemory.session.ended; nothing in src/ publishes that topic, so it is dormant. Left as is

Follow-up

The in-process memory_sessions MCP tool reads the sessions scope directly, unsorted and ignoring limit; it does not go through this route. Out of #40's scope, tracked separately.

Test plan

  • npx vitest run test/list-routes-paging.test.ts (18 new, including a ghost row without startedAt and the memories route)
  • npx vitest run test/session-end-unknown.test.ts (3 new)
  • npx vitest run test/search.test.ts (2 new: oversized record skipped, truncated false when everything fits)
  • npx vitest run test/memories-pagination.test.ts (two source-grep tests replaced by behaviour tests above)
  • npm run build (typecheck gate)
  • npm test

🤖 Generated with Claude Code

neal added 9 commits September 21, 2026 15:54
fetchWithTimeout clamped every budget to a 170s HARD_BUDGET_CAP_MS while
openai.ts still reported the unclamped value in its timeout error, so an
AGENTMEMORY_LLM_TIMEOUT_MS of 480000 aborted at 170s and claimed 480000ms.
Broker-side records confirm it: 86 client-disconnect 499s on the general
route, p50 duration 169,996ms, p90 170,004ms, none past 400s.

The cap existed to stay under iii's 180s invocation timeout. ADR 0001
deleted that runtime — the in-process Engine has no invocation timeout, so
the ceiling bounded against a limit that no longer exists and turned slow
local models into provider failures, which then tripped the circuit breaker
and failed unrelated calls.

The caller's timeout is now the total budget for all attempts plus sleeps,
honored exactly. test/fetch-timeout.test.ts asserted the clamp; it now
asserts the opposite.

Generated-By: Claude Opus 5 (1M context)
groupKey joined its two parts with a raw NUL byte. One NUL is enough for
git and grep to classify the whole file as binary, so every search over
src/engine/inproc/sdk.ts silently returned nothing and `file` reported it
as data rather than source.

U+001F separates just as well. The key is only ever a streamItems Map key
and is never persisted, so nothing migrates.

Generated-By: Claude Opus 5 (1M context)
CLAUDE.md opened straight into architecture, so every feature argument
started from mechanism. Lead with the goal instead: right Memory, right
moment, right scope, least record that restates it.

Generated-By: Claude Opus 5 (1M context)
Score every open upstream issue on severity x difficulty, cross-link the PRs
that claim to fix each one, and score the 168 PRs that reference no open issue
by how much of their diff lands in files this fork tracks.

Every row carries a disposition: wont-fix for what is out of scope here (no iii
engine, no npm publish, no Windows CI, no deploy tree, no adapter for the host),
already-fixed for what this tree already carries, candidate for the working set.

The 17 high-severity/low-difficulty issues and the 35 high-relevance candidate
PRs were then opened against this tree and read. Rows checked that way carry a
status whose leading token says what the read found; 15 claims turned out to be
already fixed here and moved out of the candidate set. A row with no status is
still upstream's claim, not a verified defect.

Generated-By: Claude Opus 5 (1M context)
Generated-By: Claude Fable 5.1
GET /agentmemory/sessions, /semantic and /procedural returned the whole
scope. Each now takes limit (default 100, or "all") and offset, keeps its
collection key, and adds total/limit/offset. Sessions are sorted
newest-first after the agent filter and before the page is taken, so
the standalone MCP client's existing ?limit= and the recap, handoff and
session-history skills get the most recent Sessions. Session Summaries
are fetched only for the page returned.

Closes #40. Refs #31, rohitg00#1022, rohitg00#1324.

Generated-By: Claude Fable 5.1
kv.update creates a missing key, so POST /agentmemory/session/end with
an unknown id invented a Session row holding only endedAt/status. The
route now answers 404 session_not_found and fires nothing. The Engine's
update-creates-missing-key behaviour is unchanged.

Other kv.update callers on the sessions scope: mem::observe updates only
after reading the row (implicit create otherwise); event::session::ended
updates without a check but no publisher emits its topic.

Closes #41. Refs #31, rohitg00#1251.

Generated-By: Claude Fable 5.1
applyTokenBudget returned at the first record that would overflow, so
one large result ranked early hid every smaller one behind it. The loop
now skips the record and continues; truncated is true whenever a record
was skipped. Output is unchanged when everything fits.

Closes #42. Refs #31, rohitg00#1232.

Generated-By: Claude Fable 5.1
…ugh parsePage

Review corrections for #48. The newest-first sort threw on the ghost
rows that carry only endedAt/status; they now sort last. The memories
route shares parsePage (default 100, limit=all in place of the 5000
cap), and the viewer plus `agentmemory status` pass limit=all on
sessions so their counts still cover the whole store.

Generated-By: Claude Fable 5.1
@possiblyneal

Copy link
Copy Markdown
Owner Author

Code review: standard scan (Standards, Spec, Correctness/Logic)

Standards

No hard violations. Judgement calls resolved: memories route unified onto parsePage (user's choice), limit vocabulary now number | "all" everywhere, dead update stub removed from the paging test mock. parseOptionalInt left as is (lacks the all branch and positivity guard). Signed off at 8fde836.

Spec

One finding, fixed: the newest-first sort threw on Session rows without startedAt (35 such rows in the live store); they now sort last, with a test. In-process memory_sessions (unsorted, ignores limit) is out of #40 scope and tracked as a follow-up issue. Signed off at 8fde836.

Correctness/Logic

Definite bug (same sort crash) fixed. Behaviour change addressed: viewer and agentmemory status pass limit=all on sessions so whole-store counts hold. Eviction edge case (404 at stop for a Session evicted while open) recorded in the PR body. Shape change noted, not a bug: memories limit is "all" or a number instead of null. Signed off at 8fde836.

Totals: Standards 0 hard / 5 judgement, Spec 1, Correctness 1 definite / 1 behaviour change. Worst 3: sort crash on ghost rows (fixed), viewer/status 100 cap (fixed), memories default change for external callers (documented).

Reviewed-Head: 8fde836

@possiblyneal
possiblyneal merged commit 0019bef into main Sep 22, 2026
6 checks passed
possiblyneal pushed a commit that referenced this pull request Sep 22, 2026
@possiblyneal
possiblyneal deleted the fix/api-bounds branch September 25, 2026 21:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant