Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#3,864 2 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

@V3RON ya está trabajando en esto.

Desde el 21/10/2026.

  • #3865 de @V3RON — abierto

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
25/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Estancado
Stack tecnológico
node.js, typescript
Área
backend-api-design, cli, mobile

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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).
Lenguaje dominante
TypeScript
Estrellas
5.1k
Forks
339
Merge medio
12 h 22 min
PR fusionados (30 d)
701

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de callstack/agent-device

Todos los issues de callstack/agent-device

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.