Repository navigation
Description
Request: #1203. agent-device side: callstack/agent-device#4235 (the --device-baseline flag and deviceBaseline spec key).
Problem
An agent that leases through agent-device cannot name a Simlock baseline. agent-device's lease spec has no baseline key, its CLI drops spec flags it does not know, and Simlock's agent-device front reads only platform, target, device, osVersion, imageTag, physical and ttlMs from an allocate. The agent gets a factory device instead of the prepared one, and nothing tells it so.
Who it is for
Teams whose agents drive devices through agent-device connect proxy against a Simlock worker or gateway, and want each agent to start from a baseline an operator saved (logged in, onboarding done) instead of a factory device.
Outcome
agent-device open MyApp --platform ios --device-baseline logged-in reaches Simlock as lease.request.baseline: "logged-in". The agent gets a fresh copy of that baseline, with the same fast failures as simlock lease --baseline: an unknown, mismatched or stale baseline is refused at once with Simlock's own message, and no lease is left. The reply the CLI gets names the baseline and its version, so the CLI can tell a Simlock that honoured the key from one that ignored it. The agent-device daemon Simlock runs never sees the key.
How it works for the user
sequenceDiagram
participant CLI as agent-device CLI
participant F as simlock front (/v1/agent-device)
participant L as leasing (worker or gateway)
participant D as agent-device daemon
CLI->>F: lease.allocate {platform, deviceBaseline, target?, device?, ...}
alt front refuses
F-->>CLI: "refused: malformed deviceBaseline" | "refused: unknown --target watch; use mobile, tv or desktop"
else
F->>L: lease.request {platform, baseline, model?, osVersion?, imageTag?, ...} (no class)
alt refused by simlock
L-->>F: UNKNOWN_BASELINE | BASELINE_MISMATCH | BASELINE_STALE | BAD_REQUEST
F-->>CLI: "refused by simlock: <message>", no lease
else granted
L-->>F: grant {device.address, device.spec with baseline {name, version}}
F->>D: lease.allocate {udid|serial, ttlMs} (deviceBaseline stripped)
D-->>F: lease reply
F-->>CLI: same reply + data.lease.device {model, osVersion, physical, imageTag?, baseline {name, version}}
end
end
Before:
$ agent-device open MyApp --platform ios --device-baseline logged-in
# today's agent-device has no such flag; a raw allocate with deviceBaseline gets a factory simulator
After:
$ agent-device open MyApp --platform ios --device-baseline logged-in
# leased a copy of baseline logged-in v3: iPhone 17 Pro, iOS 26.0 (from data.lease.device)
$ agent-device open MyApp --platform ios --device-baseline no-such
Error: refused by simlock: <Simlock's UNKNOWN_BASELINE message>
$ agent-device open MyApp --platform android --device-baseline logged-in # logged-in is an iOS baseline
Error: refused by simlock: <Simlock's BASELINE_MISMATCH message, field platform>
The Error: lines carry Simlock's own lease.request message for that input, word for word; the texts may change with Simlock, never with this feature. The CLI lines need the agent-device release that adds --device-baseline; until then the same allocate is sent raw.
Examples
Allocate params the CLI sends, and what Simlock is asked for. logged-in is an iOS baseline of iPhone 17 Pro, iOS 26.0.
| Input | Today | After |
|---|---|---|
platform: "ios", deviceBaseline: "logged-in" |
key ignored; a factory simulator | lease.request.baseline "logged-in"; a copy of it; reply carries baseline {name: "logged-in", version} |
the same with target: "mobile" |
class phone |
baseline, no class (the baseline wins over the target) |
the same with target: "watch" |
refused: unknown --target watch; use mobile, tv or desktop |
refused: unknown --target watch; use mobile, tv or desktop (unchanged) |
the same with device: "iPhone 17 Pro" |
that model, factory | baseline and model; granted |
the same with device: "iPad Pro 13-inch (M5)" |
that model, factory | refused by simlock: + BASELINE_MISMATCH message; no lease |
platform: "android", deviceBaseline: "logged-in" |
key ignored | refused by simlock: + BASELINE_MISMATCH message (platform); no lease |
deviceBaseline: "no-such" |
key ignored | refused by simlock: + UNKNOWN_BASELINE message; no lease |
| a baseline whose runtime was removed | key ignored | refused by simlock: + BASELINE_STALE message; no lease |
deviceBaseline: "Logged In" |
key ignored | refused by simlock: + Simlock's BAD_REQUEST message for the name; no lease |
deviceBaseline: "logged-in", physical: true |
key ignored | refused by simlock: + Simlock's BAD_REQUEST message; no lease |
deviceBaseline: 7 (a number) |
key ignored | refused: malformed deviceBaseline |
no deviceBaseline |
as today | as today; reply has no baseline |
deviceBaseline on a later command's flags, input or a batch step |
forwarded to the daemon | stripped before forwarding |
What could go wrong
- The agent asks for a baseline and gets a factory device: the key was dropped on the way to leasing. Unlikely; the lease request is pinned by a test, and agent-device's CLI releases a lease whose reply does not name the baseline.
openfails with an agent-device error about an unknown key: the key leaked through to the daemon. Unlikely; the forwarded body is pinned.- A connection with a stored
--targetgets a baseline device whose class differs from the target: by design, the baseline wins.
Words used
- baseline: a named device state an operator saved with
simlock baseline save; each lease naming it gets a fresh copy, e.g.logged-in. - front: Simlock's
/v1/agent-deviceroutes, which turn agent-device lease calls into Simlock lease operations. - granted device: the
data.lease.deviceobject the front adds to the relayed allocate reply. deviceBaseline: the allocate key agent-device sends for--device-baseline; named likedeviceModebecause agent-device's--baselinealready means a screenshot file fordiff.
Non-goals
deviceModethrough the front: bug agent-device front drops the allocate's mode, so a full simulator cannot be leased through it #1223 and its PRs fix(agent-device): an allocate's device mode reaches the lease request (#1223) #1225 and feat(agent-device): the allocate reply reports the granted device mode #1254.- Saving, listing or removing baselines from agent-device.
- Honouring the key on a plain agent-device daemon (agent-device refuses it there).
- A slow-lane test: the path is proven with the allocate the CLI will send against the fake daemon; the real CLI is checked by hand after the agent-device release.
Completion conditions
- An allocate with
deviceBaselinethrough a worker and through a gateway leases a copy of that baseline, and the reply carriesdata.lease.device.baseline {name, version}. Until agent-device ships--device-baseline, the stand-in is the task's tests, which send the same allocate the CLI will. - An unknown, mismatched or stale baseline, a bad name and
physical: truewith a baseline come back asrefused by simlock:with Simlock's message and leave no lease; a non-stringdeviceBaselineisrefused: malformed deviceBaseline. - A
targetbeside a baseline asks Simlock for no class; an unmappedtargetis still refused. - The agent-device daemon receives
deviceBaselineneither on the allocate nor on any later command. - The website agent-device page names
--device-baselineand its refusals;src/agent-device/AGENTS.mdflow steps 2 to 5 name the key; ADR 0023's list of mapped selectors and ADR 0061 §5's list of places a baseline is named include it, and its sentence that agent-device does not send a baseline yet is replaced by one namingdeviceBaseline.
Open questions
Decisions
- No new ADR. ADR 0023 (the edge maps the CLI's selectors) and ADR 0061 §5 (a request names a baseline) get one-line list amendments.
- Flag
--device-baseline, keydeviceBaseline(maintainer, 2026-11-05). - A baseline wins over
target; an unmapped target is still refused (maintainer, 2026-11-05). - The reply echoes
baseline {name, version}(maintainer, 2026-11-05). - We write the agent-device PR ourselves, outside this task list (maintainer, 2026-11-05).
deviceModestays with agent-device front drops the allocate's mode, so a full simulator cannot be leased through it #1223 (maintainer, 2026-11-05).- Fast-lane tests only (maintainer, 2026-11-05).
Shared values
none (one task).
Behaviours
| Behaviour (invoker, action, what it sees) | Seam | Cases | Task |
|---|---|---|---|
B1. A CLI allocate with deviceBaseline asks Simlock for that baseline |
worker front, src/agent-device/edge.test.ts |
iOS alone; Android alone; with target: "mobile" (no class sent); with device (model sent too) |
#1312 |
B2. A baseline Simlock refuses answers refused by simlock: <message> and leaves no lease |
worker front, edge.test.ts |
unknown name; model mismatch; platform mismatch; stale; bad name Logged In; with physical: true |
#1312 |
B3. A malformed deviceBaseline or an unmapped target beside it is refused by the front |
worker front, edge.test.ts |
deviceBaseline: 7 → refused: malformed deviceBaseline; target: "watch" with a baseline → the unknown-target message |
#1312 |
| B4. The relayed reply names the baseline the device was copied from | worker front, edge.test.ts |
granted from a baseline → baseline {name, version}; no baseline → no baseline key |
#1312 |
B5. The agent-device daemon never receives deviceBaseline |
worker front, edge.test.ts |
the forwarded allocate; a later command's flags, input and a batch step |
#1312 |
B6. An allocate with deviceBaseline through a gateway reaches the worker's lease request and the reply names the baseline |
gateway front, src/agent-device/gateway-front.test.ts |
baseline on the worker → granted, requires: ["agent-device"] sent, reply carries baseline; unknown baseline → refused by simlock: |
#1312 |
Tasks
- agent-device: the front leases from a named baseline #1312 agent-device: the front leases from a named baseline — an agent sending
deviceBaselineon an allocate gets a copy of that baseline, or Simlock's refusal.
Risk: an agent silently gets a factory device.
Completion conditions → #1312's Done when lines, all of them.
Open work in the same area:
- PR fix(agent-device): an allocate's device mode reaches the lease request (#1223) #1225 (bug agent-device front drops the allocate's mode, so a full simulator cannot be leased through it #1223, external, open) and PR feat(agent-device): the allocate reply reports the granted device mode #1254 (draft, external) change
leaseCallFields,planOf,forwardedBody, the reply'sdata.lease.deviceand the same docs. No Depends on: neither is a task of a feature and their merge time is unknown; whichever lands second rebases. - callstack/agent-device PR #4183 (merged) added
--device-mode; the agent-device change for this feature addsdeviceBaselinebeside it inLEASE_DEVICE_SPEC_KEYS(packages/contracts/src/lease-scope.ts).
Written by an agent.
Activity
V3RON commentedon Nov 5, 2026
Spec updated: all sections written from the spec session; task #1312 added.
Written by an agent.
feat(agent-device): the front leases from a named baseline (#1319)
github-actions commentedon Nov 5, 2026
Closing: all 1 sub-issues are closed. The PR that closed the last one walks the completion conditions (delivery rule 9); reopen this if one does not hold on
main. Flip its ADRs to Accepted if delivery has not.V3RON commentedon Nov 5, 2026
Delivery run
Merged: #1319 (#1312)
Parked: none
Waiting: none
Manual check (maintainer asked): agent-device built from callstack/agent-device#4236 against a worker at the PR head;
open --device-baseline logged-ingot a copy of the baseline withlease.device.baseline {logged-in, 1},--target mobilestill granted, unknown and mismatched baselines refused word for word with no lease left. The Android platform-mismatch path was not reachable on this Mac (adb port held by another session); the unit test covers it.Written by an agent.