> ## Documentation Index
> Fetch the complete documentation index at: https://opentrain.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Manage a Live Job With Shared Context
> Run a safe context-first loop for triage, coordinated actions, message reconciliation, and handoffs across OpenTrain agents.
Use shared job context when an agent needs to answer questions such as:
* What should we do next?
* Who is blocked, and why?
* Which messages still need an employer response?
* Which deterministic attention signals are highest priority?
* Are any evaluators stale or incomplete?
* Which action is another manager already handling?
* What changed since this agent last checked?
* Who is ready under the current workflow?
This guide describes the operating loop shared by the API, CLI, and MCP server. See [Shared Job Context](/docs/developers/concepts/shared-job-context) for the data model and provenance rules.
## Before you start
You need:
* an employer account or employer team membership;
* access to the specific job;
* `jobs:read` to inspect context; and
* `jobs:write` for supported decisions, observations, actions, checkpoints, and handoffs.
The job also needs a valid workflow before anyone can be derived as ready. If the context reports a missing or invalid workflow, resolve that inconsistency before relying on readiness totals.
Shared Job Context is delivered by the matching app and agent-package release.
Before using these examples against a deployment, confirm `GET
/api/public/v1/capabilities` reports the `job_operations` family as
`available`. The base shared-context family requires CLI/MCP 0.8.0+ or SDK
0.7.0+. The deterministic signals, typed policies, and generated operating
guide used below require CLI/MCP 0.10.0+ or SDK 0.9.0+. Automatic
cross-command synchronization, intents, proposals, and scoped overlays require
CLI/MCP 0.11.0+ or SDK 0.10.0+. If npm `latest` is older, the release has not
reached that package yet.
## The operating loop
```text theme={null}
resolve job
↓
read context
↓
writable session: sweep with that revision
↓
continue with each returned contextRevision until hasMore=false
↓
read context again
↓
review guide, attention, health, blockers, inconsistencies, and claims
↓
claim one action or declare one spontaneous-work intent
↓
re-read the affected canonical source
↓
act with expected versions and idempotency
↓
verify the result
↓
complete/release action + checkpoint + handoff
```
### 1. Resolve one exact job
Do not infer the target from a similar title alone. Resolve the job ID and confirm the acting token can access it.
If an employer team member has organization access but not access to that job, OpenTrain denies the context request. Ask an authorized employer admin to update job or folder access rather than trying to broaden the token.
### 2. Read, then reconcile a writable session
Always begin with a normal context read. It returns the `contextRevision`
required by the first sweep. The same coherent snapshot includes the current
attention queue, evaluator health, effective-policy summary, and Job Operating
Guide digest. The agent does not need separate full scans merely to discover
candidate priorities.
In a writable management session, sweep once at startup. This covers:
* the agent is starting a new session;
* an external provider may have changed asynchronously;
* stale people or incomplete reconciliation;
* a previous operation timed out before returning its receipt; or
* the job has been idle long enough that freshness is uncertain.
A sweep consumes pending canonical events and reconciles bounded canonical drift
on the server. The client does not maintain the platform event cursor. When a
sweep returns `hasMore: true`, call it again with that response's
`contextRevision`. Continue until `hasMore` is false, then read the context again
so triage uses the newly derived snapshot. A read-only session does not sweep.
Save the returned context version as the precondition for the work you plan to do.
With CLI/MCP 0.11.0 or SDK 0.10.0, later covered calls carry this session
forward automatically. Inspect the additive `sync` and `syncCoverage` fields
on each response. `sync.conflicts`, `sync.recommendations`, and
`sync.nextOperations` can change what the agent should do next without another
full-system scan. `syncCoverage.coverage: none` means that call did not refresh
shared context; perform a covered context read before relying on it.
### 3. Triage before acting
Review these sections in order:
1. **Evaluator health, inconsistencies, and unknowns** — stale or incomplete evidence can invalidate otherwise simple status conclusions.
2. **Job Operating Guide, objective, workflow, and effective policies** — they define the current operating rules and what “next” and “ready” mean.
3. **Fresh priority signals and open blockers** — treat them as an investigation queue, grouped by impact and dependency.
4. **Message response signals** — treat them as prompts to inspect a conversation, not as message content.
5. **Actions and claims** — avoid duplicating work already owned by another manager.
6. **Recent changes or delta** — identify records that changed since your last checkpoint.
Do not collapse different gates into one count. “Assessment passed,” “identity complete,” “training complete,” and “production ready” answer different questions.
An attention score does not prove a root cause or authorize a mutation. A repeated LMS failure may point to unclear instructions, a difficult question, an assignment problem, or a genuine knowledge gap. Claim the signal, inspect the canonical evidence, and record the verified outcome.
Capability recommendations also help the agent discover existing OpenTrain
workflows. For example, a confusing message may suggest an individualized LMS
retraining plan. Treat that suggestion as a product-discovery prompt:
1. inspect the conversation, current Instructions, training history, and
relevant evidence;
2. explain the verified misunderstanding;
3. generate a no-write retraining outline or assignment plan; and
4. ask the employer to approve it before creating content or assigning a
Project To-do.
The recommendation does not prove that retraining is necessary and never
authorizes a write by itself.
### 4. Claim the action
Claim coordinated work before performing it. Include the expected action or context version.
When work begins from an attention signal, use the signal-claim operation. It atomically creates or reuses the linked action and acquires its lease. A signal is claimable only while its condition is active, its evaluation is fresh, and its effective triage is open or acknowledged. Stale, incomplete, live-snoozed, dismissed, and shadow-rule signals cannot be claimed. Acknowledge, snooze, and dismiss are triage operations; they do not claim ownership.
If another owner has an unexpired claim:
* choose different work;
* wait for the current owner; or
* coordinate outside the system and have the owner release it.
Do not steal an active claim because the task looks urgent. If a claim expired, refresh the context before claiming it again.
If the work is spontaneous and has no shared action yet, declare an intent
before starting it. Another matching intent returns the current owner instead
of creating parallel work. Resolve the intent when it is complete, abandoned,
or replaced by a canonical action.
When a manager proposes a different workflow or policy, do not silently follow
the competing local instruction. Show the current team policy, the alternative,
and the conflict. Ask whether to continue under the current policy or submit a
reviewable Job Operations proposal. Proposal review records agreement; it does
not execute the proposed change.
### 5. Re-read the canonical source
Context helps an agent choose the right work, but the source record is the final pre-action check.
For a message, re-read the latest authorized conversation and thread. Confirm that:
* no employer teammate already answered;
* a later AI trainer message did not reopen the question;
* the requested requirement is still incomplete;
* the conversation type still matches the relationship; and
* the participant and conversation remain visible to the acting user.
For the guarded send, pass that exact latest message ID. Pass `null` only when
the authorized conversation was actually observed empty. Use the exact
synchronized managed-send operation (CLI `manager messages send`; MCP
`opentrain_send_managed_job_message`), not the generic message tool. OpenTrain
resolves the authorized Job Message or Proposal Message binding, validates the
guarded state, and commits the message and shared-context advance atomically.
It rejects the send if any reviewed state changed.
For a Project To-do, assessment, contract, milestone, or training action, fetch that canonical record and confirm its current status and version.
### 6. Apply the action safely
For a consequential context-plane write:
* send the expected context revision;
* send the expected action version when changing an action;
* use a stable idempotency key for one semantic operation; and
* include evidence IDs instead of copying sensitive source content.
The underlying domain API remains the correct place to change a proposal, contract, message, Project To-do, milestone, or other canonical resource. Do not simulate the change by recording a context observation.
Use a stable idempotency key for the managed message. It must be 8–128
characters using letters, numbers, `.`, `_`, `:`, or `-`. The operation
requires both `messages:write` and `messages:manage`.
### 7. Verify before completion
After an operation succeeds, fetch the affected record again and confirm the intended state.
Then:
* complete the coordinated action with its result evidence;
* release it if no work was performed or a different owner must continue;
* acknowledge the newest processed context version; and
* add a concise handoff when the next session needs more than the structured state already shows.
A timeout is not proof that the write failed. Refresh with the same idempotency key before creating a replacement action.
## Handle version conflicts
A `409` stale-version response means another manager or event changed relevant state after your read.
Do not overwrite it. Instead:
1. fetch the latest context or delta;
2. re-read the affected canonical records;
3. inspect the other manager's action result or claim;
4. discard the plan if it is obsolete; and
5. retry only if it remains correct.
The context version is a safety precondition, not a cursor that the client may increment locally.
## Record durable judgment carefully
Record a decision when an authorized employer judgment must persist across sessions, such as an approved exception or manual assessment outcome. Record a typed policy when the change governs the workflow or agent behavior across the job.
For MCP hosts that consume instruction resources, the generated Markdown guide
is available at `opentrain://jobs/{jobId}/operations/guide`. It is a read-only
projection of the same effective policies and context state; do not edit or
treat it as a second authority. Use the structured guide tool when you need its
exact context revision and checksum.
When the current projection refers to prior judgment, list the durable decision
history before acting. Use the decision and observation cursors to continue
until the relevant history is complete; do not infer supersession from a
truncated context summary.
Include:
* the exact subject and scope;
* the decision type and operative value;
* a concise rationale;
* privacy-safe evidence references;
* the effective and optional expiration time; and
* the decision it supersedes, when applicable.
Use an observation for non-authoritative evidence. Do not use an observation to create a policy or override a mandatory gate.
Do not edit a local shared prompt or free-form “agent memory” as the policy source. Supersede the active typed policy with the exact current decision ID, then read the new context and Job Operating Guide checksum before continuing.
Choose an enforcement target that matches what the platform actually changes. A `GUIDE` policy with status `APPLIED` is published coordination guidance for managers and agents; it is not proof of runtime enforcement. For example, the training production gate can canonically switch between course completion and scored assessment review. A separate instruction to complete one production task and stop belongs in an attributed guide policy such as `OPERATING_RULE.first-production-task-limit` unless a canonical task limit exists.
## End a session cleanly
Before the agent stops:
* release claims it will not finish;
* complete actions whose canonical results were verified;
* acknowledge the last processed context version;
* resolve or transfer spontaneous-work intents;
* record unresolved blockers with their current owner; and
* create a handoff only for continuation details that are not already structured in the context.
The next authorized agent should be able to start from the job context without receiving the previous chat transcript.
## Related
Understand provenance, readiness, versions, claims, and privacy boundaries.
Combine job-scoped context with account updates and webhooks.
Use the canonical assignment control plane for job requirements.
Handle conflict envelopes, paging, rate limits, and retries.