Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đang mở
  • Có gì không ổn?
#3,864 2 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

@V3RON đang làm issue này rồi.

Từ ngày 21/10/2026.

  • #3865 của @V3RON — đang mở

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
25/100
Loại issue
Tính năng
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
node.js, typescript
Lĩnh vực
backend-api-design, cli, mobile

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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).
Ngôn ngữ chính
TypeScript
Star
5.1k
Fork
339
Merge trung bình
11 giờ 54 phút
Pull request đã merge (30 ngày)
745

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của callstack/agent-device

Tất cả issue của callstack/agent-device

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.