> ## 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.
# Shared Job Context
> Use one evidence-backed operational view so every authorized OpenTrain agent and employer team member can continue managing a job safely.
Shared job context gives every authorized agent and employer team member the same current operational view of a job. It combines canonical OpenTrain records with explicit project rules, deterministic attention signals, readiness gates, action ownership, and recent changes.
Use it whenever an agent manages an existing job. The agent should read the context before deciding what to do, claim coordinated work before acting, and use the current context version when it makes a consequential change.
For the full operating loop, see [Manage a Live Job With Shared Context](/docs/developers/guides/manage-live-jobs-with-shared-context).
OpenTrain's CLI and MCP server include context-first instructions for job
management. An agent that connects through either surface receives this
operating protocol automatically. The normal context read also includes the
bounded fresh-priority queue, evaluator health, effective-policy summary, and
Job Operating Guide digest, so the agent does not need to scan every subsystem
before it can choose what to investigate.
Use capability discovery as the release fence. The workflow below is available
only when `GET /api/public/v1/capabilities` reports `job_operations` as
`available`. The deterministic signal, typed-policy, and operating-guide
surfaces require CLI/MCP 0.10.0+ and 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, wait for the matching
package release instead of assuming the commands exist.
## What the context contains
A job context can include:
* the current objective and workflow;
* active policies, manual decisions, and approved exceptions;
* each person's lifecycle stage, gate results, blockers, and readiness;
* privacy-safe signals for conversations that may need an employer response;
* a ranked, bounded attention queue for conditions that may need investigation;
* evaluator health and freshness, including incomplete or stale scans;
* effective typed policies and their attributed supersession history;
* a versioned Job Operating Guide digest generated from current shared state;
* open actions, owners, claim leases, dependencies, and due dates;
* recent context events and evidence references;
* conflicts, incomplete scans, and unknown state that require reconciliation; and
* a monotonic context version for concurrency checks.
The response is structured so an agent can distinguish how each value was established:
| Provenance | Meaning |
| ------------- | --------------------------------------------------------------------------- |
| `OBSERVED` | A current fact from an authoritative OpenTrain record or connected provider |
| `DERIVED` | A value computed from canonical facts and the job's active workflow |
| `DECIDED` | A recorded employer decision, policy, or approved exception |
| `INFERRED` | An agent interpretation that is not authoritative |
| `RECOMMENDED` | A proposed next action that has not happened yet |
Agents must not present an inference or recommendation as a completed fact.
## Attention signals guide triage
OpenTrain evaluates supported job conditions deterministically. Examples include unanswered messages, overdue Project To-dos, stalled grading, repeated LMS difficulty, readiness contradictions, and provider-state drift.
Each signal keeps three independent states:
* **Condition:** whether the underlying condition is active or cleared.
* **Freshness:** whether the evaluator completed a current scan, is stale, or could not complete its scan.
* **Triage:** whether an authorized manager acknowledged, snoozed, or dismissed that occurrence.
The default attention queue includes only active, fresh signals from active rules. Shadow rules can collect evidence without appearing as actionable priorities. Stale or incomplete evaluators remain visible in health metadata, but their findings are not presented as current work.
Priority is a deterministic sorting aid, not authorization to act. For example, a cohort of AI trainers repeatedly missing one LMS question can suggest that the instructions or question need review. The signal does not rewrite the course, contact anyone, or decide the cause. An agent claims the signal, inspects the supporting canonical records, and proposes the appropriate change.
A manager can acknowledge, snooze, or dismiss one occurrence. Only the evaluator clears the underlying condition. If evidence changes materially or the condition recurs, OpenTrain can reopen it as new work.
## Synchronization follows the agent automatically
CLI/MCP 0.11.0 and SDK 0.10.0 keep one private Job Operations session across
covered job-scoped calls. The client captures the server-issued credential and
latest per-job delivery token, presents them on the next covered call, and
removes them from agent-visible output. You do not copy tokens between commands
or put them in an agent prompt.
Every covered response includes:
* `sync`: current conflicts, recommendations, next operations, recent changes,
and session state; and
* `syncCoverage`: whether the operation is `native`, `bridged`, or intentionally
`none`, with a reason when it is not synchronized.
A native or bridged call can therefore tell the next agent command that another
manager changed a policy, claimed related work, replied to a conversation, or
recorded a different plan. The agent should inspect this additive envelope
before continuing. `coverage: none` is an explicit boundary, not a silent claim
that synchronization happened.
The CLI persists this convenience state only when the runtime supplies a stable
agent identity through `PASEO_AGENT_ID` or `OPENTRAIN_AGENT_INSTANCE`. Without
one, it stays ephemeral. MCP keeps equivalent state private to the authenticated
connection, and the SDK keeps it private to one `OpenTrain` client instance.
Deleting local state is safe because canonical OpenTrain context remains the
authority; the next covered read simply bootstraps again.
Use a bounded sync poll when a long-running agent needs a fresh change quickly.
Polling reduces repeated full scans, but it does not replace an immediate
canonical re-read before a consequential write.
## Canonical records remain authoritative
Shared context does not replace proposals, contracts, identity verification, Project To-dos, training assignments, messages, milestones, payments, or provider enrollment records.
When a supported canonical record changes, OpenTrain advances or invalidates the job context automatically. A context sweep reconciles any changes that arrived asynchronously. You do not need to copy the same status into a separate agent-maintained memory field.
This distinction prevents a summary from claiming that someone is ready after the underlying requirement changed.
## Readiness uses independent gates
Readiness is derived from the job's active workflow. It is not a manually edited “approved” label.
A person can have separate gates for requirements such as:
* assessment or practice work;
* identity and location eligibility;
* agreements;
* Project To-dos;
* training;
* provider access or membership; and
* production activation.
Each gate preserves its raw result and evidence. An authorized manual decision can change the operative result only when the workflow permits it. For example, a project owner might pass a minor assessment error with coaching while the failed raw answer remains visible. Mandatory compliance gates cannot be silently rewritten.
If the workflow is missing, invalid, or has no required gates, readiness fails closed and the context reports the inconsistency.
## Start every job-management session with context
Follow this sequence when an agent begins or resumes work:
Identify the exact job and confirm the token has access to it. Shared
employer membership does not grant access to every job automatically.
Load the job context first and record its version. In a writable management
session, sweep with that version, continue with each sweep response's
`contextRevision` until `hasMore` is false, then load context again. A
read-only session does not sweep.
Check blockers, inconsistencies, unanswered-message signals, open actions,
existing owners, and active claim leases before proposing work.
Claim coordinated work before acting. Another agent should respect an
unexpired claim and choose different work.
Immediately before a consequential mutation, fetch the latest canonical
record or conversation. Context helps you choose the work; the current
source confirms that the planned action is still valid.
Send the expected context or action version and an idempotency key. A
stale-version conflict means the agent must refresh and reconsider instead
of forcing its earlier plan.
Complete or release the action, acknowledge the new context version, and
create a handoff when another manager or agent needs to continue.
## Context versions prevent stale actions
Every accepted context change advances a monotonic version. Consequential writes can require the version that the agent reviewed.
If another manager changes the job after the agent prepares an action, OpenTrain returns a conflict instead of accepting a stale write. The safe response is:
1. fetch the latest context;
2. inspect the delta and affected canonical records;
3. revise or discard the planned action; and
4. retry with the new version and the same semantic idempotency key when the action is still correct.
Do not retry a stale write blindly.
## Claims coordinate agents and people
An action claim is a time-limited lease, not permanent ownership. The context shows who claimed the action and when the lease expires.
* Respect an active claim.
* Release work you are no longer handling.
* Complete the action only after verifying its canonical result.
* If a lease expires, refresh before claiming it again; the previous owner may have completed related work outside the context view.
Idempotency protects repeated requests after timeouts or handoffs. Reusing an idempotency key for a different semantic action fails closed.
## Intents and proposals resolve different plans
Claims coordinate work that already has a shared action. An intent is the
write-ahead lane for spontaneous work that has not become an action yet. Declare
it before starting so another manager sees the owner and purpose. An overlapping
intent returns the current winner instead of letting both agents race.
If a manager wants a different workflow or policy, submit a proposal. A proposal
records the alternative, rationale, evidence, and review outcome without
executing it. Another authorized manager can accept or reject the idea, then
perform any approved canonical change through its normal guarded operation.
Proposal review never becomes hidden write authority.
Scoped overlays provide flexible memory without weakening the shared source of
truth:
* **TEAM** guidance is shared and owner-controlled;
* **PERSONAL** guidance is durable for one manager; and
* **SESSION** guidance is scratch context for one agent connection.
Overlay text is attributed and untrusted. It cannot change readiness, gates, or
effective typed policies. When an overlay conflicts with team policy, the agent
must surface the conflict and ask whether to follow the current policy or submit
a proposal to change it.
## Typed policies and the Job Operating Guide
Project rules that affect agent behavior or readiness belong in typed, attributed policies. A policy records who approved it, which agent recorded it, when it became effective, what it supersedes, and where OpenTrain enforces it.
For example, changing a training gate from “scored assessments required” to “course completion required” updates the one canonical readiness workflow atomically. It does not leave one agent following an old chat instruction while another agent follows the new rule.
OpenTrain generates a read-only Job Operating Guide from the current objective, workflow, effective policies, approved exceptions, active claims, and fresh attention signals. The structured guide and its deterministic Markdown rendering are the shared `AGENTS.md`-equivalent for that job. Agents read it from OpenTrain; they do not maintain competing local copies.
The guide explains shared state but does not become a second authority. Canonical records and approved typed policies remain authoritative. Recording or superseding a policy advances the shared context, changes the generated guide, and becomes visible to every authorized manager and agent.
Policy enforcement targets are intentionally precise:
* `CANONICAL_DB` and `WORKFLOW` mean OpenTrain changed the corresponding canonical configuration atomically with the policy record.
* `GUIDE` with status `APPLIED` means the attributed rule is published in the shared operating guide for managers and agents. It does not mean OpenTrain enforces that instruction in another subsystem.
* `EXTERNAL` remains pending until verified evidence confirms that the external system was updated.
For example, `TRAINING_PRODUCTION_GATE` controls whether production readiness follows course completion or scored assessment review. It does not contain a first-production-task limit. If the team wants every AI trainer to complete one production task and stop for review, record that instruction as an attributed `OPERATING_RULE.first-production-task-limit` guide policy. Agents will share the rule, its approver, and its supersession history, while the guide remains honest that the rule is coordination guidance rather than a runtime task cap.
## Decisions, observations, and handoffs
Use the right durable record:
* **Decision or policy:** an authorized rule, exception, pass/fail determination, or superseding instruction.
* **Observation:** evidence or a non-authoritative signal that may inform later work.
* **Action:** coordinated work with an owner, status, lease, and result.
* **Checkpoint:** the latest context version an agent has processed.
* **Handoff:** a concise continuation record for another authorized manager or agent.
Decisions are versioned and superseded rather than silently edited. An expired or superseded decision does not affect the current projection.
## Message safety
Shared context exposes privacy-safe response signals, not message bodies. Before sending a reply, the agent must read the latest authorized conversation and thread.
A managed send uses the dedicated synchronized operation
`messaging_management.messages.send` (CLI `manager messages send`; MCP
`opentrain_send_managed_job_message`). It includes the exact latest message ID
together with the context revision, action revision, and signed claim receipt.
Use `null` only when the conversation was observed empty. The server resolves
the authorized Job Message or Proposal Message binding, validates the guarded
state, and commits the message and context advance atomically. It fails stale
before creating the message or notifications.
The generic message-send operation is intentionally unsynchronized. Do not use
it for claimed shared-job work.
This final check protects against common races:
* another employer teammate already replied;
* the AI trainer followed up after an earlier employer response;
* the requested task was completed after the draft was prepared;
* the relationship changed, so a different conversation surface is appropriate; or
* the conversation or participant is no longer visible to the acting user.
## Security and scope
The context follows the same organization, token-scope, and per-job access checks as the underlying records. It does not expose raw identity documents, message content, secret provider data, or restricted integrity details.
Use a token with `jobs:read` to inspect job context and `jobs:write` for supported coordination records. The acting employer team member must also have access to the specific job.
## Related
Understand token scopes, account state, and capability discovery.
Use account updates and webhooks alongside job-scoped operational context.
Follow the context-first triage, claim, recheck, action, and handoff loop.
Manage canonical post-hire requirements and provider-backed obligations.
Learn which money and hiring actions still require a human co-sign.