Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Proxy lease by device spec: --os and --image-tag, honoured or refused by the backend

Aperta
  • Qualcosa non va?
#3,864 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@V3RON ci sta già lavorando.

Dal 21/10/2026.

  • #3865 di @V3RON — aperta

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
25/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Ferma
Stack tecnologico
node.js, typescript
Ambito
backend-api-design, cli, mobile

Direzione di ricerca

Start with the proxy lease flow and the exported keys beside LEASE_ALLOCATE_PROVIDER_FLAG_KEYS in packages/contracts/src/lease-scope.ts; trace how LeaseAllocateOptions and the MCP open schema carry allocation options. Use the completion conditions to map the required proxy, daemon, live-lease, and documentation changes. Done means the listed behaviors, schemas, remote-proxy docs, help text, and ADR amendment are complete; an open linked pull request (#3865) already covers this work.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

enhancement

Purpose

open through connect proxy already allocates by spec: without --udid/--serial it sends platform, target, device, and the backend picks the device (#3487). Simlock, as the backend, can also pick by OS version and Android image tag. This adds those two keys to the proxy lease, and makes a backend that cannot honour them refuse instead of silently ignoring them.

Simlock side: callstackincubator/simlock#814.

Flow

sequenceDiagram
    participant CLI as agent-device CLI
    participant B as backend (simlock front)
    participant D as agent-device daemon
    CLI->>B: lease.allocate {leaseId, platform, target, device?, osVersion?, imageTag?}
    alt backend consumes the spec
        B->>B: pick device by spec (validate os grammar, class, tag)
        B->>D: lease.allocate {leaseId, udid|serial, ttlMs} (spec keys stripped)
        D-->>B: lease {deviceKey}
        B-->>CLI: lease {deviceKey, device: {model, osVersion, imageTag?}}
    else plain daemon receives a spec key
        D-->>CLI: UNSUPPORTED_OPERATION reason device-spec-unsupported, keys: [...]
    else backend older than this feature
        B-->>CLI: lease {deviceKey} without device facts
        CLI->>B: lease.release
        CLI-->>CLI: fail: device-spec-unsupported
    end

Wire

New keys on agent_device.lease.allocate, one exported list beside LEASE_ALLOCATE_PROVIDER_FLAG_KEYS in packages/contracts/src/lease-scope.ts, also on LeaseAllocateOptions:

Flag Key Type Validated by
--os <version|range> osVersion string, opaque backend (simlock: exact or range, Android = API level)
--image-tag <tag> imageTag string backend (Android only)

Echo on the returned lease (data.lease.device), written by the backend that honoured the request:

Field Type Meaning
lease.device.model string model granted
lease.device.osVersion string exact OS granted
lease.device.imageTag string? Android image tag granted

deviceKey stays the identity. lease.device is the proof the spec was understood.

Rules

  • Flags on open, install, reinstall, uninstall; connect proxy stores them as defaults like platform and device.
  • --target stays the class selector (mobile, tv, desktop); the backend maps it. No --device-class.
  • A daemon that receives either key on an allocate refuses: UNSUPPORTED_OPERATION, details.reason: 'device-spec-unsupported', details.keys. Local daemon and plain agent-device proxy included. No partial honouring.
  • A lease returned without lease.device after a request that named a spec key: the CLI releases it and fails with the same reason.
  • A live lease serves a later open only when its spec matches the request's; otherwise CONNECTION_DEVICE_CONFLICT.
  • Keys are agent-visible in MCP and the SDK schemas (not operatorField).
  • No --allow-download, --mode, lease-wait: downloads and mode are backend config.
  • Decision recorded as an amendment to ADR 0007, no new ADR.

Example

agent-device connect proxy --daemon-base-url http://worker:7700/v1/agent-device
agent-device open MyApp --platform ios --device "iPhone 17 Pro" --os ">=26"
agent-device open MyApp --platform android --os 34 --image-tag google_apis_playstore
agent-device open MyApp --platform ios --os ">=26"   # local daemon
# Error: UNSUPPORTED_OPERATION device-spec-unsupported (keys: osVersion)

open --json prints lease.device.

Completion conditions

  • open --os/--image-tag through a proxy sends the keys on allocate; devices.list is not called first.
  • A fake backend that echoes lease.device → open succeeds and reports the granted model and OS.
  • A fake backend that returns no lease.device → the lease is released, open fails with device-spec-unsupported.
  • Local daemon and agent-device proxy refuse the keys with the typed reason; the lease registry records nothing.
  • Second open with a different --os on a live lease → CONNECTION_DEVICE_CONFLICT.
  • MCP open tool schema and LeaseAllocateOptions carry the two keys; remote-proxy.md and help remote document them.
  • ADR 0007 amended.

Postponed

--physical was in the first cut and is dropped (Decision comment below): neither phone reaches the daemon simlock runs today (iOS: the daemon-wide simulator set hides physical devices in agent-device's inventory; Android: phones sit on the default adb server, the daemon on simlock's). Simlock will spec a phone path on its side first.

Sequencing

  1. This issue (agent-device release).
  2. Simlock front maps the keys and echoes lease.device (callstackincubator/simlock#814).
Lingua principale
TypeScript
Stelle
5.1k
Fork
339
Merge medio
11h 54m
PR unite (30g)
745

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di callstack/agent-device

Tutte le issue di callstack/agent-device

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.