Shared Job Context

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.

​

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: 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:

​

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