Repository navigation
docs(api): envelope exceptions and post-flush OME latency - #455
Merged
Merged
Conversation
Findings from driving a live server the way the Claude Code plugin does: - `POST /ome/trigger` returns its body bare (no `request_id` / `data`), while the "always wrapped" sentence and every `/memory/*` section imply otherwise; say so at both places, and mention the `201` on a knowledge upload. - `POST /cascade/quiesce` was in the OpenAPI spec but nowhere in the docs; list it with the other operational endpoints. - Agent cases, skills and profiles are produced by OME strategies after `/flush` has returned (14 s / 32 s observed), and `cascade.pending` does not cover that window; the eventual-consistency section only described index lag. Also list the agent-track extraction gates that yield no case. - `EXTRACTION_EMPTY` was described as covering empty uploads; those are rejected earlier as `INVALID_INPUT`. Align with knowledge.md. - knowledge.md: read endpoints trail writes (~1 s after create, ~11 s after delete observed); PATCH does not. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
gloryfromca
changed the title
A delete that runs before the cascade has indexed the document's topics also answers 204 (no indexed topics were removed), so the status code alone cannot tell "nothing existed" from "removed before indexing". Point readers at a read-back with the index lag in mind. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
8 of 12 tasks
Adversarial review of the eventual-consistency paragraph against everalgo: the gate that actually decides under EverOS defaults is `min_tool_call_rounds=3` — no case below three tool-call rounds, which also makes the previously listed "assistant turn under ~200 tokens" gate unreachable — and the EverOS `agent_case_skipped_by_algo` event carries ids only; the reason is on everalgo's own log line. Also: `quiesce` is safe to call twice rather than "idempotent" (it reports `quiesced=True` both times), knowledge GET reads SQLite rather than "the index", the ~1 s figure is hedged like the others, the PATCH sentence names why it escapes the lag, and the delete status-code sentence is left as on main because PR #456 changes what a delete-before-index reports. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
gloryfromca
force-pushed
the
docs/api-contract-notes
branch
from
September 24, 2026 05:56
baeb59d to
3843ed4
Compare
0xKT
approved these changes
Sep 24, 2026
arelchan
self-requested a review
September 24, 2026 08:45
This was referenced Sep 24, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Contract clarifications found by driving a live Tier-3 server the way the Claude Code plugin does (SessionStart → recall → capture → flush, then every documented edge). Docs only; no behaviour change.
POST /ome/triggerreturns a bare body (norequest_id/data), unlike every/memory/*and/knowledge/*endpoint; the "always wrapped" sentence now names the exceptions, and the201on a knowledge upload.POST /cascade/quiescewas inopenapi.jsonbut not in the docs; listed with the operational endpoints./flushreturns (14 s for the case, 32 s for the skill observed);cascade.pendingdoes not cover that window. The eventual-consistency section only described index lag. The agent-track extraction gates (no tool use + short assistant turn, trajectory ending on a user message) are listed so integrators know why a session yields no case.EXTRACTION_EMPTYwas described as covering empty uploads; those are rejected earlier asINVALID_INPUT. Aligned with knowledge.md.PATCHdoes not.Area
Verification
Every statement is a literal observation from
.work_context/agent_sim/logs/trace.jsonl(local, not committed) againsteveros server starton this branch's parent commit; the OME latency numbers come from the server log (agent_case_extracted,agent_skills_extractedtimestamps vs the/flushrequest id).make check-cjkclean.Checklist
Notes for Reviewers
Whether
/ome/triggershould instead be wrapped in the SuccessEnvelope for consistency is a contract decision left open here; this PR documents what the server does today. Consumers of the bare shape:docs/reflection.mdexamples,tests/e2e/test_reflection_e2e.py,tests/unit/.../test_ome.py.🤖 Generated with Claude Code