Shared Job Context API

The Shared Job Context API gives every authorized employer team member and agent one evidence-backed operational view of a job. It projects current canonical OpenTrain records, preserves durable decisions and exceptions, and coordinates work with versioned action claims.

Base path: /api/public/v1/job-operations/jobs/{jobId}

Information

Shared context is a projection and coordination plane. Proposals, contracts, identity checks, assessments, Project To-dos, training, messages, payments, and provider records remain authoritative in their existing APIs.

Warning

Treat capability discovery as the release fence. Use this API only when GET /api/public/v1/capabilities reports job_operations as available. The matching agent packages for deterministic signals, typed policies, and the canonical guide projection are CLI/MCP 0.10.0+ and SDK 0.9.0+. Automatic synchronization, intents, proposals, and 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, external attestations, action renewal and handoff, 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+. Older npm latest versions do not contain these operations.

Start every job-management session here

1. GET /context for the current objective, workflow, readiness, bounded fresh-priority queue, evaluator health, effective-policy summary, Agent Guide digest, blockers, action claims, inconsistencies, and revisions. The bootstrap envelope’s sync.nextOperations then ends with job_operations.agent_guide.get: read GET /agent-guide once, and later fetch GET /playbook/delta only when recommendation.agent_guide_changed names it.
2. In a writable session, POST /sweep with that revision. Continue with each response’s contextRevision while hasMore is true, then read context again. Read-only sessions do not sweep.
3. Claim one coordinated action before working.
4. Re-read the affected canonical record and latest authorized conversation immediately before a consequential write.
5. Send the expected context or action revision and an idempotency key.
6. Verify the canonical result, complete or release the action, then checkpoint or hand off.

The live-job guide explains the full operating loop.

Endpoints

Method	Path	Purpose
GET	/context	Read one coherent compact or full context snapshot.
GET	/delta	Page through context events after a prior revision.
GET	/people/{personUserId}	Read one person’s lifecycle, raw and operative gates, blockers, decisions, and evidence IDs.
POST	/sweep	Reconcile durable event hints and canonical projection drift before triage.
GET	/actions	List open, claimed, completed, or canceled coordination actions.
POST	/actions	Create a versioned coordination action and its dependencies.
POST	/actions/{actionId}/claim	Claim an eligible action with a bounded lease.
POST	/actions/{actionId}/release	Release an unexpired claim held by the authenticated claimant.
POST	/actions/{actionId}/renew	Renew the authenticated claimant’s still-live lease against the exact action revision and receipt.
POST	/actions/{actionId}/handoff	Release the current claim and create a bounded reservation for a named recipient, without transferring a receipt.
POST	/actions/{actionId}/complete	Complete an unexpired claim with an outcome receipt.
POST	/actions/{actionId}/cancel	Cancel a nonterminal action with an audited reason.
POST	/brief	Publish a new objective and typed readiness-workflow revision.
GET	/decisions	Page through durable decisions and their supersession history.
POST	/decisions	Record or supersede a policy, decision, or approved exception.
GET	/observations	Page through typed observations, optionally filtered to one person.
POST	/observations	Record typed external evidence, inference, or recommendation.
POST	/checkpoints	Acknowledge the last context revision consumed by this actor/session.
POST	/handoffs	Leave a structured handoff for the next authorized manager or agent.
GET	/signals	Page through deterministic attention signals; shadow rules are excluded unless an authorized audit read explicitly requests them.
GET	/signals/{signalId}	Read one privacy-safe signal, its evidence references, revisions, and linked-action state.
POST	/signals/{signalId}/acknowledge	Acknowledge one occurrence without claiming or clearing it.
POST	/signals/{signalId}/snooze	Snooze one occurrence until a bounded future time without claiming or clearing it.
POST	/signals/{signalId}/dismiss	Dismiss one occurrence with an audited reason; recurrence can reopen new work.
POST	/signals/{signalId}/claim	Atomically create or reuse the linked action and acquire its claim lease for an active, fresh signal whose effective triage is open or acknowledged.
GET	/policies	Read the effective typed policies and current enforcement state.
GET	/policies/history	Page through attributed, append-only policy revisions and supersession history.
POST	/policies	Record the first typed policy revision or supersede the exact active head.
POST	/policies/verify-enforcement	Attach verified external-enforcement evidence to a pending policy.
GET	/agent-guide	Read the composite Agent Guide: the typed projection, the published Playbook, the open-proposal count, and the precedence list, as JSON plus Markdown.
GET	/playbook	Read the published Playbook head, or the empty state when nothing is published.
GET	/playbook/versions	Page newest-first version summaries with per-version added/changed/removed section ids (limit 1–200).
GET	/playbook/versions/{playbookVersion}	Read one exact immutable version with its sections; 404 when it does not exist.
GET	/playbook/delta	Read the exact section delta from fromVersion to toVersion (default: the head): added, changed, removedSectionIds, unchangedSectionIds, sectionOrder.
GET, POST	/playbook/proposals	List proposals oldest first, or submit a SECTION_UPSERT, SECTION_REMOVE, or NOTE proposal against the current head (recommended, never enforced).
POST	/playbook/proposals/{proposalId}/resolve	ACCEPT (human job-manager court), DECLINE, or WITHDRAW an exact proposal revision.
POST	/playbook/publish	Publish an immutable Playbook version from the closed editor-subset document under the expectedPlaybookVersion pin. Human job-manager court only.
GET	/guide	Read the canonical typed projection alone (the Agent Guide without the Playbook) as JSON plus Markdown. Kept for existing clients.
GET	/setup	Read the deterministic guided-setup packet, including missing components, canonical evidence, questions, proposed defaults, write previews, and current setup coordination.
GET	/sync/poll	Wait up to the bounded server limit for a new private-session delivery.
GET, POST	/intents	List or declare write-ahead spontaneous-work intents.
POST	/intents/{intentId}/resolve	Complete, abandon, reject, or promote an exact intent revision.
GET, POST	/proposals	List or submit non-enforced workflow, policy, priority, goal, exception, or capability proposals.
POST	/proposals/{proposalId}/review	Accept or decline an exact proposal revision without executing it.
POST	/proposals/{proposalId}/withdraw	Withdraw an open proposal.
GET, POST	/guide/overlays	Read or replace attributed TEAM, PERSONAL, or SESSION guidance.
GET, POST	/work/definitions	List this job’s definitions or create one attributed immutable draft head.
POST	/work/definitions/propose-from-provisional	Propose an inactive inferred definition from observed provisional work.
GET	/work/definitions/{definitionKey}	Read one definition’s exact current/latest bindings and bounded immutable history.
POST	/work/definitions/{definitionKey}/versions	Append an immutable successor against the exact latest semantic binding.
POST	/work/definitions/{definitionKey}/activate	Activate an approved version against exact revision and binding preconditions.
POST	/work/definitions/{definitionKey}/archive	Archive a definition after open-work and migration blockers are resolved.
POST	/work/definitions/{definitionKey}/migration/start	Start an approved frozen migration between exact version bindings.
POST	/work/definitions/{definitionKey}/migration/batch	Continue one bounded migration page; repeat until the durable result is complete.
GET, POST	/work/executions	List executions or begin defined work and mint its one coordinating action.
POST	/work/executions/provisional	Begin immediate ad hoc work without inventing or activating a reusable type.
POST	/work/executions/{executionId}/promote	Promote an exact provisional execution to an approved definition.

Use the machine-readable OpenAPI document for final request and response schemas.

Context response

The response separates each value’s provenance:

Authority	Meaning
OBSERVED	Direct canonical or approved external evidence.
DERIVED	Deterministic projection from current evidence and workflow rules.
DECIDED	An authorized policy, judgment, manual pass/fail, hold, or exception.
INFERRED	An interpretation that is not canonical truth.
RECOMMENDED	A proposed next action; it changes no state by itself.

Per-person results keep raw gates separate from operative gates. A manual pass can change an operative assessment gate without erasing the failed raw item. Identity and eligible-location gates are non-waivable.

Evidence references contain privacy-safe resource identity, not message bodies, answers, identity documents, fraud telemetry, contact details, or provider secrets.

Automatic synchronization envelopes

Covered Job Operations, messaging-management, and LMS responses add two top-level fields:

• sync contains the current private-session delivery, conflicts, recommendations, next operations, and whether a full context read is required; and
• syncCoverage identifies the exact operation and reports native, bridged, or intentionally none coverage.

The official CLI, MCP server, and SDK capture the server-issued credential and per-job token internally, present them on the next covered request, and redact them from agent-visible output. A custom HTTP client must implement the exact header and acknowledgement contract described by OpenAPI. Never put session credentials or signed sync tokens in prompts, logs, or ordinary application state.

Synchronization is additive. It does not authorize a mutation or replace the canonical pre-action read. If sync.resyncRequired is true, read context again before continuing. If syncCoverage.coverage is none, do not claim that the operation refreshed shared context.

GET /sync/poll provides a bounded real-time wait. It avoids repeated full scans while another project manager is working, but canonical resources remain the final authority.

Guided operational setup

Covered responses recommend /setup automatically while the operating brief, typed workflow, or an applicable required operating choice is missing. The packet is read-only and never applies a proposed default.

The agent declares a setup.* intent before presenting questions. An overlapping declaration can return the current winner, but that visible ID does not transfer ownership. Before prompting or writing, the winner verifies that the intent’s non-null sessionId equals the current synchronized response’s non-null sync.session.sessionId, with the same principal. It repeats that check on a fresh setup read immediately before approved writes.

Use ordinary guarded /brief and /policies operations to apply the exact approved plan. A complete or explicitly deferred component becomes shared state for every authorized employer manager and agent.

See Set Up Shared Job Operations for the driven agent workflow.

Dynamic per-job Work Catalog

OpenTrain does not define business work types. /work/definitions stores each job’s own versioned atomic-work vocabulary; /work/executions coordinates instances of that work. Covered responses expose sync.workCatalog and automatically recommend setup, review, or approval work, so a user does not have to discover the feature before their agent uses it.

A durable ops:work-catalog-setup intent selects one setup session. Immediate ad hoc work can be provisional. Recurring evidence can produce an inactive INFERRED definition, but only a non-agent human job manager can approve its exact content and coordination digests. Activating the resulting decided version requires the exact immutable binding the caller just read.

Each execution owns one coordinating action, whose claim lease is the single ownership authority. The human-only WORK_COORDINATION_MODE policy chooses whether this is advisory (OPEN), required with defined or provisional work (COORDINATED), or required with active defined work (MANAGED). An unreadable policy head fails closed.

External systems are not silently treated as current. Record bounded evidence through an OBSERVED /observations request’s top-level externalAttestation; use ATTEST with a required expiry or INVALIDATE for a named predecessor. The generated guide’s externalCoverage projection is the safe read surface.

See Dynamic Work Catalog for the agent behavior, flexible-definition model, duplicate review, and optional UI.

Deterministic attention queue

OpenTrain evaluates supported conditions on the backend and ranks them using a deterministic score. The default actionable queue contains only signals whose condition is active, evaluator result is fresh, and rule is active rather than shadow. Stale or incomplete evaluator runs remain visible in context health and counts, but do not appear as current priorities.

Condition, freshness, and triage are independent. Acknowledging, snoozing, or dismissing one occurrence does not clear its underlying condition. Only a successful evaluator run can clear it. Signal claim is the sole path that turns a finding into owned work, and it returns the linked action lease and signed claim receipt.

Claim fails closed while a signal is stale, incomplete, live-snoozed, dismissed, or produced by a shadow rule. Refresh context and wait for a complete fresh evaluation instead of creating work from evaluator-health metadata.

Priority indicates what may deserve investigation; it does not establish root cause or authorize a canonical mutation. Fetch the evidence-bearing canonical records before acting.

Typed policies and the Agent Guide

Job-wide workflow and agent-behavior rules are stored as typed, attributed, append-only policies. A policy update names the exact active decision it supersedes and records the approving user, recording user, recording agent, effective time, enforcement target, and evidence. Supported canonical enforcement changes are applied atomically with the policy record; external enforcement remains pending until separately verified.

GUIDE is a publication target. A guide policy marked APPLIED is present in the shared Agent Guide; that status does not claim that another OpenTrain subsystem enforces the instruction. The TRAINING_PRODUCTION_GATE v1 payload contains only schemaVersion and basis. Record a first-production-task stop rule separately as an attributed OPERATING_RULE.first-production-task-limit guide policy.

GET /agent-guide returns the Agent Guide: the canonical typed projection of the current objective, workflow, effective policies, approved exceptions, active claims, fresh priorities, and Work Catalog, plus the human-published Playbook (bounded Markdown sections with stable ids and content hashes), the open-proposal count, and the precedence list, under one contextRevision and checksum, with a deterministic Markdown rendering. The projection’s version and checksum also appear in every context read as the guide digest. GET /guide returns the projection alone and is kept for existing clients.

The Agent Guide is the job’s shared AGENTS.md-equivalent, not a second authority: canonical records and effective typed policies remain the source of truth, and the Playbook is guidance beneath them. Agents change guidance only through POST /playbook/proposals; humans publish through POST /playbook/publish, which links accepted proposals only when the exact proposed section content landed. See Follow and Improve the Agent Guide for the request and response shapes.

Intents, proposals, and overlays

Use an intent before spontaneous work that has no shared action yet. Active intents have bounded leases and deterministic dedupe keys, so overlapping agents receive the current winner instead of performing duplicate work.

Use a proposal when a manager wants a different job-wide workflow, policy, priority, goal, exception, or capability action. A proposal is attributed and reviewable but non-enforced. Accepting it records the review and can link a separately authorized decision, action, or brief revision; review never executes the proposal.

Use overlays for flexible guidance that should not become policy. TEAM is owner-controlled shared guidance, PERSONAL belongs to one manager, and SESSION belongs to one private agent session. Overlay entries are attributed untrusted content. Typed-reference lint can flag stale or higher-authority references, but overlays never alter readiness, gates, or effective policy.

Version and replay safety

• Every context-changing write carries the exact expectedContextRevision read by the caller. A mismatch returns 409; refresh and re-evaluate instead of blindly retrying.
• Action transitions also carry expectedActionRevision.
• Every mutation requires a stable idempotency key. Repeating the same key and payload converges; reusing a key with different intent returns 409.
• Signal transitions also carry the exact expectedSignalRevision.
• Claim leases expire. An expired claimant cannot release or complete the action; a later caller can reclaim it through the guarded claim path.
• Action dependencies must be complete before a dependent action can be claimed.

Delta pagination

GET /delta?sinceRevision=<n> returns events strictly after <n>, plus hasMore, nextRevision, and the current context revision. Continue with nextRevision until hasMore is false, then acknowledge that revision with a checkpoint.

Guarded managed messages

When a message is part of claimed job-context work, use:

POST /api/public/v1/messaging/management/messaging_management.messages.send

The operation requires messages:write and messages:manage, plus an Idempotency-Key of 8–128 characters using letters, numbers, ., _, :, or -. Its body includes:

{
  "contractId": "<contract-id>",
  "content": "<reviewed-message>",
  "jobOperationsGuard": {
    "jobId": "<job-id>",
    "expectedContextRevision": 1845,
    "actionId": "<action-id>",
    "expectedActionRevision": 1,
    "claimReceipt": "<exact-claim-receipt>",
    "expectedLatestMessageId": "<message-id>"
  }
}

Set expectedLatestMessageId to null only when the authorized conversation was observed empty. OpenTrain resolves the authorized Job Message or Proposal Message to its canonical job, validates the guard, and commits the message and context advance atomically. A teammate or AI trainer reply, context advance, action transition, expired lease, or mismatched receipt rejects the send before creating the message or notifications.

POST /api/public/v1/messages remains the generic backward-compatible send endpoint. Its optional legacy guard is only a stale-message precondition. It does not attach or advance shared Job Operations context.

Permissions

Reads require jobs:read; supported coordination and context writes require jobs:write. The authenticated actor must also have canonical access to the exact job—organization membership alone does not bypass folder or direct-job assignment rules.

Shared Job Context is an always-available baseline agent surface. It has no separate environment, account, or UI rollout flag; normal token scopes and job access still apply.

Common errors

Status	Meaning	Recovery
400	Invalid workflow, evidence, transition, lease, or pagination input.	Correct the structured request; do not retry unchanged.
403	Missing scope, unclaimed agent account, or no employer organization.	Use the correct claimed employer token and scope.
404	The job, person, or action is absent or not canonically accessible.	Resolve the exact resource and job assignment again; access denials do not reveal existence.
409	Stale revision, idempotency conflict, active claim, incomplete dependency, or invalid state transition.	Refresh context/action state and deliberately re-evaluate.