The Intent Envelope, Explained: A Durable Object for Agent Work

A prompt captures a moment of instruction. It does not capture who asked, what constraints apply, what has already been tried, what was produced, or whether a human still needs to approve the result. The instant work crosses a tool boundary, all of that context has to be rebuilt by hand. The intent envelope exists to make the unit of work survive that journey.

An Agintent envelope is a versioned wrapper. A minimal envelope looks like this:

{ "protocol": "agintent.envelope", "version": "0.1", "source": { "actorType": "human" }, "intent": { "object": "intent", "status": "queued" }, "run": { "executorCapability": "browser_automation" }, "artifacts": [], "memoryRefs": [] }

Every field has a job. None of them are decoration.

• protocol + version: the contract identifier and version. Versioning is first-class so the object model can evolve without silently breaking consumers.
• source: the actor and origin metadata. Was this emitted by a human, an agent, a workflow, or an external system? Routing and trust decisions depend on it.
• intent: the canonical requested-work object — what is being asked, for whom, under what constraints, with what priority, with what expected outputs.
• run: the run block that binds the envelope to an execution capability and tracks lifecycle state.
• artifacts: typed references to outputs — files, links, summaries, screenshots, reports — that remain attached to this work.
• memoryRefs: references to memory records linked to this and related work, so context is retrievable instead of informal.

The run block is not just a status string. It is a contract. It records who accepted the work, which executor capability is handling it, which state transitions are valid, and how logs and artifacts attach. The lifecycle states are deliberately small and explicit: queued, running, waiting for input, completed, failed, cancelled. A run that pauses for human review is not in a fuzzy 'pending' limbo — it is in a defined waiting state with a reason.

A common anti-pattern is routing work to a specific named worker or agent ID. That couples the request to one implementation. The envelope routes to a declared executor capability instead — research, webhook dispatch, manual approval, browser automation, CRM mutation, data extraction, content creation, task decomposition. Any executor that declares the capability can accept the work, and unsupported intents fail clearly instead of silently stalling.

The most common context loss in agent stacks is outputs drifting away from the request that produced them. A report lands in a drive folder; a log lands in a separate observability tool; a useful learning lives only in someone's head. The envelope keeps artifacts and memory references attached to the originating work. Storage backends can change — local filesystem today, object storage tomorrow — without changing the artifact contract, because the contract is defined at the protocol level, not the storage level.

Agintent's reference runtime still uses task-shaped internals and a /api/tasks compatibility API. That is a deliberate, honest tradeoff: the storage shape can lag the protocol vocabulary, but the external language should not. A 'task' in the runtime maps to an intent object inside an envelope; a 'task run' maps to a run under the run contract. The protocol boundary is what matters, and it is being kept explicit and tested.

Object models are easy to change when one team owns one runtime and almost impossible to change once an ecosystem depends on them. Defining a clean, versioned envelope while Agintent is at the concept-plus-reference-implementation stage is the entire point. Get the durable object right, and mixed human-and-agent execution becomes practical instead of a permanent integration tax.