Repository navigation
Description
Part of #1308.
Scope
An agent that sends deviceBaseline on an agent-device allocate, through a worker or a gateway, gets a fresh copy of that Simlock baseline, or Simlock's own refusal with no lease left. The reply names the baseline and its version. The agent-device daemon never sees the key. This is the whole feature; the agent-device CLI flag --device-baseline is built in agent-device's own repo.
In short
The front reads one more allocate key, deviceBaseline, and passes it to lease.request as baseline. A target beside it is dropped (the baseline fixes the device), and the granted device in the reply gains baseline {name, version}.
flowchart LR
A[allocate] --> B["front: read fields<br/>(+ deviceBaseline)*"] --> C["lease.request<br/>(+ baseline, no class)*"] --> D[grant] --> E["forward to daemon<br/>(deviceBaseline stripped)*"] --> F["reply + data.lease.device<br/>(+ baseline)*"]
* = changed step.
Before and after, with raw allocates (the CLI flag ships with agent-device):
| Allocate params | Today | After |
|---|---|---|
platform: "ios", deviceBaseline: "logged-in" |
factory simulator | lease.request {platform: "ios", baseline: "logged-in"}; reply data.lease.device.baseline {name: "logged-in", version: <n>} |
the same + target: "mobile" |
class phone |
no class sent |
the same + target: "watch" |
refused: unknown --target watch; use mobile, tv or desktop |
refused: unknown --target watch; use mobile, tv or desktop (as today) |
the same + device: "iPhone 17 Pro" |
model, factory | baseline and model sent |
deviceBaseline: "no-such" / mismatched / stale / "Logged In" / with physical: true |
factory device | refused by simlock: <Simlock's message>; no lease |
deviceBaseline: 7 |
factory device | refused: malformed deviceBaseline |
deviceBaseline on a later command's flags, input or batch step |
forwarded | removed before forwarding |
<Simlock's message> is the message of the error lease.request throws, as the front already relays it (F6).
If this goes wrong, an agent asking for a baseline silently gets a factory device, or open fails with an agent-device error about an unknown key.
Technical spec
Facts
Commit f4e1c29. agent-device rows at the pinned v0.21.35.
| # | Fact | Source |
|---|---|---|
| F1 | The front reads allocate fields only through leaseCallFields: device, deviceKey, imageTag, leaseId, osVersion, platform, serial, target, ttlMs, udid. |
src/agent-device/shared/rpc.ts:90-111 |
| F2 | planOf maps device → model, else target → class via CLASS_OF_TARGET; strings imageTag, osVersion pass as given; physical: true passes. |
src/agent-device/front/allocate.ts:118-139 |
| F3 | An unmapped target is refused before planning, whether or not device is set. |
src/agent-device/front/allocate.ts:89-94, :96-110 |
| F4 | lease.request takes baseline: baselineNameSchema.optional(); the name allows a-z, 0-9, ., _, -, starting with a letter or digit, so logged-in passes and Logged In is refused. |
src/contract/operations.ts:162, src/contract/schemas.ts:93-99 |
| F5 | lease.request refuses a baseline with a class ("a request names a baseline or a class, not both…") and a baseline with physical: true ("baseline has no meaning for a physical device"). |
src/contract/operations.ts:199-215, :218-246, :297-301 |
| F6 | A lease.request error reaches the CLI as refused by simlock: ${mapped.message} (except QUEUE_TIMEOUT). |
src/agent-device/front/allocate.ts:245-252 |
| F7 | Unknown, mismatched and stale baselines are the errors UNKNOWN_BASELINE, BASELINE_MISMATCH (field platform, model, osVersion, mode or imageTag), BASELINE_STALE. |
src/contract/errors.ts:94-101 |
| F8 | A grant's device.spec carries baseline: {name, version} when made from a baseline, none otherwise. |
src/contract/schemas.ts:152-159 |
| F9 | withGrantedDevice writes data.lease.device as {model, osVersion, physical, imageTag?} from the grant spec. |
src/agent-device/front/allocate.ts:397-412 |
| F10 | forwardedBody removes device, deviceKey, imageTag, osVersion, physical, target from the allocate sent to the daemon. |
src/agent-device/front/allocate.ts:262-285 |
| F11 | ruleLeaseKeys deletes osVersion and imageTag from every place of a non-allocate request (flags, input, batch steps). |
src/agent-device/front/request-rules.ts:137-147 |
| F12 | malformedField refuses a non-string in STRING_FIELDS (platform, target, udid, serial, device, deviceKey, osVersion, imageTag) as refused: malformed <field>. |
src/agent-device/shared/selectors.ts:11-35, src/agent-device/front/request-rules.ts:122-133 |
| F13 | A gateway excludes a worker answering UNKNOWN_BASELINE, BASELINE_MISMATCH or BASELINE_STALE and walks again; it forwards baseline to the worker. |
src/gateway/fleet-coordinator.ts:123-125, :1639 |
| F14 | agent-device names spec keys in LEASE_DEVICE_SPEC_KEYS (osVersion, imageTag, physical; main adds deviceMode) and its --baseline flag (key baseline) is the diff screenshot file. |
agent-device v0.21.35:packages/contracts/src/lease-scope.ts:275-279, v0.21.35:packages/command-registry/src/flag-definitions-workflow.ts:364 |
| F15 | Existing tests: osVersion reaches the lease request (edge.test.ts:697), the daemon gets neither key (:744), the reply carries data.lease.device (:759), simlock refusals relayed (:797), unmapped target (:1120), target → class (:1157), later commands lose the keys (:3659), malformed fields (:3847); gateway osVersion with requires (gateway-front.test.ts:909). |
those lines |
Modules touched
Searches: leaseCallFields, planOf, forwardedBody, withGrantedDevice, ruleLeaseKeys, STRING_FIELDS, "osVersion", "imageTag" in src/, docs and website.
flowchart LR
R["shared/rpc.ts*"] --> A["front/allocate.ts*"]
S["shared/selectors.ts*"] --> Q["front/request-rules.ts*"]
A --> L["lease.request (contract, unchanged)"]
A --> H[host link → daemon]
* = changed. Also docs: src/agent-device/AGENTS.md (flow steps 2 to 5), website/src/content/docs/docs/using-devices/agent-device.mdx (the "open takes a lease" bullets near line 123 and "Messages you may see" near line 213), docs/internal/adr/0023-agent-device-is-served-by-an-optional-edge-module.md:74, docs/internal/adr/0061-every-virtual-device-is-a-copy-of-a-source-and-a-baseline-is-a-named-source.md:210-211.
Contract and event changes
None: lease.request.baseline exists (F4). The new wire field read is deviceBaseline on an agent-device allocate: a string, bounded by baselineNameSchema at lease.request (F4); a non-string is refused: malformed deviceBaseline (F12). No protocol bump; no event changes.
Other code on the same state
Searches: the allocate params bag (call.params, leaseCallFields) — 4 readers: planOf, refusalFor, forwardedBody, checkRequest. All four see the key: refusalFor unchanged, planOf maps it, forwardedBody strips it, checkRequest type-checks it. The front map stores no spec field. Open PRs #1225 and #1254 (external) edit the same functions; no shared state at runtime.
Failure modes
| Call | Outcome | What happens | Limit, counted from |
|---|---|---|---|
lease.request with baseline |
ok | grant; allocate forwarded without the key; reply names the baseline | queue wait 330 s, from admit (as today) |
lease.request with baseline |
UNKNOWN_BASELINE, BASELINE_MISMATCH, BASELINE_STALE, BAD_REQUEST |
refused by simlock: <message>, no lease, nothing forwarded |
at once |
gateway lease.request |
a worker lacks the baseline | the gateway tries the next worker (F13); none → refusal relayed | gateway.leaseRequestTimeoutMs (as today) |
Writes no state of its own.
Rules in play
- ADR 0023 §2: "CLI's selectors mapped to
platform,modelorclass,osVersionandimageTag" — addsbaselineto that list. - ADR 0061 §5: "A request carries an optional
baselinename … (CLI--baseline,SIMLOCK_BASELINE, HTTP, MCP, the client)" — adds agent-device'sdeviceBaseline; the mismatch and unknown rules apply unchanged through the front. - Documentation rule 9: the public surface (agent-device front) changes, so the website page changes in the same PR.
Tests
Seam: the worker front through src/agent-device/edge.test.ts (fake daemon, faked driver with a saved baseline), and the gateway front through src/agent-device/gateway-front.test.ts; extend the tests named in F15.
- B1. An allocate with
deviceBaseline: "logged-in"makes a lease request withbaseline: "logged-in": iOS alone; Android alone; withtarget: "mobile"(noclass); withdevice: "iPhone 17 Pro"(modeltoo). Extendsedge.test.ts:697. - B2. A baseline Simlock refuses answers
refused by simlock: <message>and leaves no lease: unknown name; model mismatch; platform mismatch; stale; nameLogged In; withphysical: true. Extendsedge.test.ts:797. - B3. The front refuses
deviceBaseline: 7withrefused: malformed deviceBaseline, andtarget: "watch"beside a baseline withrefused: unknown --target watch; use mobile, tv or desktop. Extendsedge.test.ts:3847and:1120. - B4. The relayed reply's
data.lease.devicecarriesbaseline {name: "logged-in", version: <the saved version>}for a grant from a baseline, and nobaselinekey otherwise. Extendsedge.test.ts:759. - B5. The agent-device daemon never receives
deviceBaseline: not on the forwarded allocate, not on a later command'sflags,inputor batch step. Extendsedge.test.ts:744and:3659. - B6. Through a gateway, an allocate with
deviceBaselinereaches the worker's lease request withbaselineandrequires: ["agent-device"], and the reply carriesbaseline; an unknown baseline answersrefused by simlock:. Extendsgateway-front.test.ts:909.
Done when
pnpm exec vitest run --project unit src/agent-device/passes, with B1 to B6 red onmain.src/agent-device/AGENTS.mdflow steps 2 to 5 namedeviceBaseline(read, refused when malformed, mapped tobaselinewith no class, stripped, echoed).- The website agent-device page names
--device-baseline/deviceBaselinein its "opentakes a lease" bullets, saying the flag needs the agent-device release that adds it, and listsrefused: malformed deviceBaselineunder "Messages you may see". - ADR 0023's list of mapped selectors and ADR 0061 §5's list of places a baseline is named include agent-device's
deviceBaseline, and §5's sentence "agent-device does not send a baseline yet; that is a later change on both sides" is replaced by one saying the front mapsdeviceBaselinetobaseline.
Out of scope
deviceMode(bug agent-device front drops the allocate's mode, so a full simulator cannot be leased through it #1223, PRs fix(agent-device): an allocate's device mode reaches the lease request (#1223) #1225, feat(agent-device): the allocate reply reports the granted device mode #1254).- The agent-device CLI flag, spec key and echo check (callstack/agent-device, its own PR).
- A slow-lane test.
Depends on
Written by an agent.
Activity
test: the relayed allocate reply names the baseline and its version (#…
feat(agent-device): the reply's device names the baseline it was made…
test: a baseline Simlock refuses answers refused by simlock and leave…
test: the front refuses a non-string deviceBaseline and keeps refusin…
feat(agent-device): a non-string deviceBaseline is refused as malform…
test: the agent-device daemon never receives deviceBaseline (#1312)
feat(agent-device): later commands lose deviceBaseline before forward…
test: through a gateway, deviceBaseline reaches the worker as baselin…
docs(agent-device): the front maps deviceBaseline to baseline (#1312)
refactor(agent-device): split the baseline tests and the daemon rig o…
refactor(agent-device): chosenDevice returns early per case to lower …
feat(agent-device): the front leases from a named baseline (callstack…