An autonomous system must keep useful work moving when nobody is typing the next instruction. That requires more than a model that can choose tools. It requires a runtime that remembers commitments, controls effects, detects failure, and resumes safely. This independently written lesson uses an original documentation-maintenance service throughout the week. It is a synthesis of public material, not a reproduction of John Lindquist's MEGA teaching.
Learning goals
- Define autonomy as a bounded set of decisions and effects.
- Separate model judgments from runtime responsibilities and durable state.
- Design observation and recovery for interrupted work.
- Explain why confidence does not grant permission.
Autonomy starts with a contract
Imagine a service called Doc Steward. After an API change, it finds affected guides and prepares a documentation patch. The desired outcome is specific: a reviewable patch that describes the new API correctly. The service may inspect approved repositories, read public reference material, and create a local proposal. Publishing remains a separate capability.
Write that contract before choosing a framework. Include the trigger, permitted inputs, allowed effects, completion evidence, and stop conditions. Otherwise, “keep documentation current” can expand into changing implementation, contacting customers, or rewriting unrelated guides. Those actions may be useful in some system, but they are different jobs with different authority.
John's Script Kit project provides a concrete public example of packaging everyday work into executable scripts with a desktop entry point. The architectural lesson we draw is our own: make a repeated task easy to invoke, then make its boundaries visible. A convenient launch surface does not by itself supply recovery or durable scheduling.
For Doc Steward, autonomy has several independent dimensions. It can choose which guide needs attention while remaining unable to publish. It can retry a read without being allowed to retry a notification. It can run unattended for ten minutes while still requiring a reviewer for ambiguous factual changes. Treating autonomy as one on/off switch hides these differences.
The runtime owns progress
A model receives observations and proposes the next action. The runtime turns that proposal into controlled work. Our runtime validates arguments, checks the current state, applies limits, calls tools, stores receipts, and decides whether another turn is possible. These responsibilities must survive a model switch.
Use a small state machine: queued, inspecting, drafting, checking, ready_for_review, blocked, and failed. Each transition needs a cause. A patch existing on disk is insufficient for ready_for_review; its checks and source revision must also be recorded. Conversely, a network timeout should not automatically erase a valid draft.
Temporal's workflow execution documentation describes durable execution, event history, and replay after failure. We borrow the distinction between transient execution and recorded progress. Our example is not a Temporal implementation, and a JSON file alone does not reproduce Temporal's guarantees.
Durable state should include the task identifier, input revision, policy version, current phase, completed effects, artifact hashes, and remaining budget. Store large source documents separately and reference their immutable hashes. A conversation summary can help the model resume its reasoning, but the summary cannot establish whether an external effect happened.
That difference matters after a crash. “I was about to create a proposal” is ambiguous. A durable effect record saying proposal/docs-a17 = receipt-42 is actionable. Recovery can query the proposal store for that key and reconcile the result before deciding whether to retry.
Decisions need uncertainty and control
A useful automation primitive makes one small judgment: does this change affect authentication documentation, pagination documentation, or neither? TypeSafe's introduction describes Jev as evaluating typed questions against state and returning structured answers. It distinguishes Choice, Score, and Noul questions. This verifies a decision-oriented public contract; it does not establish a particular SDK for our service.
Our examples therefore use conceptual pseudocode. judge_route is a placeholder that an implementation must bind to a real service. It must not be mistaken for a Jev function name.
A decision result should influence routing, not replace authorization. A strongly preferred authentication category still cannot grant access to a private repository. A weak judgment might trigger more evidence gathering, a narrower question, or review. A valid but incorrect answer remains possible, so successful schema validation is only one check.
Separate three gates: Is the action permitted? Is there enough evidence? Is the proposed result correct enough to proceed? Keeping them separate makes failures diagnosable. A missing credential is an environment problem. An unclear API diff is an evidence problem. A patch that contradicts the reference is a content problem.
Worked example
The following is illustrative pseudocode, not a tested runtime or provider API. Assume durable writes are atomic, verified bundles are immutable, and one leased worker owns the task. reserve_once binds an effect key to the saved bundle hash; reconcile_or_create looks up that key before creating anything and always uses the bound artifact.
task = load_task("docs-a17")
assert task.input_revision == checkout.revision
assert policy.permits("create_local_proposal")
if task.phase in ["ready_for_review", "blocked", "failed"]:
stop
key = task.id + ":proposal:1"
evidence = load_saved_evidence(task.id)
reservation = load_reservation(key)
if reservation exists:
bundle = load_verified_bundle(reservation.bundle_hash)
assert evidence exists and hash(evidence) == bundle.evidence_hash
assert bundle.checks.passed
receipt = reconcile_or_create(key, bundle.patch)
save_receipt(key, receipt)
transition(task, "ready_for_review")
stop # recovery makes no new model calls
if evidence is missing:
evidence = collect_api_diff(task.input_revision)
save_evidence(task.id, evidence)
transition(task, "inspecting")
bundle = load_saved_verified_bundle(task.id)
if bundle is missing:
route = judge_route(evidence) # conceptual decision call
if route.needs_more_evidence:
transition(task, "blocked", reason="ambiguous API impact")
stop
patch = draft_for_route(route.category, evidence)
checks = verify_patch(patch, evidence)
if not checks.passed:
transition(task, "failed", reason=checks.failures)
stop
bundle = save_immutable_verified_bundle(task.id, patch,
checks, hash(evidence))
assert bundle.evidence_hash == hash(evidence)
reserve_once(key, bundle.hash)
receipt = reconcile_or_create(key, bundle.patch)
save_receipt(key, receipt)
transition(task, "ready_for_review")Suppose the API diff renames page_size to limit. The route selects pagination, the draft changes the request example, and checks confirm that the obsolete parameter is absent. Expected behavior is one proposal linked to the exact source revision. This is a reasoned expectation, not a reported execution result.
Now kill the worker after proposal creation but before save_receipt. On restart, recovery reloads evidence and the existing reservation, then loads the exact verified patch bound to that reservation. It reconciles the original proposal before any routing or drafting call. A crash before reservation instead reuses the saved verified bundle. Recovery never regenerates a patch under an existing effect key. If the external system cannot support lookup or idempotency, the task must surface an uncertain effect for reconciliation.
Observation should report phase, age of last progress, remaining budget, and unresolved effects. A heartbeat says the process is alive; it does not prove the task is advancing. Repeatedly rereading the same file with no state change should eventually stop under a bounded retry or turn budget.
Practice
Create a paper simulation or a small local implementation of this state machine. Use three fixtures: a valid pagination rename, an ambiguous behavior change, and a crash after the proposal effect.
Acceptance criteria:
- The valid task reaches review with its input revision and check evidence.
- The ambiguous task records a specific blocked reason and publishes nothing.
- Restarting the crashed task produces one logical proposal.
- An exhausted budget prevents another model or tool call.
- An observer can distinguish a running worker from recent useful progress.
A satisfactory answer contains an event log and a transition policy. The crash fixture should show reconciliation using the original effect key. Generating a fresh key after restart fails the exercise because it permits duplicate effects. Leaving the ambiguous fixture running indefinitely also fails: a system must express that it cannot safely proceed.
Check your understanding
- Why is conversation history insufficient recovery state? Answer: It can describe intent without establishing the outcome of an external effect. Recovery needs recorded commitments and observable receipts.
- Does a high-confidence route authorize publication? Answer: No. Decision strength and action permission are separate gates.
- What should a stalled-task alert measure? Answer: Time since meaningful state or artifact progress, alongside heartbeat and budget information.
Sources
- John Lindquist's Script Kit: firsthand automation project and script entry points.
- Temporal workflow execution: durable state, event history, and recovery concepts.
- TypeSafe introduction: verified typed decision primitives; no SDK calls are reproduced here.