Overview

OpenMAIC edits courses through owner-scoped, typed tools rather than opaque document replacement. Tools identify the stage, scene, and path; owner probes keep the model from choosing the security principal, while sequential writers make later reads observe committed edits. Atomic document validation, stable scene identity, and mutation fences distinguish structural success, retries, and detached media updates. These boundaries reduce stale overwrites and cross-owner writes, but they do not ensure that a model chose the right edit or that generated content is factually correct.

Learning outcomes

Typed patches expose the intended course operation without asking the model to reproduce a whole, potentially stale document.
Sequential scheduling makes reads and writes observe one ordered state, reducing silent lost updates at the cost of parallelism.
Owner probes, atomic saves, stable identities, and mutation fences control access and freshness, not the quality of the edit itself.

Keywords

OpenMAICtoolsownershippatchesconcurrencycheckpoints

Why the Agent Edits Through Tools Instead of Blobs

When an agent edits a course, the visible request may be as simple as “change the example on page three.” The underlying failure can be much less simple: the model may target the wrong course, two edits may read the same old snapshot, or a background media job may finish after a newer page revision. This chapter diagnoses those failures and explains why OpenMAIC uses owner-scoped, typed tools and serialized document writers instead of letting the model replace an opaque course blob.

The lost-update symptom and the typed-tool diagnosis

An opaque blob hides the operation being requested. If the model sends back a whole course document, the storage layer has to accept a large replacement even when the user wanted one small change. The write may contain a stale copy of every unrelated scene. It may also carry an identifier supplied by the model rather than an identity established by the server. A successful response would not prove that the intended page changed or that another user's course was untouched.

OpenMAIC's agent surface breaks that operation into typed tools. The agent can read a stage, inspect a scene or outline, search the stage, patch a specific path, generate one page, change deck structure, import a presentation, or request media. The tool parameters describe the operation the runtime is prepared to validate. A targeted patch can therefore say which course, scene, and content path it intends to change instead of replacing every field that happened to be in the model's context.

The stage identifier is not treated as proof of ownership. It is an address that the server checks. Before a stage-bearing tool touches the store, the runner probes whether the stage belongs to the session owner and refuses foreign, missing, or tombstoned targets with a generic not-yours response. The owner identity is captured outside the model-visible parameters. This matters because a model can generate a plausible identifier, but it cannot be allowed to choose the security principal that identifier will be evaluated against.

flowchart LR A["Model tool intent"] --> B["Declared stageId"] B --> C{"Owner access probe"} C -->|refused| D["No store write"] C -->|owned| E["Typed read or minimal patch"] E --> F["Sequential writer scheduling"] F --> G["Validate and atomically write document"] G --> H["Durable checkpoint"] E --> I["Detached media job"] I --> J["Stage mutation fence"] J --> G

The owner probe and the typed operation solve different problems. The probe answers “may this session work on this stage?” The tool schema answers “what operation is being attempted?” The document store then validates the resulting stage or scene and enforces its own version and JSON boundaries. No single layer has to trust the model's text as an authorization decision or as a complete document replacement.

The distinction between reading and mutating is deliberate.

Published by DeepMox

FAQ

Why does OpenMAIC use typed tools instead of whole course blobs?

OpenMAIC uses typed tools so an edit can name the intended stage, scene, and path instead of replacing unrelated state from a stale snapshot. The operation can then be checked for ownership and document validity before it is committed.

How does OpenMAIC reduce lost updates from parallel edits?

OpenMAIC serializes document-writing tools and orders accompanying reads when a writer is present, so later operations observe committed changes instead of the same old snapshot. The trade-off is less parallelism and potentially more waiting.

How does OpenMAIC handle media jobs that finish after a session ends?

OpenMAIC lets detached media jobs use owner-bound document and mutation checks without requiring the old session lease, so legitimate late results can update the course without bypassing freshness or validation gates. A page may therefore persist before its media is ready.

Previous10 minOpenMAIC: Durable Building Sessions

Next10 minOpenMAIC: Trust Boundaries for AI Courses

OpenMAIC: Typed Tools for Course Editing

Why the Agent Edits Through Tools Instead of Blobs

The lost-update symptom and the typed-tool diagnosis

FAQ