@platless/axom-cli 0.5.9 → 0.6.36

package/dist/workstation/agentFlow.js

@@ -21,7 +21,7 @@
  *   window could ever open for them;
  * - **control frames** bypass both and are written at once: RPC replies (`agent_opened`, `agent_steered`,
  *   `agent_config_option_set`, `agent_native_sessions`, `agent_native_deleted`, `agent_verified`, `agent_authenticated`,
- *   `agent_installed`, `agent_delegation_renewed`, `agent_provider_task_stopped`, `agent_backfill_done`), levels
+ *   `agent_installed`, `agent_provider_task_stopped`, `agent_backfill_done`), levels
  *   (`agent_session_state`, `agent_runtime_profile`, `agent_provider_task_event`), `agent_session_lost`, `agent_resume_offer`,
  *   `agent_auth_url`/`agent_auth_done`, and the channel's own heartbeat. They are small and rare, an answer the server is waiting
  *   for (a 10–120 s timeout) must not queue behind a session's backlog, and an answer to a user (a permission card's state) must

package/dist/workstation/agentSessions.js

@@ -1,21 +1,13 @@
 import path from 'node:path';
-import { createHash, randomUUID } from 'node:crypto';
-import { AGENT_WIRE_AUTH_URL_VERSION, AGENT_WIRE_HEARTBEAT_INVENTORY_VERSION, AGENT_WIRE_SCOPED_ORIGIN_VERSION, AGENT_WIRE_ORPHAN_OFFER_VERSION, AGENT_WIRE_SESSION_AUTH_METHODS_VERSION, AGENT_WIRE_SESSION_LOST_VERSION, AGENT_WIRE_VERSION, AGENT_WIRE_DELEGATION_MCP_VERSION, AGENT_WIRE_DELEGATION_RENEW_VERSION, AGENT_WIRE_PROVIDER_TASK_VERSION, AGENT_WIRE_REOPEN_REQUEST_VERSION, AGENT_WIRE_RELATION_ACK_VERSION, outboundAgentFrameRejection, outboundFailureReply, } from './protocol/agent.js';
+import { AGENT_WIRE_AUTH_URL_VERSION, AGENT_WIRE_HEARTBEAT_INVENTORY_VERSION, AGENT_WIRE_SCOPED_ORIGIN_VERSION, AGENT_WIRE_ORPHAN_OFFER_VERSION, AGENT_WIRE_SESSION_AUTH_METHODS_VERSION, AGENT_WIRE_SESSION_LOST_VERSION, AGENT_WIRE_VERSION, AGENT_WIRE_PROVIDER_TASK_VERSION, AGENT_WIRE_REOPEN_REQUEST_VERSION, AGENT_WIRE_RELATION_ACK_VERSION, outboundAgentFrameRejection, outboundFailureReply, } from './protocol/agent.js';
 import { listLegacyJournalRefs, readLegacyJournal, removeLegacyJournal } from './journal.js';
 import { SESSION_WINDOW_BYTES, SESSION_WINDOW_EVENTS } from './acp/outbox.js';
 import { SocketGate } from './agentFlow.js';
 import { AGENT_PROBE_TIMEOUT_MS, AgentRefusedSessionError, LOCAL_SESSION_UNMOVABLE } from './acp/acpAgents.js';
-import { AdapterStillInstallingError } from './acp/builds/model.js';
 import { projectFrame } from './acp/processor/projection.js';
 import { reportsActivity, supportsAsyncTaskStop } from './acp/activityReporting.js';
 import { activityIsBusy } from './acp/activityBusy.js';
-import { buildSessionMcpServers } from './acp/delegationMcp.js';
 import { ADAPTER_LOST_REOPEN_ATTEMPTS, plainSwitchBlocker, REOPEN_REQUEST_RETRY_MS, switchBlockers, SWITCH_QUIET_MS } from './acp/switching.js';
-function delegationLeaseId(lease) {
-    return createHash('sha256').update(JSON.stringify([
-        lease.url, lease.headers, lease.bindingId,
-    ])).digest('hex');
-}
 /**
  * 从线上收来的验证预算的绝对上限。
  *
@@ -129,10 +121,6 @@ function openSpecOf(frame) {
         openRequestId: frame.id,
         sessionRef: frame.sessionRef,
         agentKey: frame.agentKey,
-        ...(frame.delegationMcp ? { delegation: {
-                leaseId: delegationLeaseId(frame.delegationMcp),
-                ...(frame.delegationMcp.bindingId ? { bindingId: frame.delegationMcp.bindingId, instanceId: randomUUID() } : {}),
-            } } : {}),
         // `frame.bridge` is the registry agent id now — the wire field keeps its name because Plan A
         // renames nothing (Global Constraint 3); ruling R2 replaced what it *means*.
         agentId: frame.bridge,
@@ -143,7 +131,6 @@ function openSpecOf(frame) {
         args: frame.args ?? [],
         ...(frame.nativeSessionId ? { nativeSessionId: frame.nativeSessionId } : {}),
         ...(frame.requireSessionLoad ? { requireSessionLoad: true } : {}),
-        ...(frame.delegationMcp ? { delegationMcp: frame.delegationMcp } : {}),
         // Retaining a whole adopted history costs memory for the session's lifetime, so it is only
         // kept when this open is the one that will stream it back.
         backfill: frame.backfill === true,
@@ -163,13 +150,6 @@ function exitWords(exit) {
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
-/**
- * The reply text of an open that failed. A managed (delegation) open hides the cause behind one fixed sentence — except when
- * the adapter is still being installed: that one is actionable ("try again shortly") and carries nothing about the lease (15c).
- */
-function openFailureText(frame, err) {
-    return frame.delegationMcp && !(err instanceof AdapterStillInstallingError) ? 'Managed delegation session could not open' : errorMessage(err);
-}
 /**
  * Batch size for `agent_backfill_events`. Kept modest so a session with a long history does not
  * arrive as one giant frame; the last batch of a stream is whatever remains below this size.
@@ -251,6 +231,8 @@ export class AgentSessionManager {
     journalDir;
     tasks;
     sessions = new Map();
+    /** A failed recorded-build respawn keeps this binding even after no LiveSession remains. */
+    retainedRespawnBuilds = new Map();
     /** In-flight opens, keyed by sessionRef, so two racing agent_open frames cannot spawn two agents. */
     opening = new Map();
     /**
@@ -809,38 +791,6 @@ export class AgentSessionManager {
         for (let parked = frameRef !== undefined ? this.switching.get(frameRef) : undefined; parked; parked = this.switching.get(frameRef))
             await parked;
         switch (frame.t) {
-            case 'agent_delegation_renew': {
-                if (this.serverAgentWire < AGENT_WIRE_DELEGATION_RENEW_VERSION)
-                    return;
-                const live = this.liveSession(frame.sessionRef);
-                const now = Date.now();
-                // Delegation's non-secret fields are processor state (Task 19): the checks read it, an accepted renewal is a note.
-                const delegation = live?.session.delegation ?? undefined;
-                if (!live || !delegation || live.closed || !live.session.liveness.agentAlive || live.session.liveness.turnRunning ||
-                    activityIsBusy(live.session.activityRaw) || delegation.refreshPending ||
-                    live.nativeSessionId !== frame.nativeSessionId || delegation.instanceId !== frame.instanceId ||
-                    delegation.bindingId !== frame.bindingId || !frame.bindingId ||
-                    !Number.isSafeInteger(frame.renewalRevision) || frame.renewalRevision < 1 ||
-                    !Number.isSafeInteger(frame.expiresAtEpochMs) || frame.expiresAtEpochMs <= now ||
-                    frame.expiresAtEpochMs > now + 330_000 || frame.renewalRevision < (delegation.renewalRevision ?? 0) ||
-                    frame.expiresAtEpochMs < delegation.expiresAtEpochMs ||
-                    (frame.renewalRevision === delegation.renewalRevision && frame.expiresAtEpochMs !== delegation.expiresAtEpochMs)) {
-                    this.emit({ t: 'agent_delegation_renewed', id: frame.id, ok: false, error: 'The original managed instance cannot renew' });
-                    return;
-                }
-                try {
-                    await live.session.note({ type: 'agent_delegation_renewed', expiresAtEpochMs: frame.expiresAtEpochMs, renewalRevision: frame.renewalRevision });
-                }
-                catch (err) {
-                    this.emit({ t: 'agent_delegation_renewed', id: frame.id, ok: false, error: errorMessage(err) });
-                    return;
-                }
-                const renewed = live.session.delegation ?? delegation;
-                this.emit({ t: 'agent_delegation_renewed', id: frame.id, ok: true,
-                    nativeSessionId: live.nativeSessionId, instanceId: renewed.instanceId, bindingId: renewed.bindingId,
-                    renewalRevision: renewed.renewalRevision, expiresAtEpochMs: renewed.expiresAtEpochMs });
-                return;
-            }
             case 'agent_open': {
                 const admission = this.reserveOpen(frame.id, frame.sessionRef);
                 if (admission === 'rejected')
@@ -1490,20 +1440,6 @@ export class AgentSessionManager {
         return idle.map((live) => live.sessionRef);
     }
     async onOpen(frame) {
-        if (frame.delegationMcp && (this.serverAgentWire < AGENT_WIRE_DELEGATION_MCP_VERSION ||
-            (frame.delegationMcp.bindingId && this.serverAgentWire < AGENT_WIRE_DELEGATION_RENEW_VERSION))) {
-            this.emit({ t: 'agent_opened', id: frame.id, ok: false, error: 'Managed delegation requires a newer server' });
-            return;
-        }
-        if (frame.delegationMcp) {
-            try {
-                buildSessionMcpServers([], frame.delegationMcp);
-            }
-            catch {
-                this.emit({ t: 'agent_opened', id: frame.id, ok: false, error: 'Delegation MCP configuration is unavailable' });
-                return;
-            }
-        }
         // Rotation is server-driven. A busy reconnect resends the original process's outbox.
         let existing = this.liveSession(frame.sessionRef);
         // An open that would spawn the ref's adapter anew after it kept exiting on its own waits out the backoff (no crash loop).
@@ -1532,69 +1468,33 @@ export class AgentSessionManager {
             retireForRefresh = existing;
             existing = undefined;
         }
+        // A keeper session's label records the build that created its native session. Preserve that
+        // binding across an adapter exit: the agent's current pointer may have advanced meanwhile,
+        // but a cached reconnect must retry the recorded package before any explicit switch.
+        const recordedBuildId = retireForRefresh
+            ? this.agents.placementOf?.(retireForRefresh.session)?.buildId
+            : this.retainedRespawnBuilds.get(frame.sessionRef);
         if (existing) {
-            const delegation = existing.session.delegation ?? undefined;
-            if (delegation && !frame.delegationMcp) {
-                this.emit({ t: 'agent_opened', id: frame.id, ok: false, error: 'Managed delegation lease is required' });
+            // Spec §6.3: a session with a switch pending (a persistent intent: another adapter build, or off an older keeper-acp
+            // generation) moves at this open — the only moment its spawn secrets are at hand — when it is strictly idle.
+            if (await this.switchAtOpen(existing, frame))
                 return;
-            }
-            if (frame.delegationMcp && frame.nativeSessionId && frame.nativeSessionId !== existing.nativeSessionId) {
-                this.emit({ t: 'agent_opened', id: frame.id, ok: false, error: 'Managed delegation cannot reload the original session' });
-                return;
-            }
-            const refresh = !!frame.delegationMcp &&
-                (delegation?.leaseId !== delegationLeaseId(frame.delegationMcp) || delegation?.refreshPending === true);
-            if (refresh) {
-                if (!existing.nativeSessionId || (frame.nativeSessionId && frame.nativeSessionId !== existing.nativeSessionId)) {
-                    this.emit({ t: 'agent_opened', id: frame.id, ok: false, error: 'Managed delegation cannot reload the original session' });
-                    return;
-                }
-                if (existing.session.liveness.turnRunning || activityIsBusy(existing.session.activityRaw)) {
-                    if (!delegation?.refreshPending) {
-                        try {
-                            await existing.session.note({ type: 'agent_delegation_refresh_pending' });
-                        }
-                        catch (err) {
-                            this.emit({ t: 'agent_opened', id: frame.id, ok: false, error: errorMessage(err) });
-                            return;
-                        }
-                    }
-                    if (!await this.resumeAndReply(existing, frame, false))
-                        return;
-                    this.replyNoReplayNeeded(frame);
-                    return;
-                }
-                openFrame = { ...frame, nativeSessionId: existing.nativeSessionId, requireSessionLoad: true };
-                retireForRefresh = existing;
-            }
-            else {
-                // Spec §6.3: a session with a switch pending (a persistent intent: another adapter build, or off an older keeper-acp
-                // generation) moves at this open — the only moment its spawn secrets are at hand — when it is strictly idle.
-                if (await this.switchAtOpen(existing, frame))
-                    return;
-                // Reusing a live session: neither the process nor the native session moved.
-                if (!await this.resumeAndReply(existing, frame, false))
-                    return;
-                // The session already exists, so any history it has was already streamed under whichever
-                // open first established it (or never will be, if that open didn't ask for it) — replaying it
-                // again here would duplicate what the platform already holds. But if THIS frame asked for
-                // backfill, the server is waiting on exactly one `agent_backfill_done` for THIS open's id:
-                // silence is not "no", it is a wait that never resolves. Answer it without replaying.
-                this.replyNoReplayNeeded(frame);
+            // Reusing a live session: neither the process nor the native session moved.
+            if (!await this.resumeAndReply(existing, frame, false))
                 return;
-            }
+            // The session already exists, so any history it has was already streamed under whichever
+            // open first established it (or never will be, if that open didn't ask for it) — replaying it
+            // again here would duplicate what the platform already holds. But if THIS frame asked for
+            // backfill, the server is waiting on exactly one `agent_backfill_done` for THIS open's id:
+            // silence is not "no", it is a wait that never resolves. Answer it without replaying.
+            this.replyNoReplayNeeded(frame);
+            return;
         }
         const inFlight = this.opening.get(frame.sessionRef);
         if (inFlight) {
             // Piggyback on the attempt already running, and report its real failure — not a generic one.
             const { live, error, agentRefused } = await inFlight;
             if (live) {
-                const delegation = live.session.delegation ?? undefined;
-                if (!!frame.delegationMcp !== !!delegation ||
-                    (frame.delegationMcp && delegation?.leaseId !== delegationLeaseId(frame.delegationMcp))) {
-                    this.emit({ t: 'agent_opened', id: frame.id, ok: false, error: 'Managed delegation lease does not match the live session' });
-                    return;
-                }
                 // Piggybacking on the attempt already running: a non-null `live` means that attempt was a
                 // real open (`session/load` or `session/new`), which this frame is reporting secondhand.
                 if (!await this.resumeAndReply(live, frame, true))
@@ -1623,9 +1523,9 @@ export class AgentSessionManager {
         const attempt = (async () => {
             if (retireForRefresh)
                 await this.retire(retireForRefresh, 'keep');
-            return this.openSession(openFrame);
+            return this.openSession(openFrame, recordedBuildId);
         })()
-            .catch((err) => ({ live: null, error: openFailureText(openFrame, err) }))
+            .catch((err) => ({ live: null, error: errorMessage(err) }))
             .finally(() => releaseHold?.());
         this.opening.set(frame.sessionRef, attempt);
         let outcome;
@@ -1648,6 +1548,7 @@ export class AgentSessionManager {
         // tombstone without anything ever closing it. Nothing but microtasks separates `attempt`
         // resolving from the finally, and microtasks always drain before the next inbound frame.
         if (outcome.live) {
+            this.retainedRespawnBuilds.delete(frame.sessionRef);
             // openSession returned successfully, having just done session/load or session/new.
             if (!await this.resumeAndReply(outcome.live, frame, true))
                 return;
@@ -1658,6 +1559,8 @@ export class AgentSessionManager {
                 await this.streamBackfill(frame.id, outcome.live.session);
         }
         else {
+            if (recordedBuildId !== undefined)
+                this.retainedRespawnBuilds.set(frame.sessionRef, recordedBuildId);
             this.emit({
                 t: 'agent_opened', id: frame.id, ok: false, error: outcome.error,
                 // Only when the agent is the one that said no, and then it is the one refusal that can be
@@ -1689,7 +1592,7 @@ export class AgentSessionManager {
      */
     async switchAtOpen(live, frame) {
         const agents = this.agents;
-        if (!agents.switchSession || !agents.pendingSwitchFor || frame.delegationMcp)
+        if (!agents.switchSession || !agents.pendingSwitchFor)
             return false;
         // A switch spawns an adapter: new work, refused while the workstation drains (spec §8.2).
         if (this.tasks && !this.tasks.accepting)
@@ -1847,7 +1750,7 @@ export class AgentSessionManager {
      * "Move idle sessions" (Task 25's `agent_switch_idle`, spec §6.4): every held session of `agentId` that runs another build than
      * `toBuild` (else the agent's current build) gets a persistent intent to move there; those already strictly idle get their
      * `agent_reopen_request` at once, the others when they become idle. A session that can never be moved this way
-     * ({@link unmovableWhy}: a local-fallback session, a managed delegation, no native session, a target that already refused it) gets
+     * ({@link unmovableWhy}: a local-fallback session, no native session, a target that already refused it) gets
      * no intent — it would only be asked to reopen again and again — and is listed in `unmovable` with the reason. A `toBuild` that is
      * not installed for the agent is refused (throws). Returns the refs registered, the ones a request went out for, and the unmovable.
      */
@@ -1889,7 +1792,7 @@ export class AgentSessionManager {
     }
     /**
      * Why `live` can never be moved to `target` by a switch (spec §6.3 "当前限制"), or `undefined`: a session keeper-acp does not host
-     * (the local fallback), a managed delegation, a session with no native session to load, or one a switch to the same build already
+     * (the local fallback), a session with no native session to load, or one a switch to the same build already
      * found unmovable. `plain` is what the scan card and the result frame say (Task 25); `detail` is the switch's own words, for the
      * log, when there are any.
      */
@@ -1897,8 +1800,6 @@ export class AgentSessionManager {
         const placement = this.agents.placementOf?.call(this.agents, live.session);
         if (!placement?.keeper)
             return { plain: LOCAL_SESSION_UNMOVABLE };
-        if (live.session.delegation)
-            return { plain: 'it is a delegated session, which can\'t be moved to another build yet' };
         if (!live.nativeSessionId)
             return { plain: 'it has no saved conversation the new build could reload' };
         const refused = this.agents.unmovableFor?.call(this.agents, live.sessionRef);
@@ -2128,7 +2029,6 @@ export class AgentSessionManager {
             this.emit({ t: 'agent_opened', id: frame.id, ok: false, error: 'session was closed while opening' });
             return false;
         }
-        const delegation = live.session.delegation ?? undefined;
         const activityRaw = live.session.activityRaw;
         this.emit({
             t: 'agent_opened',
@@ -2140,13 +2040,6 @@ export class AgentSessionManager {
             // Emitted only when true, the same `supportsSteering` convention as below: absent is the
             // field's only "no", and it is also what an older peer sends.
             ...(reloaded ? { reloaded: true } : {}),
-            // Delegation's non-secret fields, from processor state (Task 19: `agent_opened` is assembled from state).
-            ...(delegation ? { delegationExpiresAtEpochMs: delegation.expiresAtEpochMs } : {}),
-            ...(delegation?.refreshPending ? { delegationRefreshPending: true } : {}),
-            ...(this.serverAgentWire >= AGENT_WIRE_DELEGATION_RENEW_VERSION && delegation?.instanceId ? {
-                delegationInstanceId: delegation.instanceId, delegationBindingId: delegation.bindingId,
-                delegationRenewalRevision: delegation.renewalRevision,
-            } : {}),
             // The server learns this here and nowhere else. It used to be published only on the roster in
             // the `agent_hello` handshake, which is a snapshot taken *before* any agent was connected to —
             // and the capability can only be observed on a live `initialize`, whose record
@@ -2223,7 +2116,7 @@ export class AgentSessionManager {
         });
         return true;
     }
-    async openSession(frame) {
+    async openSession(frame, recordedBuildId) {
         // A previous incarnation of this ref may still be closing: its adapter stopped and its transport session (raw, outbox) kept or
         // released — the new spawn goes under the same key (see {@link retiring}). This is the first statement on purpose — before the
         // agent spawns, before anything touches the transport. The one-time legacy journal migration lands before any open too.
@@ -2272,13 +2165,14 @@ export class AgentSessionManager {
             });
         };
         try {
-            const result = await this.agents.open({ ...openSpecOf(frame), onInstallOutcome, seqBase: () => resumeFrom });
+            const result = await this.agents.open({
+                ...openSpecOf(frame),
+                ...(recordedBuildId !== undefined ? { recordedBuildId } : {}),
+                onInstallOutcome,
+                seqBase: () => resumeFrom,
+            });
             session = result.session;
             nativeSessionId = result.nativeSessionId;
-            if (frame.delegationMcp && !nativeSessionId) {
-                await session.close();
-                return { live: null, error: 'Managed delegation requires a native session ID' };
-            }
         }
         catch (err) {
             await reportFailedInstall();
@@ -2288,7 +2182,7 @@ export class AgentSessionManager {
             // on `session/new` arrives as; see {@link OpenOutcome.agentRefused}.
             return {
                 live: null,
-                error: openFailureText(frame, err),
+                error: errorMessage(err),
                 // The code comes off the marker, not off `errorMessage(err)` above: the wrapper captured it
                 // from the original rejection at the moment that object still existed.
                 ...(err instanceof AgentRefusedSessionError
@@ -2843,6 +2737,7 @@ export class AgentSessionManager {
         void this.agents.cancelSwitch?.({ sessionRef }).catch(() => false);
         this.reopenRequests.delete(sessionRef);
         this.adapterCrashes.delete(sessionRef);
+        this.retainedRespawnBuilds.delete(sessionRef);
         // Closing a ref that is still spawning: nothing to close yet, so tombstone it — openSession
         // closes the session (and destroys its journal) the moment the bridge hands it over.
         //

package/dist/workstation/channels/management.js

@@ -1,16 +1,22 @@
 import { deriveSessionKey, randomBytes } from '../crypto.js';
 import { connectEncryptedChannel } from '../connection/encryptedChannel.js';
 import { CLIENT_PACKAGE_NAME, CLIENT_VERSION } from '../version.js';
-import { decodeManagementFrame, encodeManagementFrame, MANAGEMENT_WIRE_DRAINING_VERSION, MANAGEMENT_WIRE_GPU_VERSION, MANAGEMENT_WIRE_KEEPERS_VERSION, MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION, MANAGEMENT_WIRE_METRICS_VERSION, MANAGEMENT_WIRE_MIN_VERSION, MANAGEMENT_WIRE_PRESSURE_VERSION, MANAGEMENT_WIRE_VERSION, } from '../protocol/management.js';
+import { decodeManagementFrame, encodeManagementFrame, MANAGEMENT_WIRE_DRAINING_VERSION, MANAGEMENT_WIRE_GPU_VERSION, MANAGEMENT_WIRE_KEEPERS_VERSION, MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION, MANAGEMENT_WIRE_METRICS_VERSION, MANAGEMENT_WIRE_MIN_VERSION, MANAGEMENT_WIRE_PRESSURE_VERSION, MANAGEMENT_WIRE_VERSION, ManagementFrameAdmission, } from '../protocol/management.js';
 import { bridgesForWire, helloRoster } from '../protocol/common.js';
 import { AGENT_WIRE_MIN_VERSION, AGENT_WIRE_VERSION } from '../protocol/agent.js';
 import { osInfo } from '../osinfo.js';
 import { workstationChannelUrl } from './url.js';
+import { DesktopCapabilityReporter } from '../desktopControl/capabilities.js';
 const protocols = {
     MANAGEMENT: { min: MANAGEMENT_WIRE_MIN_VERSION, max: MANAGEMENT_WIRE_VERSION },
     // COMPUTER v5: durable exec frames (exec_started/attach/status/ack, offsets on exec_output; spec §4.3).
-    COMPUTER: { min: 1, max: 5 }, AGENT: { min: AGENT_WIRE_MIN_VERSION, max: AGENT_WIRE_VERSION },
+    // COMPUTER v6: this client refuses credential storage to the agent file tools (files/credentials.ts); the server sends
+    // file frames only to v6 clients.
+    COMPUTER: { min: 1, max: 6 }, AGENT: { min: AGENT_WIRE_MIN_VERSION, max: AGENT_WIRE_VERSION },
 };
+function toolchainField(toolchain) {
+    return toolchain ? { toolchain: { python: toolchain.python, node: toolchain.node } } : {};
+}
 /** Exported so tests can assert the wire frame's `clientPackage` without opening a socket. */
 export function buildHelloFrame(options, clientNonce) {
     return {
@@ -177,9 +183,28 @@ export class ManagementChannel {
     serverManagementWire;
     /** The open channel of the current connection, for frames this client sends unprompted ({@link pushRoster}). */
     channel;
+    desktopReporter;
+    connectionAttempt = 0;
+    generation;
     constructor(options) {
         this.options = options;
     }
+    refreshDesktopCapabilities(generation) {
+        if (generation === undefined || generation === this.generation)
+            this.desktopReporter?.refresh();
+    }
+    /** T10 reports only on its authenticated current management socket. */
+    sendDesktopState(generation, frame) {
+        if (generation !== this.generation || (this.serverManagementWire ?? 0) < 9 || this.channel?.state !== 'OPEN')
+            return false;
+        try {
+            this.channel.send(frame);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Tell the server about a roster that changed without a scan asking (adapter builds moved by Axom,
      * spec §6.1): the same `external_agents_scan_result` frame a scan answers with, under a client-made
@@ -199,14 +224,22 @@ export class ManagementChannel {
         }
     }
     async connect(signal) {
+        const attempt = ++this.connectionAttempt;
+        this.desktopReporter?.dispose();
+        this.desktopReporter = undefined;
+        this.generation = undefined;
+        this.channel = undefined;
         this.serverManagementWire = undefined;
         const nonce = randomBytes(16);
         let initialHeartbeat = true;
+        const admission = new ManagementFrameAdmission(() => attempt === this.connectionAttempt && !signal?.aborted);
         const channel = await connectEncryptedChannel({
             url: workstationChannelUrl(this.options.server, 'management', this.options.allowInsecureWs),
             signal,
             encode: encodeManagementFrame,
             decode: decodeManagementFrame,
+            decodeBytes: decodeManagementFrame,
+            admitFrame: frame => admission.admit(frame),
             heartbeat: (seq, sentAtEpochMs) => this.heartbeat(seq, sentAtEpochMs),
             initialFrame: () => {
                 initialHeartbeat = false;
@@ -226,15 +259,40 @@ export class ManagementChannel {
         if (initialHeartbeat)
             throw new Error('Management proof heartbeat was not sent');
         const ready = await this.nextReady(channel);
+        if (attempt !== this.connectionAttempt || channel.state !== 'OPEN') {
+            channel.close();
+            throw new Error('Management connection superseded');
+        }
         this.serverManagementWire = ready.protocols.MANAGEMENT;
+        this.generation = ready.generation;
+        this.channel = channel;
+        const reporter = new DesktopCapabilityReporter({ selectedWire: this.serverManagementWire, generation: ready.generation,
+            provider: this.options.desktopProvider, send: report => {
+                if (attempt === this.connectionAttempt && this.channel === channel && channel.state === 'OPEN')
+                    channel.send({ t: 'workstation_capabilities', ...report });
+            } });
+        this.desktopReporter = reporter;
+        // Starts before the existing awaited update hook; heartbeat and reporting never await discovery.
+        reporter.refresh();
+        const retire = () => {
+            admission.dispose();
+            reporter.dispose();
+            try {
+                this.options.onClosed?.(ready.generation);
+            }
+            catch { /* transport retirement must complete */ }
+            if (this.channel === channel) {
+                this.channel = undefined;
+                this.generation = undefined;
+                this.desktopReporter = undefined;
+                this.serverManagementWire = undefined;
+            }
+        };
+        void channel.closed.then(retire, retire);
         // A readiness record is evidence from this encrypted, proof-of-key management generation — it
         // is never driven by the local browser/device-authorization flow.
-        await this.options.onReady?.({ generation: ready.generation, release: ready.release });
+        await this.options.onReady?.({ generation: ready.generation, selectedWire: ready.protocols.MANAGEMENT, release: ready.release });
         const pending = new Map();
-        this.channel = channel;
-        void channel.closed.then(() => { if (this.channel === channel)
-            this.channel = undefined; }, () => { if (this.channel === channel)
-            this.channel = undefined; });
         void this.routeMessages(channel, pending);
         return {
             generation: ready.generation,
@@ -255,6 +313,11 @@ export class ManagementChannel {
         };
     }
     async heartbeat(seq, sentAtEpochMs) {
+        const selectedWire = this.serverManagementWire;
+        // Availability may change without restarting the CLI (Desktop sharing is process-owned).
+        // Discovery stays bounded and never delays the heartbeat or creates a capture session.
+        this.desktopReporter?.refresh();
+        const revision = this.desktopReporter?.revision;
         const snapshot = await this.options.snapshot();
         return {
             t: 'heartbeat', seq, sentAtEpochMs, clientVersion: CLIENT_VERSION,
@@ -266,11 +329,13 @@ export class ManagementChannel {
             },
             activeShellTasks: snapshot.activeShellTasks, activeAgentTasks: snapshot.activeAgentTasks,
             protocols, os: osInfo(),
-            ...(this.options.metrics && (this.serverManagementWire ?? 0) >= MANAGEMENT_WIRE_METRICS_VERSION
-                ? { metrics: metricsForManagementWire(this.options.metrics(), this.serverManagementWire) }
+            ...toolchainField(this.options.toolchain?.() ?? null),
+            ...(this.options.metrics && (selectedWire ?? 0) >= MANAGEMENT_WIRE_METRICS_VERSION
+                ? { metrics: metricsForManagementWire(this.options.metrics(), selectedWire) }
                 : {}),
-            ...(snapshot.update ? { update: statusForManagementWire(snapshot.update, this.serverManagementWire) } : {}),
-            ...await keepersForManagementWire(this.options.keepers, this.serverManagementWire, this.options.keepersCapMs),
+            ...(snapshot.update ? { update: statusForManagementWire(snapshot.update, selectedWire) } : {}),
+            ...await keepersForManagementWire(this.options.keepers, selectedWire, this.options.keepersCapMs),
+            ...((selectedWire ?? 0) >= 9 && revision !== undefined ? { capabilitiesRevision: revision } : {}),
         };
     }
     async nextReady(channel) {
@@ -282,6 +347,25 @@ export class ManagementChannel {
     async routeMessages(channel, pending) {
         try {
             for await (const frame of channel.messages) {
+                if (channel !== this.channel)
+                    break;
+                if (frame.t === 'workstation_capabilities_request') {
+                    if ((this.serverManagementWire ?? 0) >= 9 && frame.generation === this.generation)
+                        this.desktopReporter?.refresh();
+                    continue;
+                }
+                if ((frame.t === 'desktop_background' || frame.t === 'desktop_lobby' || frame.t === 'desktop_prepare' || frame.t === 'desktop_cancel') && (this.serverManagementWire ?? 0) >= 9) {
+                    if (frame.t !== 'desktop_cancel' && frame.deviceGeneration !== this.generation)
+                        continue;
+                    if (this.options.onDesktopCommand && this.generation) {
+                        // Capture the authenticated generation now: later callbacks cannot borrow a reconnect.
+                        try {
+                            void this.options.onDesktopCommand(frame, this.generation).catch(() => undefined);
+                        }
+                        catch { /* bounded desktop admission failure */ }
+                    }
+                    continue;
+                }
                 if (frame.t === 'channel_ticket') {
                     const queue = pending.get(frame.channel);
                     queue?.shift()?.resolve(frame.ticket);

package/dist/workstation/channels/url.js

@@ -11,7 +11,7 @@ function ipv4Octets(hostname) {
     return octets.every((octet) => octet <= 255) ? octets : null;
 }
 /** Deliberately classifies literal names/IPs only: DNS answers must never downgrade transport security. */
-function isTrustedPlaintextHost(rawHostname) {
+export function isTrustedPlaintextHost(rawHostname) {
     const hostname = rawHostname.toLowerCase().replace(/^\[|\]$/g, '');
     if (TRUSTED_PLAINTEXT_NAMES.has(hostname) || hostname.endsWith('.localhost'))
         return true;

package/dist/workstation/config.js

@@ -1,20 +1,28 @@
+import { loadManagedCliInstallSync, npmExecutionContext } from './managedInstall.js';
 import { resolveBrowserBinding } from './desktop/binding.js';
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import yaml from 'js-yaml';
+import { z } from 'zod';
+const localPath = z.string().refine(p => path.isAbsolute(p) && !p.includes('\0'));
+const nativeConfig = z.strictObject({ kind: z.literal('linux-native'), helperPath: localPath, runtimeDir: localPath });
 export function updateServiceContext(configDir = clientDir(), overrides = {}) {
     // config.ts lives in dist/workstation/ after packaging, so two levels up is the installed package root.
     const packageRoot = overrides.packageRoot ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-    const nodePath = overrides.nodePath ?? process.execPath;
+    const managed = loadManagedCliInstallSync(packageRoot);
+    const nodePath = managed?.nodePath ?? overrides.nodePath ?? process.execPath;
+    const npmPrefix = managed?.prefix ?? overrides.npmPrefix ?? process.env.AXOM_WORKSTATION_NPM_PREFIX ?? path.resolve(packageRoot, '../../../..');
     return {
         configDir,
+        ...(managed ? { managed } : {}),
+        env: npmExecutionContext({ prefix: npmPrefix, nodePath }, process.env),
         platform: overrides.platform ?? (process.platform === 'darwin' ? 'darwin' : 'linux'),
         nodePath,
-        npmPath: overrides.npmPath ?? process.env.AXOM_WORKSTATION_NPM_PATH ?? path.join(path.dirname(nodePath), 'npm'),
+        npmPath: managed?.npmPath ?? overrides.npmPath ?? process.env.AXOM_WORKSTATION_NPM_PATH ?? path.join(path.dirname(nodePath), 'npm'),
         // packageRoot is under lib/node_modules/@platless; climb to npm's global prefix.
-        npmPrefix: overrides.npmPrefix ?? process.env.AXOM_WORKSTATION_NPM_PREFIX ?? path.resolve(packageRoot, '../../../..'),
+        npmPrefix,
         packageRoot,
     };
 }
@@ -35,7 +43,11 @@ export async function loadClientConfig(dir) {
         throw new Error('Invalid workstation config: server and workstationId are required; run axom auth again');
     }
     const browserBinding = parsed.browserBinding ? resolveBrowserBinding(parsed.browserBinding, {}) : undefined;
-    return { ...(browserBinding ? { browserBinding } : {}), server: parsed.server, workstationId: parsed.workstationId, ...(Array.isArray(parsed.workspaces) ? { workspaces: parsed.workspaces } : {}) };
+    const desktopProvider = parsed.desktopProvider ? nativeConfig.parse({ ...parsed.desktopProvider,
+        helperPath: parsed.desktopProvider.helperPath === '/usr/local/bin/axom-desktop-helper' ? '/usr/local/bin/axom-desktop-keeper' : parsed.desktopProvider.helperPath,
+    }) : process.env.AXOM_DESKTOP_NATIVE_PROVIDER === '1' ?
+        nativeConfig.parse({ kind: 'linux-native', helperPath: '/usr/local/bin/axom-desktop-keeper', runtimeDir: '/run/axom-desktop' }) : undefined;
+    return { ...(browserBinding ? { browserBinding } : {}), ...(desktopProvider ? { desktopProvider } : {}), server: parsed.server, workstationId: parsed.workstationId, ...(typeof parsed.ownerUserId === 'string' && parsed.ownerUserId ? { ownerUserId: parsed.ownerUserId } : {}), ...(Array.isArray(parsed.workspaces) ? { workspaces: parsed.workspaces } : {}) };
 }
 export async function writeKeys(dir, clientKeyB64, serverPubB64) {
     await fs.mkdir(dir, { recursive: true });

package/dist/workstation/connection/encryptedChannel.js

@@ -279,7 +279,10 @@ export function connectEncryptedChannel(options) {
             if (!isBinary)
                 return;
             try {
-                const frame = options.decode(crypto.open(sessionKey, bytes).toString());
+                const plaintext = crypto.open(sessionKey, bytes);
+                const frame = options.decodeBytes ? options.decodeBytes(plaintext) : options.decode(plaintext.toString());
+                if (options.admitFrame && !options.admitFrame(frame))
+                    return;
                 const acknowledged = [...outstandingAcks].some((sequence) => options.isHeartbeatAck(frame, sequence));
                 // A correctly encrypted and decoded frame proves the peer is still reachable. Heartbeat
                 // acknowledgements are one such frame, but computer streaming/agent events may legitimately