Skip to content

agent-device: the front leases from a named baseline #1312

Closed

Description

@V3RON

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)*"]
Loading

* = 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]
Loading

* = 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, model or class, osVersion and imageTag" — adds baseline to that list.
  • ADR 0061 §5: "A request carries an optional baseline name … (CLI --baseline, SIMLOCK_BASELINE, HTTP, MCP, the client)" — adds agent-device's deviceBaseline; 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 with baseline: "logged-in": iOS alone; Android alone; with target: "mobile" (no class); with device: "iPhone 17 Pro" (model too). Extends edge.test.ts:697.
  • B2. A baseline Simlock refuses answers refused by simlock: <message> and leaves no lease: unknown name; model mismatch; platform mismatch; stale; name Logged In; with physical: true. Extends edge.test.ts:797.
  • B3. The front refuses deviceBaseline: 7 with refused: malformed deviceBaseline, and target: "watch" beside a baseline with refused: unknown --target watch; use mobile, tv or desktop. Extends edge.test.ts:3847 and :1120.
  • B4. The relayed reply's data.lease.device carries baseline {name: "logged-in", version: <the saved version>} for a grant from a baseline, and no baseline key otherwise. Extends edge.test.ts:759.
  • B5. The agent-device daemon never receives deviceBaseline: not on the forwarded allocate, not on a later command's flags, input or batch step. Extends edge.test.ts:744 and :3659.
  • B6. Through a gateway, an allocate with deviceBaseline reaches the worker's lease request with baseline and requires: ["agent-device"], and the reply carries baseline; an unknown baseline answers refused by simlock:. Extends gateway-front.test.ts:909.

Done when

  • pnpm exec vitest run --project unit src/agent-device/ passes, with B1 to B6 red on main.
  • src/agent-device/AGENTS.md flow steps 2 to 5 name deviceBaseline (read, refused when malformed, mapped to baseline with no class, stripped, echoed).
  • The website agent-device page names --device-baseline / deviceBaseline in its "open takes a lease" bullets, saying the flag needs the agent-device release that adds it, and lists refused: malformed deviceBaseline under "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 maps deviceBaseline to baseline.

Out of scope

Depends on

Written by an agent.

Activity

  1. added
    task:draftScope written; technical spec or its spec check missing.
    on Nov 5, 2026
  2. added
    task:readySpec checked. An agent may implement it once its Depends on allow.
    and removed
    task:draftScope written; technical spec or its spec check missing.
    on Nov 5, 2026
  3. self-assigned this
    on Nov 5, 2026
  4. added a commit that references this issue on Nov 5, 2026
    ef0d3e8
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

task:readySpec checked. An agent may implement it once its Depends on allow.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions