Manage multiple Agentlet devices and device-scoped Profiles

[mydmdm]

Problem

After #254 enabled remote Agentlets sharing one connection token, Huabu still models the supervised local Agentlet as the only configurable machine:

• there is no durable, owner-visible directory of connected or previously connected Agentlet devices;
• Profile runtime availability is not derived from device connectivity (selectableProfileIds currently contains every persisted Profile);
• Settings always displays every Profile without distinguishing connected and disconnected target devices;
• Add Agent always binds a new Profile to the supervised local Agentlet and cannot target another connected device;
• the default Agentlet identity is hostname-only, so Windows and WSL on the same host collide.

Desired behavior

Add a small multi-Agentlet device-management layer while preserving Profiles as durable templates and Gateway as the live-connection authority.

Devices

• Persist authenticated Agentlet device metadata in Huabu across server restarts.
• Show a Devices section first in Settings > Agent with online/offline state, hostname, environment/platform, last-seen time, and Profile count.
• Support forgetting a device only when it is offline and has zero Profiles. Do not cascade-delete Profiles or conversation bindings.
• Treat Gateway state as authoritative for whether a device is currently online; the durable registry stores historical display metadata only.

Profiles

• Compute selectableProfileIds from Profiles whose target device is currently connected.
• Runtime Agent selectors show only selectable Profiles.
• Settings shows connected-device Profiles by default and provides an explicit Show disconnected affordance so stale Profiles remain manageable and deletable.
• Add Agent requires selecting a currently connected device before choosing a harness. Discovery, launch preview, and creation target that selected device.
• The Profile device is immutable after creation and remains read-only while editing.

Device identity

• Replace hostname-only implicit identity with a stable Agentlet installation/device identity persisted locally by Agentlet.
• Carry hostname and a useful environment label (windows, macos, linux, or wsl, including WSL distribution where available) as display metadata rather than using mutable display information as the primary key.
• Preserve explicit --agentlet-id as an override.
• Define a deterministic, non-destructive compatibility path for existing hostname-bound Profiles before changing the default identity.

Acceptance criteria

• Device metadata survives Huabu restart; online state reflects the live Gateway.
• Connection and disconnection update status and last-seen metadata.
• Online devices and devices referenced by Profiles cannot be forgotten.
• Offline-device Profiles are excluded from runtime selectors but remain accessible in Settings.
• Add Agent discovers and validates against the selected online device and persists that immutable target.
• Windows and WSL on one hostname can connect concurrently with stable distinct identities.
• Existing hostname-bound Profiles have a tested compatibility/migration path.
• Device and Profile APIs use shared schemas and owner authorization.
• Agentlet, Agenetes, server, and Settings tests cover the lifecycle.
• Agent Profile and connection architecture documentation is updated.

Non-goals

Per-device credentials, enrollment approval, remote installation, automatic Profile reassignment, cascade deletion, device renaming, and token rotation/revocation.

Related

• Allow configuring the Agentlet connection token with generated fallback #254 — shared configurable Agentlet/RFS connection token
• Configure shared Agentlet connection token #265 — implementation of Allow configuring the Agentlet connection token with generated fallback #254

[mydmdm]

Confirmed MVP scope

Use active connected devices only for the first implementation. GET /api/acp/devices projects the live Gateway connections; Settings shows only currently connected devices. This phase does not add a durable device registry, offline device history, last-seen persistence, or forget/delete-device operations.

Profile behavior in this phase:

• compute runtime selectableProfileIds from currently connected target agentletIds;
• Add Agent selects one active device and persists that immutable agentletId; discovery and preview target the selection;
• keep unavailable Profiles manageable in Settings (visually marked or behind a Show unavailable affordance) rather than deleting or making them unreachable.

The remaining material design question is the default agentletId and backward-compatible Windows/WSL collision behavior. Per-device persistent identity can remain a later phase if the MVP retains hostname plus explicit --agentlet-id override.

[mydmdm]

Proposed identity transition

Use a dedicated Agentlet-owned identity file such as ~/.agentlet/device.json rather than composing mutable machine metadata into the key. On first start, create it atomically with a UUID; malformed existing content must fail explicitly rather than silently rotating identity. Suggested v1 shape:

{ "version": 1, "deviceId": "<uuid>" }

Identity precedence:

1. explicit --agentlet-id remains an exact user override;
2. otherwise use the persisted deviceId;
3. create and persist a UUID when the file is absent.

The hello profile reports actual machine metadata separately: hostname(), platform(), and arch() (WSL-specific classification is not required in this phase). New Profiles persist the active UUID-backed agentletId.

Backward compatibility for hostname-bound Profiles uses live resolution without rewriting records:

• exact connected agentletId match wins;
• otherwise treat the stored Profile target as a legacy hostname and match active devices by machine.hostname;
• exactly one match makes the Profile selectable and routes operations to that device’s current UUID;
• zero or multiple matches leaves the Profile unavailable with an actionable recreate/delete message.

This gives ordinary one-device upgrades a smooth transition while deliberately refusing ambiguous pre-existing Windows/WSL hostname collisions. The user may delete/recreate those Profiles as agreed.

Do not store the shared connection token in this identity JSON or an ordinary ~/.agentlet/env: it grants Agentlet plus complete RFS read/write access. Token persistence would require a separate explicit credential-storage/security design; the MVP continues to accept --token / AGENTLET_TOKEN.

[mydmdm]

Implementation complexity assessment

Overall: medium-high, primarily because the supervised local daemon is currently identified synchronously as hostname() before it connects. DaemonSupervisor always passes that value through --agentlet-id, and Huabu/Agenetes call getSupervisedAgentletId() in profile creation, discovery, legacy workload fallback, availability, and spawn diagnostics. A UUID-backed identity therefore cannot be implemented only inside the standalone Agentlet CLI.

Estimated change surfaces:

• Agentlet subtree (medium): atomic ~/.agentlet/device.json UUID lifecycle, corruption/concurrency tests, real hostname/platform/arch hello metadata, explicit override precedence.
• Agenetes subtree (medium-high): supervised daemon identity lifecycle and a centralized exact-ID-then-unique-legacy-hostname resolver; normalize the resolved UUID before spawn/session registry keys so old workload specs do not create mismatched session identities.
• Huabu shared/server (medium): active-device schema/API, connected-profile availability, device-targeted discovery/preview/create, immutable agentletId, removal of supervised-only creation assumptions.
• Web Settings (medium): Connected Devices section, active-device selector, per-device catalogue reload/fencing, unavailable Profile presentation.
• Tests/docs (medium): protocol/identity persistence, duplicate/ambiguous legacy hostname behavior, supervised startup, profile/runtime filtering, device switching, UI and architecture docs.

Expected footprint is roughly 20–30 files across three independently committable ownership areas (Agentlet subtree, Agenetes subtree, Huabu/shared/web/docs). The active-only decision removed the persistence/delete-device half of the work, but UUID migration still makes this larger than a normal Settings feature.

A lower-risk staged delivery is possible: first ship active devices + device-targeted Profiles while retaining hostname identity, then ship UUID identity/legacy resolution separately. Shipping both together is coherent but raises regression risk around supervised startup and resumed external sessions.

[mydmdm]

Placement rule refinement

Most placement must be explicit and Profile-owned. Introduce a live connected-device projection/service and use it as follows:

• Add Agent may initialize its unsaved dropdown to the first device in a deterministic sorted list, but saving persists the selected agentletId.
• Discovery and launch preview always receive the current explicit device selection.
• Runtime execution always uses the Profile/workload device identity; it never falls back to the first connected device.
• Existing records missing placement must use an explicit compatibility/migration rule or fail unavailable; connection arrival order must never reroute a workload because cwd, installed harnesses, credentials, and session state are machine-local.
• Higher-level defaults choose Profiles, not devices. A first selectable Profile fallback remains a separate product rule.

With these rules the public getSupervisedAgentletId() default-placement API can be removed. Supervision still needs private correlation with the child it launched for restart/backoff diagnostics, but that belongs inside DaemonSupervisor (for example an internal managed connection ID/ownership check learned from the identity file or child IPC), not as a globally reusable device default. Legacy supervised fallbacks should be migrated or made explicit rather than replaced with getConnectedDevices()[0].

[mydmdm]

Scope correction: remove getSupervisedAgentletId() repository-wide

UUID identity invalidates the synchronous global supervised-ID concept: before the child starts and reports hello, the Server does not know which UUID it will use. #267 therefore does include repository-wide removal of getSupervisedAgentletId() and every implicit supervised-placement fallback.

This does not require changing the workload snapshot schema or realization model:

• new/current workloads already persist explicit placement and continue unchanged;
• code that reads an explicit workload/Profile agentletId continues unchanged;
• a legacy record that reaches runtime without an explicit target must fail clearly rather than guessing supervised/first-connected placement.

Required cleanup categories:

• Profile create/discovery/preview: require an explicit active device ID;
• legacy helpers such as spec.agentletId ?? getSupervisedAgentletId(): require the explicit value or return an unavailable/corrupt-data error;
• supervised daemon launch: stop injecting hostname through --agentlet-id; let Agentlet load/create its UUID;
• supervisor diagnostics/backoff: track only child-process lifecycle, or learn correlation after connection through private IPC/launch correlation if needed, never expose it as a placement default;
• legacy local Profile import: defer target assignment until an explicit connected device is known or fail migration explicitly—do not invent a hostname target;
• remove the export, tests, and all call sites across Huabu and Agenetes.

The supervised daemon remains special only as a managed process, not as a pre-known device identity or default execution target.

[mydmdm]

Final confirmed implementation plan

The primary invariant is device identity continuity.

Identity ownership and continuity

• Agentlet owns ~/.agentlet/device.json and creates one UUID when the file is absent.
• Default agentletId is that UUID. The same user/home therefore keeps the same identity across daemon, Huabu, OS-session, binary, and worktree restarts/upgrades. Windows and WSL naturally use separate home directories and receive separate UUIDs.
• Creation must be race-safe for concurrent first starts. Existing malformed/unreadable identity data fails explicitly; Agentlet never silently rotates to a new UUID.
• --agentlet-id remains an advanced exact override; continuity under an override is the caller’s responsibility. It does not rewrite the persisted default UUID.
• The hello profile reports actual hostname, platform, and arch separately for display. Hostname is never a primary key.
• The shared connection token remains outside the identity file.

Supervised Agentlet

• Huabu stops passing hostname through --agentlet-id; the supervised child resolves the same Agentlet-owned UUID mechanism.
• Remove getSupervisedAgentletId() and all repository call sites. Supervision owns process lifecycle only: executable, spawn, restart/backoff, shutdown, and diagnostics. It is not a placement default.
• Where private child/connection correlation is genuinely needed, learn it after startup through supervisor-private IPC/correlation rather than exposing a synchronous global ID.

Active devices and Profiles

• Add an owner-only active connected-device projection from Gateway; no offline registry, last-seen persistence, or delete-device API in this version.
• Settings shows Connected Devices first using UUID plus hostname/platform/arch metadata.
• Add Agent initializes its unsaved device dropdown from a deterministic sorted active list, but discovery, preview, and save always use the explicit current selection.
• Profile creation persists the selected UUID-backed agentletId; the target is immutable after creation.
• Runtime selectableProfileIds includes only Profiles whose exact target ID is connected. Unavailable Profiles remain manageable in Settings.
• No runtime operation falls back to the first connected device.

Transition boundary

• Existing hostname-era Windows/WSL Profiles may be deleted and recreated as agreed; this issue does not need to infer which colliding environment owned them.
• Workload snapshot schema/realization is not redesigned. Existing explicit placement continues unchanged. Any call site that depended on getSupervisedAgentletId() must use its existing explicit Profile/workload placement or fail clearly when data is insufficient; it must not invent a replacement target.

Delivery shape

• Separate commits for Agentlet subtree identity/protocol work, Agenetes subtree supervised/default cleanup, and Huabu shared/server/web/docs integration.
• Validation covers identity persistence/corruption/concurrency, supervised UUID startup, active device projection, Profile filtering, per-device discovery/create, unavailable Profile management, and repository-wide absence of getSupervisedAgentletId.

[mydmdm]

Implemented on the existing fix/issue-254 branch and opened #268 against alpha.

The implementation preserves Agentlet device identity with a persistent UUID, removes getSupervisedAgentletId() repository-wide, requires explicit Profile/workload placement, filters runtime Profiles by live connectivity, and adds Connected Devices plus explicit device selection to Agent Settings. The first sorted device is used only as the unsaved create-form initial value.

Validation completed: pnpm format, pnpm lint:fix, pnpm typecheck, and targeted shared/server/web/Agentlet/Agenetes tests.

[mydmdm]

Completed in Alpha by #268 at 9d55adb624d98918df9c2252e80f1a2484666e01, with hostname-era compatibility completed by #271. The current alpha branch contains both deliveries.