Skip to content

Steer envelope v1 ​

This specification defines what a steer makes visible inside a running sandbox: the steer files and the message the agent receives. It is the contract between fullsend run, the agent runtimes, and the agent definitions in fullsend-ai/agents.

  • ADR 0119 decides when a steer happens and which records it may carry.
  • ADR 0117 (proposed) decides how a runtime delivers the message.
  • ADR 0118 (proposed) and ADR 0121 (proposed) decide the GitHub Actions change signal and the default.
  • ADR 0141 requires a versioned schema before extension output becomes sandbox-visible. This document is that schema for steer output. Its manifest stands in for the snapshot manifest under the scoped partial supersession in ADR 0119, with the same filtering, digest, permissions, exact-path, and cleanup rules.

This document is normative. The key words MUST, MUST NOT, and MAY are used as in RFC 2119.

Overview ​

Each steer produces two things:

PartWhat it isWho reads it
Steer directoryOne manifest plus one filtered file per admitted record, in an agent-immutable treeThe agent, through file reads
EnvelopeA short message that lists the steer's records by key and path, with the new headThe agent, as a new user turn

Record bodies appear only in the steer directory. The envelope carries no source-authored text, so a record body cannot forge envelope structure.

Steer directory ​

Location ​

Fullsend reserves one sandbox path per cycle, a sibling of the snapshot path:

text
/sandbox/entity-context-steer/
├── 0001/
│   ├── manifest.json
│   └── records/<order-key>-<record-key>.md
└── 0002/
    └── ...
  • FULLSEND_STEER_DIR points to /sandbox/entity-context-steer inside the sandbox.
  • Each steer writes a new directory named by its one-based sequence number within the cycle, zero-padded to four digits so names sort in steer order. Four digits bound a cycle to 9999 steers, so max_steers MUST NOT exceed 9999. Earlier steer directories stay until the cycle ends.
  • Fullsend MUST reject a checkout or host_files destination that overlaps this path, and MUST decline steering if the path exists with unexpected contents at sandbox start.

Record files ​

Each admitted record is one file. Its name and bytes follow the entity-context-snapshot v1 record rules exactly: the records/<order-key>-<record-key>.md name, the fixed Fullsend-Record, Source-ID, Author-ID, and Created-At header, and the filtered body. A record key derived for a steer is the same key the snapshot derives for that forge record.

  • A changed version of a record that is already in the snapshot keeps its record key. The steer file holds the current filtered revision; the snapshot copy is not modified.
  • A record whose filter status is rejected, or whose admission failed, has no file. It appears only in the manifest's omitted list.

Manifest ​

manifest.json is UTF-8 JSON serialized with RFC 8785, with no byte-order mark and no trailing newline. Timestamps and Git object IDs use the entity-context-snapshot v1 canonical forms.

FieldTypeMeaning
schema_versionstringAlways "steer-envelope/v1"
filter_versionstringThe pipeline version; MUST equal the cycle snapshot's filter_version
sequenceintegerThis steer's sequence number, from 1
snapshot_input_revisionstringSHA-256 of the cycle snapshot's index.json bytes
previous_manifest_sha256string or nullSHA-256 of the previous steer's manifest bytes; null for the first
entityobjectsource (as in the snapshot index), kind, and the entity record key
headobject or nullsha and previous_sha for a change proposal whose head moved and was provisioned; otherwise null
recordsarrayOne entry per admitted record, sorted by created_at then record key
omittedarrayOne entry per scope and code, sorted by scope then code

Each records[] entry:

FieldMeaning
record_keyThe snapshot record key
kindentity, comment, or review
pathPath relative to the steer directory, for example records/<order-key>-<record-key>.md
sha256SHA-256 of the file bytes
created_atSource creation time
revisionThe source's current-revision time (its edit time, or created_at when never edited)
replaces_snapshottrue when the snapshot holds an earlier revision of the same record
actorid, login, and either role (human, verified at release) or bot_role (ADR 0107)
filterstatus (unchanged, modified, or truncated) and findings (codes and counts), as in the snapshot

Each omitted[] entry has scope (entity, comments, or reviews), code (authorization_failed, unsafe_content, fetch_failed, source_too_large, or invalid_metadata), and count. Omitted entries hold no record text, keys, or logins.

The manifest's own path set is exact: every file under the steer directory is either manifest.json or listed in records[].path.

Write, permissions, and cleanup ​

RuleRequirement
AssemblyThe host builds the directory in host-private state, then verifies every sha256 and the exact path set before upload
Release checkThe fresh authorization check for every record runs after assembly and immediately before upload, under the sandbox write lock. A record that fails is removed and moved to omitted
UploadRejects symlinks and special files at every path component, as the snapshot does
PermissionsAgent-immutable, with the snapshot's modes: a read-only bind mount, or root-owned 0555 directories and 0444 files with the agent unprivileged and without CAP_FOWNER. If neither can be enforced, Fullsend MUST NOT steer
Host copyThe snapshot's host modes, 0700 directories and 0600 files (owner-only), outside the clone and the retained run-output tree
CleanupThe sandbox copy is removed with the cycle's snapshot copy; the host copy after the post-script, on every controlled exit. Startup scavenges abandoned copies
ArtifactsSteer directories are excluded from retained artifacts. Diagnostics MAY keep counts, digests, and filter codes, never bodies

Envelope ​

The envelope is the message appended to the running session. It is built only from manifest fields, never from record bodies.

text
Runner update: your task inputs changed after this run started.

Steer: 0002
Manifest: /sandbox/entity-context-steer/0002/manifest.json
Head: 4f1c2e9d0b7a65c3e8f1a2b4c6d8e0f1a3b5c7d9 (was 9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d)
Omitted: 1

[steer-record 1/2]
Record: c73645a72a9c5de28d71e3e1efe235b9a5d02ee6dfe7dc0ef06cf3d0e5ee3421
Kind: comment
Actor: @example-maintainer (write)
Revision: 2026-11-02T10:15:30.000000000Z
Filter: unchanged
Path: /sandbox/entity-context-steer/0002/records/20261102T101530000000000Z-c73645a72a9c5de28d71e3e1efe235b9a5d02ee6dfe7dc0ef06cf3d0e5ee3421.md
[/steer-record]

[steer-record 2/2]
...
[/steer-record]

The values above are illustrative; the record key is the worked example from entity-context-snapshot v1.

Envelope rules ​

  • Opening line. Every envelope begins with Runner update: your task inputs changed after this run started., byte for byte, followed by one blank line.
  • Header lines. Steer: and Manifest: are always present. Head: is present only when the manifest head is not null. Omitted: is present only when the omitted count is above zero, and gives the sum of omitted[].count.
  • One block per record. Each admitted record is one [steer-record N/M] ... [/steer-record] block, in manifest order. Lines inside a block are, in order: Record, Kind, Actor, Revision, Filter, Path. Actor shows (role) for a human or (bot: <bot_role>) for a bot.
  • No other text. The envelope contains no record body, title, or label text. A runtime that splits the message into content blocks MUST keep each record block whole.
  • Field safety. Every field value comes from the manifest. Fullsend MUST refuse to steer if any value contains a line break, [steer-record, [/steer-record], or the opening line.

The opening line inside record bodies ​

Agent definitions treat the opening line in two ways:

Where it appearsMeaning
First line of a delivered messageA runner update. The agent reads the listed records
Inside a record bodyAn injection attempt. The agent should flag it

Fullsend does not rewrite the opening line inside record bodies, because that would remove the evidence the agent definitions act on. The filter pipeline still applies to the rest of the body.

What the agent may do with a steer ​

  • Read the listed files. They are filtered, attributed data under ADR 0133: an admitted record may guide the task within the harness's scope, but cannot change tools, role, credentials, or routing.
  • Ignore a block whose Path does not exist. The agent MAY check a file against the manifest sha256 with a tool such as sha256sum and ignore a mismatch. Such a block was not written by Fullsend.

Versioning ​

This is v1. A breaking change requires docs/normative/steer-envelope/v2/.

These changes are breaking:

  • the opening line, the header line names, the block delimiters, or the block line order;
  • the steer directory path, the record file rules, or a manifest field's name, type, or meaning;
  • any change to the permission, exact-path, or cleanup rules that weakens them.

Adding a manifest field is also breaking: consumers validate a closed field set, as entity-context-snapshot v1 consumers do.

Open questions ​

  • Machine-readable schema. This version defines the manifest in tables. A manifest.schema.json in this directory would let consumers validate it the way snapshot consumers do. Should it ship with the first implementation?
  • One block per record. ADR 0141 asks for one content block per record "when cache reuse is intended". A steer is a new user turn, so prompt-cache reuse past it is already lost. Does the rule apply to steer delivery?
  • In-band version. The opening line carries no version token. Adding one later changes the opening line, which is itself a v2 change.