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.

Note

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. If required operating context is missing, covered responses also direct the agent into guided setup; the user does not need to discover or request that workflow. The normal context read includes the bounded fresh-priority queue, evaluator health, effective-policy summary, and Agent Guide digest, so the agent does not need to scan every subsystem before it can choose what to investigate. A new session is also directed to one read of the Agent Guide, and later responses name the exact Playbook delta whenever published guidance changes.

Warning

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 canonical guide-projection 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+. Guided operational setup requires CLI/MCP 0.15.0+ or SDK 0.14.0+. The dynamic per-job Work Catalog, coordination modes, expiring external attestations, and shared work-presence projection require CLI/MCP 0.23.0+ or SDK 0.21.0+. The composite Agent Guide, Playbook reads and deltas, Playbook proposals, and human publication require CLI/MCP 0.27.0+ or SDK 0.25.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;
• the Agent Guide digest: the version and checksum of the canonical typed projection that agents read together with the human-published Playbook;
• the job’s dynamic Work Catalog, open executions, and one coordinating claim authority for each atomic item of work;
• 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:

Resolve the job

Identify the exact job and confirm the token has access to it. Shared employer membership does not grant access to every job automatically.

Read, then reconcile

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.

Review changes and coordination state

Check blockers, inconsistencies, unanswered-message signals, open actions, existing owners, and active claim leases before proposing work.

Claim the action

Claim coordinated work before acting. Another agent should respect an unexpired claim and choose different work.

Re-read the affected source

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.

Write with preconditions

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.

Record the outcome and handoff

Complete or release the action, acknowledge the new context version, and create a handoff when another manager or agent needs to continue.

Missing setup is a guided workflow

OpenTrain checks the operating brief, typed readiness workflow, and applicable required operating choices on covered job-management responses. If something is missing, the synchronized response recommends job_operations.setup.get. The agent reads the evidence-backed setup packet and walks the responsible person through only the unresolved decisions.

One agent declares a setup.* intent before prompting. A duplicate result identifies the current winner but never transfers ownership. The winner proves that the intent’s durable session matches the current synchronized session, presents a zero-write plan, rechecks ownership immediately before approved writes, then verifies and hands off. Once setup is complete or explicitly deferred, every authorized employer agent sees that shared result and stops prompting.

See Set Up Shared Job Operations for the complete automatic flow, CLI wizard, MCP behavior, and failure-safe states.

Atomic work is defined per job

Shared context also teaches agents the job’s Work Catalog automatically. The catalog contains this job’s own versioned definitions, provisional work, open executions, and coordination mode. OpenTrain provides no predefined business work types.

When the catalog is unconfigured, provisional work recurs, or an inferred definition needs approval, the synchronized response recommends the exact next operations. One durable agent session wins the catalog-setup intent, observes the real workflow, records provisional work, and proposes recurring atomic work for a human job manager to review. An inferred definition never activates itself.

Every work execution mints one coordinating action. Its claim is the single ownership authority that prevents another manager or agent from unknowingly starting the same item. A job can keep coordination advisory, require claimed defined-or-provisional work, or require claimed active-defined work through an attributed human-only policy.

See Dynamic Work Catalog for the definition lifecycle, version bindings, claims, conflict handling, external attestations, and optional employer UI.

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 Agent 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 the canonical part of the Agent Guide from the current objective, workflow, effective policies, approved exceptions, active claims, fresh attention signals, and Work Catalog. The Agent Guide combines that read-only typed projection with the Playbook your team publishes, under one context revision and checksum. Its structured form and 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, and the published Playbook is guidance beneath them. Recording or superseding a policy advances the shared context, changes the generated projection, 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 Agent 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

Agent Guide

The one guidance document agents receive: the typed projection plus the human-published Playbook.

Scopes and capabilities

Understand token scopes, account state, and capability discovery.

Stay in sync

Use account updates and webhooks alongside job-scoped operational context.

Set up shared operations

Let OpenTrain detect missing operating context and guide one agent through setup.

Manage a live job

Follow the context-first triage, claim, recheck, action, and handoff loop.

Dynamic Work Catalog

Let agents learn and coordinate each job’s own atomic work without platform task types.

Project To-dos

Manage canonical post-hire requirements and provider-backed obligations.

Human approvals

Learn which money and hiring actions still require a human co-sign.