feat(desktop): add managed remote Runtime Host onboarding

.github/workflows/release-desktop.yml

@@ -2,6 +2,11 @@ name: Release desktop
 
 on:
   workflow_dispatch:
+    inputs:
+      runtime_host_setup_package:
+        description: Exact published Maka CLI package used for remote Runtime Host setup
+        required: true
+        type: string
 
 permissions:
   contents: write
@@ -26,6 +31,8 @@ jobs:
     runs-on: ${{ matrix.runner }}
     environment: release
     timeout-minutes: 60
+    env:
+      MAKA_RUNTIME_HOST_SETUP_PACKAGE: ${{ inputs.runtime_host_setup_package }}
     defaults:
       run:
         # Windows runners default to pwsh; the release steps are written once,
@@ -49,6 +56,19 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Verify Runtime Host setup package
+        run: |
+          if [[ ! "$MAKA_RUNTIME_HOST_SETUP_PACKAGE" =~ ^maka-agent@[0-9][0-9A-Za-z.+-]*$ ]]; then
+            echo "Runtime Host setup package must be an exact maka-agent version." >&2
+            exit 1
+          fi
+          requested_version="${MAKA_RUNTIME_HOST_SETUP_PACKAGE#maka-agent@}"
+          published_version="$(npm view "$MAKA_RUNTIME_HOST_SETUP_PACKAGE" version)"
+          if [ "$published_version" != "$requested_version" ]; then
+            echo "Published package resolved to ${published_version}, expected ${requested_version}." >&2
+            exit 1
+          fi
+
       - name: Audit production dependencies
         run: npm audit --omit=dev --audit-level=moderate
 

CONTRIBUTING.md

@@ -100,6 +100,16 @@ npm run cli:dev                                  # TUI with the Maka Dev profile
 npm run cli:dev -- run "…"                       # one non-interactive turn
 ```
 
+To exercise Desktop's remote Runtime Host setup with the current worktree, build the same
+self-contained package shape used for releases and opt the development app into that archive:
+
+```sh
+npm run release:cli:pack -- --allow-dirty
+MAKA_RUNTIME_HOST_SETUP_ARCHIVE="$PWD/packages/cli/release/<archive>.tgz" npm run dev
+```
+
+The development app uploads the temporary archive over SSH. Packaged apps ignore this override.
+
 Evaluation commands and contracts live in [`packages/eval`](./packages/eval).
 
 ### Building

CONTRIBUTING.zh-CN.md

@@ -98,6 +98,16 @@ npm --workspace maka-agent exec -- maka          # TUI
 npm --workspace maka-agent exec -- maka run "…"  # 非交互地跑一个 Turn
 ```
 
+如需用当前工作区真实验证 Desktop 的远程 Runtime Host setup，可先构建与正式发布相同形态的
+自包含 package，再让开发版应用显式使用该 archive：
+
+```sh
+npm run release:cli:pack -- --allow-dirty
+MAKA_RUNTIME_HOST_SETUP_ARCHIVE="$PWD/packages/cli/release/<archive>.tgz" npm run dev
+```
+
+开发版应用会通过 SSH 上传这个临时 archive；正式打包应用会忽略该覆盖项。
+
 Eval 的命令与 contract 见 [`packages/eval`](./packages/eval)。
 
 ### 构建

apps/desktop/electron-builder.config.mjs

@@ -1,8 +1,19 @@
+const runtimeHostSetupPackage = process.env.MAKA_RUNTIME_HOST_SETUP_PACKAGE?.trim();
+if (
+  runtimeHostSetupPackage !== undefined &&
+  !/^maka-agent@[0-9][0-9A-Za-z.+-]*$/u.test(runtimeHostSetupPackage)
+) {
+  throw new Error('MAKA_RUNTIME_HOST_SETUP_PACKAGE must name an exact Maka CLI version');
+}
+
 export default {
   appId: 'com.maka.desktop',
   productName: 'Maka',
   artifactName: 'Maka-${version}-mac-${arch}.${ext}',
   asar: true,
+  ...(runtimeHostSetupPackage
+    ? { extraMetadata: { runtimeHostSetupPackage } }
+    : {}),
   directories: {
     output: 'release',
   },

apps/desktop/src/main/__tests__/runtime-host-desktop-manager.test.ts

@@ -1,6 +1,10 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import type { BotIncomingMessage } from '@maka/runtime/bots';
+import {
+  RuntimeHostOperationError,
+  RuntimeHostRequestInterruptedError,
+} from '@maka/runtime-host/client';
 import {
   INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID,
   RUNTIME_HOST_COMPATIBILITY_EPOCH,
@@ -12,6 +16,7 @@ import type {
   DesktopRuntimeHostCandidateStartResult,
 } from '../runtime-host-desktop-candidate.js';
 import {
+  RuntimeHostPairingFinalizationInterruptedError,
   RuntimeHostUpgradeCancelledError,
   startRuntimeHostDesktopManager,
 } from '../runtime-host-desktop-manager.js';
@@ -186,6 +191,167 @@ test('keeps Local and remote Hosts active and routes work by owning Host', async
   await manager.close();
 });
 
+test('replays pairing finalization after an unknown commit and reconnect', async () => {
+  const local = candidateHarness({ hostId: 'host-a' });
+  const remoteHostId = 'a'.repeat(64);
+  const first = candidateHarness({
+    hostId: remoteHostId,
+    finalizeFailures: [
+      new RuntimeHostOperationError(
+        'access.credential.finalize',
+        'commit_outcome_unknown',
+        'finalization outcome is unknown',
+      ),
+    ],
+    disconnectOnFinalizeFailure: true,
+  });
+  const replacement = candidateHarness({ hostId: remoteHostId });
+  const queue = [local.candidate, first.candidate, replacement.candidate];
+  const manager = await startRuntimeHostDesktopManager(
+    {} as DesktopRuntimeHostCandidateStartInput,
+    {
+      startCandidate: async () => ready(queue.shift()!),
+      reconnectBackoff: { minMs: 0, maxMs: 0 },
+    },
+  );
+  await manager.enable(remoteTarget('office'));
+
+  await manager.finalizePairing('office');
+
+  assert.equal(first.finalizeCalls, 1);
+  assert.equal(replacement.finalizeCalls, 1);
+  await manager.close();
+});
+
+for (const dispatch of ['not_dispatched', 'dispatched'] as const) {
+  test(`replays ${dispatch} pairing finalization after connection loss`, async () => {
+    const local = candidateHarness({ hostId: 'host-a' });
+    const remoteHostId = 'a'.repeat(64);
+    const first = candidateHarness({
+      hostId: remoteHostId,
+      finalizeFailures: [
+        new RuntimeHostRequestInterruptedError(
+          'access.credential.finalize',
+          'command',
+          dispatch,
+          'connection_lost',
+        ),
+      ],
+      disconnectOnFinalizeFailure: true,
+    });
+    const replacement = candidateHarness({ hostId: remoteHostId });
+    const queue = [local.candidate, first.candidate, replacement.candidate];
+    const manager = await startRuntimeHostDesktopManager(
+      {} as DesktopRuntimeHostCandidateStartInput,
+      {
+        startCandidate: async () => ready(queue.shift()!),
+        reconnectBackoff: { minMs: 0, maxMs: 0 },
+      },
+    );
+    await manager.enable(remoteTarget('office'));
+
+    await manager.finalizePairing('office');
+
+    assert.equal(first.finalizeCalls, 1);
+    assert.equal(replacement.finalizeCalls, 1);
+    await manager.close();
+  });
+}
+
+test('defers reconnecting pairing finalization when the manager closes', async () => {
+  const local = candidateHarness({ hostId: 'host-a' });
+  const remoteHostId = 'a'.repeat(64);
+  const remote = candidateHarness({
+    hostId: remoteHostId,
+    finalizeFailures: [
+      new RuntimeHostOperationError(
+        'access.credential.finalize',
+        'commit_outcome_unknown',
+        'finalization outcome is unknown',
+      ),
+    ],
+    disconnectOnFinalizeFailure: true,
+  });
+  let reconnectStarted!: () => void;
+  const reconnecting = new Promise<void>((resolve) => {
+    reconnectStarted = resolve;
+  });
+  let starts = 0;
+  const manager = await startRuntimeHostDesktopManager(
+    {} as DesktopRuntimeHostCandidateStartInput,
+    {
+      startCandidate: async (input) => {
+        starts += 1;
+        if (starts === 1) return ready(local.candidate);
+        if (starts === 2) return ready(remote.candidate);
+        reconnectStarted();
+        const signal = input.signal;
+        assert.ok(signal);
+        return await new Promise<DesktopRuntimeHostCandidateStartResult>((_resolve, reject) => {
+          signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+        });
+      },
+      reconnectBackoff: { minMs: 0, maxMs: 0 },
+    },
+  );
+  await manager.enable(remoteTarget('office'));
+
+  const finalization = assert.rejects(
+    () => manager.finalizePairing('office'),
+    RuntimeHostPairingFinalizationInterruptedError,
+  );
+  await reconnecting;
+  await manager.close();
+  await finalization;
+
+  assert.equal(remote.finalizeCalls, 1);
+  assert.equal(starts, 3);
+});
+
+test('defers pairing finalization when reconnect does not complete in time', async () => {
+  const local = candidateHarness({ hostId: 'host-a' });
+  const remoteHostId = 'a'.repeat(64);
+  const remote = candidateHarness({
+    hostId: remoteHostId,
+    finalizeFailures: [
+      new RuntimeHostOperationError(
+        'access.credential.finalize',
+        'commit_outcome_unknown',
+        'finalization outcome is unknown',
+      ),
+    ],
+    disconnectOnFinalizeFailure: true,
+  });
+  let starts = 0;
+  const manager = await startRuntimeHostDesktopManager(
+    {} as DesktopRuntimeHostCandidateStartInput,
+    {
+      startCandidate: async (input) => {
+        starts += 1;
+        if (starts === 1) return ready(local.candidate);
+        if (starts === 2) return ready(remote.candidate);
+        const signal = input.signal;
+        assert.ok(signal);
+        return await new Promise<DesktopRuntimeHostCandidateStartResult>((_resolve, reject) => {
+          signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+        });
+      },
+      reconnectBackoff: { minMs: 0, maxMs: 0 },
+      pairingFinalizationTimeoutMs: 10,
+    },
+  );
+  await manager.enable(remoteTarget('office'));
+
+  await assert.rejects(
+    () => manager.finalizePairing('office'),
+    RuntimeHostPairingFinalizationInterruptedError,
+  );
+
+  assert.equal(remote.finalizeCalls, 1);
+  assert.equal(starts, 3);
+  await manager.close();
+});
+
 test('coalesces concurrent enable requests for one remote profile', async () => {
   const local = candidateHarness({ hostId: 'host-a' });
   const remote = candidateHarness({ hostId: 'host-b', lifecycleMode: 'remote' });
@@ -504,6 +670,8 @@ function candidateHarness(
     activeTasks?: boolean;
     lifecycleMode?: 'ephemeral' | 'service' | 'remote';
     hostId?: string;
+    finalizeFailures?: Error[];
+    disconnectOnFinalizeFailure?: boolean;
   } = {},
 ) {
   let resolveClosed: (() => void) | undefined;
@@ -515,6 +683,7 @@ function candidateHarness(
   const stoppedSessions: string[] = [];
   let lifecycleState: 'ready' | 'unavailable' = 'ready';
   let prepareUpgradeCalls = 0;
+  let finalizeCalls = 0;
   const prepareUpgradeAuthorities: boolean[] = [];
   const candidate = {
     closed,
@@ -536,6 +705,18 @@ function candidateHarness(
         }
         return { kind: 'prepared' as const, pid: 42 };
       },
+      async finalizeAccessCredential() {
+        finalizeCalls += 1;
+        const failure = options.finalizeFailures?.shift();
+        if (failure) {
+          if (options.disconnectOnFinalizeFailure) {
+            lifecycleState = 'unavailable';
+            resolveClosed?.();
+          }
+          throw failure;
+        }
+        return {};
+      },
     },
     botIncoming: {
       async handleBotIncomingMessage() {
@@ -573,6 +754,9 @@ function candidateHarness(
     get prepareUpgradeAuthorities() {
       return prepareUpgradeAuthorities;
     },
+    get finalizeCalls() {
+      return finalizeCalls;
+    },
   };
 }