Skip to main content

Agent author guide

This guide is for people building agents or workflow runners on top of AetherFS.

Your job is to make good use of sessions and the public control surface without leaking internal assumptions into your design.

What matters most in this role​

As an agent author, the highest-signal concepts are:

  • session lifecycle
  • manifest-driven discovery
  • mutation routes
  • cache versus bus versus annotations
  • checkpoints
  • approvals
  • commits and promotions

Your core workflow​

The default agent workflow is:

  1. create or receive a session
  2. inspect session detail and manifest
  3. mutate files or paths
  4. publish progress or derived state
  5. checkpoint before risky changes
  6. request approval when required
  7. commit or promote after the workflow allows it

Read these pages first​

Start here:

Then use these references:

Discovery model​

Do not start by guessing path shapes or assuming a generic remote disk API.

Use:

  • session detail for current workspace context
  • manifest for tree discovery

That is the correct public model.

Mutation model​

Choose the simplest mutation surface that matches the job.

Use:

  • directory and rename routes for path changes
  • batch when one logical action contains several path changes
  • patchSegments when you truly need partial or sparse mutation
  • expected hashes when stale clients must fail safely

State model​

Choose the right metadata surface.

Use:

  • cache for keyed structured workflow state
  • bus for live progress and event-style coordination
  • annotations for durable review notes
  • events for durable history

Do not use one of these surfaces as a substitute for all the others.

Approval model​

Use approvals when your agent is about to cross a meaningful workflow boundary.

Good triggers:

  • commit to a durable target
  • large-scale delete
  • source promotion
  • risky transformation

When requesting approval:

  • include a clear machine-readable reason
  • include useful human-facing details
  • expect the session to pause in SESSION_STATUS_PENDING_APPROVAL

Persistence model​

Agents should not treat commit as a save button.

Use:

  • checkpoints for recoverability
  • commits for durable outcomes
  • source promotion for reusable future baselines

Concurrency model​

The default order is:

  1. expected hashes
  2. collaboration locks when contested edits matter
  3. POSIX locks only when low-level compatibility is actually required

Common agent-author mistakes​

Avoid:

  • inventing unsupported REST file routes
  • treating the bus as durable state
  • treating xattrs as review comments
  • skipping checkpoints before risky automated edits
  • assuming health, approval, and persistence are interchangeable concepts

Fastest useful agent-author toolkit​

If you only remember one reading path:

  1. sessions
  2. manifest
  3. mutation routes
  4. cache/bus/annotations
  5. approval
  6. commit/promotion

That is the core of a strong public agent integration.