Skip to content

agent-device: allocate a device from a named baseline #1308

Closed
1 of 1 issue completed
Closed

Description

@V3RON

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
Loading

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.
  • open fails 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 --target gets 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-device routes, which turn agent-device lease calls into Simlock lease operations.
  • granted device: the data.lease.device object the front adds to the relayed allocate reply.
  • deviceBaseline: the allocate key agent-device sends for --device-baseline; named like deviceMode because agent-device's --baseline already means a screenshot file for diff.

Non-goals

Completion conditions

  • An allocate with deviceBaseline through a worker and through a gateway leases a copy of that baseline, and the reply carries data.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: true with a baseline come back as refused by simlock: with Simlock's message and leave no lease; a non-string deviceBaseline is refused: malformed deviceBaseline.
  • A target beside a baseline asks Simlock for no class; an unmapped target is still refused.
  • The agent-device daemon receives deviceBaseline neither on the allocate nor on any later command.
  • The website agent-device page names --device-baseline and its refusals; src/agent-device/AGENTS.md flow 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 naming deviceBaseline.

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, key deviceBaseline (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).
  • deviceMode stays 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

Completion conditions → #1312's Done when lines, all of them.

Open work in the same area:

Written by an agent.

Activity

  1. added
    feature:specSpec in progress, business and technical together.
    on Nov 5, 2026
  2. V3RON commented on Nov 5, 2026

    @V3RON
    ContributorAuthor

    Spec updated: all sections written from the spec session; task #1312 added.

    Written by an agent.

  3. added
    feature:plannedSplit into tasks. Never picked up itself.
    and removed
    feature:specSpec in progress, business and technical together.
    on Nov 5, 2026
  4. github-actions commented on Nov 5, 2026

    @github-actions
    Contributor

    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.

  5. V3RON commented on Nov 5, 2026

    @V3RON
    ContributorAuthor

    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-in got a copy of the baseline with lease.device.baseline {logged-in, 1}, --target mobile still 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    feature:plannedSplit into tasks. Never picked up itself.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions