queued and
investigating, then ends as needs_input, concluded, partial, cancelled, or
failed.
Conversations and follow-ups
A Conversation is the ordered context a person talks to. Each Message may open a new Investigation. Follow-ups reuse bounded prior Findings and citations without copying raw provider payloads or private model reasoning. Recent context includes up to 12 user and assistant Messages, oldest first, with their timestamps. Assistant Messages come from completed Investigations in this Conversation and carry their structured Conclusion for continuity; another Conversation’s private answers are not included. Long entries are shortened and marked as truncated. This bounded context is not a complete memory of the Conversation. When recent context is insufficient, the investigator can read bounded older pages from the same Conversation. Those pages preserve Message order, corrections, canonical answers, and their Investigation identities. Stored history is context rather than a current request or fresh evidence. Prior Findings retain their observation time and evidence window and can be reconsidered after a correction, refresh request, or window change. Completed andneeds_input Investigations never resume. Send a new Message to create the next turn.
To ask about a specific interval, send both windowFrom and windowUntil when posting
a Message, or when creating a Conversation with its first Message. Use RFC3339 timestamps
with an offset. The start is inclusive and the end exclusive; the end cannot be in the
future. Values are normalized to UTC microseconds and echoed on the accepted Message and
Investigation. Invalid windows return 400 before accepting the request.
Without explicit bounds, ordinary questions cover at least the preceding 24 hours;
Incident questions retain their Incident-derived window. The first queued Message fixes
the next batch’s window. Later Messages inherit it, or may supply the same normalized
bounds. Different bounds return 409; resend after that batch opens. Waiting or restarting
does not move an accepted window.
The Conversation API returns its first 50 turns as execution metadata, in ascending turn
order. Replies live in the ordered Message transcript. To read more,
pass turnsNext as cursor to GET /api/v1/conversations/{conversation}/turns.
That endpoint accepts limit from 1 to 200 (default 50) and returns turns and next.
Continue until next is null. Cursors belong to the same Organization and Conversation;
search and selectable sorting are not supported. The recent Message tail is separate.
The structured Conclusion, assistant Message, and final activity event are saved together,
so reconnecting sees the same outcome. Failed final writes do not report a completed reply.
An interrupted or superseded worker cannot append results or activity after losing ownership.
Messages sent during an active Investigation wait for its completion. An Organization can
have up to 100 unassigned user Messages waiting across its Conversations, alongside the
separate limit for waiting Investigations. When capacity is full, new Messages are refused;
retry after work progresses. Accepted Messages remain stored. Older backlogs larger than
the limit drain in chronological batches of at most 100.
Each Investigation receives the complete Messages assigned to it, in order, with their
authors and timestamps. Those assigned user Messages are the authoritative request; there
is no separate stored question preview.
Optional history and inventory are omitted first if the initial request is too large.
If the complete assigned batch still cannot fit, the result is needs_input: its limitation
identifies the unprocessed Message sequences and asks you to narrow or split the request.
Those Messages stay stored; send a new Message to continue. No part of that batch is
reported as answered.
For example, “Why did checkout latency rise?” opens one Investigation. “Does the deploy
at 09:42 explain it?” becomes a new Message and a new bounded Investigation in the same
Conversation, retaining prior cited Findings without changing the first result.
An Investigation can remain inconclusive when access, telemetry, time, or execution bounds
prevent a defensible answer.
Findings and citations
A Finding is a factual statement supported by one or more numbered Tool Runs. Its kind iscause, contributing_factor, observation, or ruled_out. A causal Finding must
explain the mechanism that produced impact. Conclusion status expresses assessment
certainty; Findings do not carry a second confidence classification.
Investigations represent other uncertainty as hypotheses or limitations instead.
Final hypotheses are supported, ruled_out, or unresolved. Supported is weaker than
verified. Limitations name missing access, telemetry, contradictions,
unresolved assumptions, or essential human input.
Citations show what OpenCluster read, not that the source was complete or correct. Check
source timestamps, bounded windows, contradictions, and truncation before accepting a
Finding.
In API results, runRefs names Tool Run ordinals in the containing Investigation.
Reused Findings use evidenceRefs pairs of investigationId and toolRunOrdinal;
follow the referenced Investigation’s detail and runs to resolve them. Two Investigations
can each have Run 1, so the ordinal alone cannot identify reused evidence.
Unavailable or unauthorized Investigations return the same 404. If a cited Tool Run
has been pruned, the Finding retains its reference and detail reports a missing_telemetry
limitation; it does not substitute another run or claim fresh verification.
Action Proposals
An Action Proposal can describe mitigation, rollback, verification, a permanent fix, or monitoring. It states a rationale, verification procedure, and supporting Tool Runs. OpenCluster never executes it. For example, a rollback proposal may cite a Kubernetes Event and a GitHub deployment, and explain how to verify latency and error rate afterward. The citations support the proposal; they do not execute or approve the change.Postmortems
A Postmortem belongs to one resolved Incident. A person triggers generation; OpenCluster does not create one automatically. The draft distinguishes system evidence from Conversation testimony and remainsdraft until reviewed.
Missing impact, resolution, owner, or deadline facts appear as Needs human input. rather
than being invented. A correction creates a new revision, and review records the reviewer
without turning testimony into system evidence. Postmortems remain nested under Incidents
in OSS v0.1 and are not automatically published.
Use Run your first investigation for the
end-to-end procedure.