@agentknight/client 0.9.53 → 0.9.56

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,358 +1,365 @@
1
- # AgentKnight
2
-
3
- AgentKnight PC Agent connects local coding-agent sessions to an AgentKnight
4
- Relay Server through Copilot, PI SDK, or ACP adapters.
5
-
6
- ## Embed
7
-
8
- Use `@agentknight/sdk` to embed the PC Agent runtime in a Node.js application
9
- without running the CLI or its local management service.
10
- Call `initialize` with an explicit absolute `dataDirectory` and the connection,
11
- identity and logging options, then manage the returned runtime with `start` and
12
- `stop`. The SDK does not select `~/.ak` or read the CLI configuration for you.
13
- Do not share a data directory between running instances.
14
- After starting, `disconnectRelay()` pauses remote access while preserving local
15
- providers and credentials. Use `reconnectRelay()` to resume and `getStatus()`
16
- to verify recovery.
17
-
18
- For renewable credentials, implement the [authorization provider](../../shared/sdk/src/relay-authorization.ts).
19
- The host owns sign-in and cleanup; cloud image storage is not supported in this mode.
20
-
21
- Azure Blob images are opt-in on the local PC page when the connected Relay offers
22
- storage. See the [image API](../../docs/remote-sessions/session-image-api.md) for
23
- client behavior and the non-E2EE storage boundary.
24
-
25
- The CLI depends on the SDK; both use the same release version. The SDK can be
26
- published independently through the [npm release workflow](../../.github/workflows/agentknight-npm-publish.yml).
27
- See the [SDK entry point](../../shared/sdk/src/index.ts) for the public API.
28
- For configuration and onboarding without loading the runtime, use
29
- [`@agentknight/sdk/configuration`](../../shared/sdk/src/configuration.ts).
30
-
31
- ## Run
32
-
33
- Use the Node.js version required by [package.json](package.json) and authenticate
34
- the coding agents you want to use.
35
-
36
- ```powershell
37
- npx @agentknight/client --env C:\path\to\agentknight.env
38
- ```
39
-
40
- Or install it globally:
41
-
42
- ```powershell
43
- npm install --global @agentknight/client
44
- agentknight --env C:\path\to\agentknight.env
45
- ```
46
-
47
- To switch from the unscoped `agentknight` package, stop the Agent and its service,
48
- run `npm uninstall --global agentknight`, then install `@agentknight/client` as
49
- above. The command remains `agentknight`; keep the existing data home and
50
- configuration. Re-register services that pin the old package path before
51
- restarting. Updating the old package does not migrate it to the new name.
52
-
53
- `AGENTKNIGHT_HOME` selects the PC data home, defaulting to `~/.ak`. Without
54
- `--env`, AgentKnight reads `<home>/agentknight.env`, with process settings taking
55
- precedence. With `--env`, the selected file is authoritative for PC settings:
56
- missing settings use defaults or fail validation, rather than inheriting old
57
- Relay credentials, machine names or data paths. OS and external provider
58
- environment variables are retained; explicitly supplied file values override them.
59
- Set custom `AGENTKNIGHT_HOME` in that file as well so restarts use the same home.
60
-
61
- `AGENTKNIGHT_PI_DIRECTORY` is a deprecated input alias for PI's native
62
- `PI_CODING_AGENT_DIR`; conflicting values are rejected. Use the native name
63
- for new configuration. An empty value selects PI's native default.
64
-
65
- The first normal startup can import legacy working-directory `.env` files or
66
- the old macOS service configuration into `~/.ak/agentknight.env`. Conflicting
67
- legacy values require selecting or reconciling the correct file; no source
68
- silently wins. A selected custom home does not import another home's settings.
69
- Status, stop and upgrade commands do not import or migrate configuration.
70
-
71
- Identity, pairing keys and saved state belong only to the selected home.
72
- Retired data directories and HOME aliases are ignored. Existing identities
73
- are preserved; deleting the home requires pairing again. Conflicting identity
74
- files require manual resolution, not an automatic reset.
75
-
76
- Diagnostic JSONL files are under `<data-home>/logs/<version>/`. Existing
77
- unversioned logs remain historical files; they are not assigned an invented
78
- version. The local pairing page shows the running version, last successful
79
- upgrade time, configuration location, and Relay URL.
80
-
81
- ## Status and upgrades
82
-
83
- ```powershell
84
- agentknight --version
85
- agentknight status
86
- agentknight status --json
87
- agentknight stop
88
- agentknight upgrade --check
89
- agentknight upgrade
90
- ```
91
-
92
- `stop` preserves data and refuses busy agents. External service managers may
93
- restart it. See `agentknight --help` for command options.
94
-
95
- `upgrade` uses the latest published version; `upgrade <version>` selects an exact
96
- newer version. Self-upgrade requires a global npm installation, not an `npx`
97
- cache or source checkout. Install a release containing this command through npm
98
- before using it for subsequent upgrades.
99
-
100
- Package resolution and installation try the official npm registry first, then
101
- the Tencent npm mirror for network failures. Existing npm/proxy configuration
102
- is respected without changing global settings. Archives and dependencies for
103
- both the target and rollback are prepared before stopping the running Agent.
104
-
105
- An independent worker waits for idle and performs the switch. Windows scheduled
106
- tasks and the supplied macOS LaunchAgent retain their existing configuration;
107
- foreground instances restart in the background. Persist their configuration and
108
- provider credentials in the environment file before upgrading; shell-only values
109
- that cannot be restored cause the upgrade to be refused. A stopped installation
110
- remains stopped. User-level installations do not require elevation; protected npm
111
- prefixes or service definitions need their existing permissions.
112
-
113
- The command reports the handoff, not successful completion. Use `status` to see
114
- the persistent result if the initiating connection closes. An Agent that remains
115
- busy is left running. Startup failure triggers an offline rollback; readiness
116
- requires the new instance's registration and initial synchronization, not merely
117
- an HTTP health response. Upgrading briefly interrupts the PC connection and does
118
- not migrate an active model turn between processes.
119
-
120
- Successful upgrades remove their temporary installation materials. Failed jobs
121
- retain their diagnostic files under `<data-home>/upgrades`; the last successful
122
- upgrade timestamp changes only after recovery is confirmed.
123
-
124
- ## Configuration
125
-
126
- Create the environment file from the [PC Agent example](.env.example), set
127
- `RELAY_URL` and sign in from the local page. Account-system discovery never falls
128
- back on failure; select an explicit mode for older Relays without discovery.
129
-
130
- AAD uses the OS authentication broker without password, API-key, browser or
131
- device-code fallback. Before headless startup, run `agentknight login` with the
132
- service's configuration and OS account.
133
-
134
- `RELAY_URL` is used for HTTP APIs and Socket.IO, so an `https://` URL enables
135
- HTTPS and WSS for the entire PC Agent connection. `AGENTKNIGHT_MACHINE_NAME`
136
- controls the PC name shown to mobile clients. The selection and pairing webpage
137
- listens only on loopback; `PAIRING_PAGE_PORT` changes its local port.
138
-
139
- On the local page, expand a working-directory folder and select a session to
140
- browse its conversation history. Viewing is read-only and does not change
141
- mobile sync selection or create a separate archive.
142
-
143
- The local pages remember your language choice. Phone authorization requests open
144
- a verification dialog automatically. Compare its code with the phone before
145
- allowing access; dismissing the dialog leaves the request pending for later review.
146
-
147
- Use **重连** on the local page to retry with saved credentials without
148
- restarting coding agents. Recognized authorization-service outages retry
149
- automatically; other server-initiated disconnects require user action.
150
- **断开连接** pauses remote access until **重连** or a PC Client restart,
151
- without stopping local agents or clearing saved login.
152
-
153
- Repository checkouts also include Windows Scheduled Task and macOS LaunchAgent
154
- installers under `clients/pc-agent/scripts`. Services use the same canonical
155
- configuration as the CLI, not a copied environment file. Service support files
156
- and output logs live under `<home>/service` and `<home>/logs/service`; OS task and
157
- LaunchAgent registrations stay in their required system locations. Reinstall the
158
- service to update an older registration after stopping it and migrating its
159
- configuration. Explicit external environment files remain referenced in place.
160
- Uninstalling the service preserves configuration, identity and logs.
161
- Installers resolve the data home through `agentknight status --json`, so they
162
- must be used with the matching installed CLI. They pin the installation working
163
- directory to preserve relative paths; reinstall after changing the configured
164
- home or moving that directory. A missing canonical configuration must be
165
- created or migrated before installing the default service. Both default and
166
- explicit-file installations refuse a pending legacy-home migration; stop the old
167
- service and complete a normal startup with the selected configuration first.
168
-
169
- Re-register older Windows tasks
170
- that use `-CaCertPath` with `agentknight-service.ps1 install -EnvFile <path>`
171
- (and `-TaskName <name>` for a custom task), omitting `-CaCertPath`.
172
-
173
- ### Microsoft sign-in
174
-
175
- For an MSA Relay, choose personal-account sign-in on the local page.
176
- Complete Microsoft sign-in and any application consent in a browser on that same
177
- computer. The browser returns to AgentKnight automatically; there is no device
178
- code to copy or enter. The Relay must support browser callback sign-in, have
179
- Microsoft sign-in enabled, and admit your account through its administrator.
180
- An older Relay must be upgraded rather than silently switching to manual codes.
181
-
182
- After approval, AgentKnight saves the machine-bound Relay credential in the
183
- current OS user's credential store, confirms it with Relay, and connects. The
184
- normal local page provides Android pairing: scan the QR code, match the verification
185
- code, and approve on the PC. Manage and revoke individual clients on that page.
186
- Upgrade Relay and Android before the PC; existing phones must pair again when
187
- approval is first enabled.
188
- See the [approval compatibility policy](../../docs/remote-sessions/protocol-compatibility-plan.md#手机连接审批与撤销)
189
- for migration and revocation limits. Microsoft sign-in does not replace the
190
- PC–phone encryption key or authenticate GitHub Copilot.
191
-
192
- Microsoft sign-in supports Windows Credential Manager and macOS Keychain only.
193
- Other operating systems are not supported for Microsoft sign-in; existing token
194
- authentication is unchanged. There is no plaintext or nonpersistent-keyring fallback.
195
- Run the service as the same OS user who signed in. Restarts reuse the saved
196
- credential; no Microsoft password, browser cookie or client secret is stored by
197
- the PC Agent.
198
-
199
- Microsoft sign-in must remain enabled on Relay so the Agent can verify saved
200
- credentials at startup. Verification failures retain the saved credential and
201
- show an error instead of silently switching accounts.
202
-
203
- To authorize a stopped installation explicitly, including before headless
204
- startup, run:
205
-
206
- ```powershell
207
- agentknight login --env C:\path\to\agentknight.env
208
- ```
209
-
210
- Use the same environment file and data home as the service. Do not delete or
211
- recreate `device.json` to sign in. A running Agent must be stopped before an
212
- explicit login; the command does not stop it for you. Browser logout does not
213
- revoke this PC: use the Relay's `/account` page to revoke its grant.
214
-
215
- ### Existing tokens
216
-
217
- An existing `RELAY_TOKEN` continues to select token authentication unless
218
- `RELAY_AUTH` explicitly selects another mode. Microsoft sign-in uses the server's
219
- returned user identity, not `USER_ID`, and never falls back to the old token on
220
- failure. Keep legacy tokens in the environment file, not command-line arguments
221
- or source control.
222
-
223
- The local page shows the Relay account's username, role and authentication
224
- method, separately from coding-agent connections. Generated Microsoft usernames
225
- are displayed as "Microsoft account"; **查看账户** opens the Relay's browser account
226
- page to view the Microsoft name and manage device grants. Account details require the
227
- Relay's PC account endpoint; update Relay as well as the PC client. An older
228
- Relay is reported explicitly instead of guessing a username from `USER_ID`.
229
-
230
- See the [AgentKnight repository](https://github.com/hydraxman/AgentKnight) for
231
- Relay Server and Android client setup.
232
-
233
- ## Windows app
234
-
235
- Windows release packages include a private Node runtime and prebuilt PC Client.
236
- The **PC Client** tab does not need a global Node/npm installation or a first-run
237
- client download; update or repair it through the Windows app. WebView2 and
238
- provider sign-in remain separate prerequisites. Source builds without a bundled
239
- runtime retain the Node/npm setup path.
240
-
241
- Closing the window keeps clients running in the notification area. **Open**
242
- restores the window; **Exit** stops only app-owned clients, never external ones.
243
- App-managed configuration is encrypted and saved separately from external ENV
244
- files. See the [Windows runtime design](../../docs/remote-sessions/windows-runtime-design.md)
245
- for configuration ownership and the limits of Windows user-scoped protection.
246
-
247
- ## Coding agents
248
-
249
- The Copilot SDK and bundled CLI are pinned together in the [SDK manifest](../../shared/sdk/package.json).
250
- Keep separately installed Copilot terminals aligned with that CLI when attaching
251
- to their live sessions; restart the terminal after upgrading it. A
252
- `COPILOT_CLI_PATH` override must provide a compatible runtime.
253
-
254
- With `AGENTKNIGHT_CODING_AGENT=managed`, saved agent selections are restored at
255
- startup, including an intentionally empty selection. Without a saved selection,
256
- GitHub Copilot sync is enabled without visiting the local webpage. Use the webpage
257
- to enable agents and select **同步** (Sync), or explicitly show the QR code to pair Android.
258
- Multiple agents share one PC connection. Enabling an agent syncs all of its
259
- current and future locally discoverable sessions; individual sessions need no
260
- selection. Unselected agents remain private. Selections survive PC Agent restarts.
261
-
262
- Use `--agents copilot,pi` to enable agent sync at startup, or `--agents none` to disable
263
- all agent sync. This switches to managed mode and overrides both the saved selection and
264
- `AGENTKNIGHT_CODING_AGENT` for that start without overwriting saved settings.
265
- Native agent configuration still comes from the environment file. Subsequent
266
- webpage Sync actions apply immediately and save the selection; the startup flag takes precedence
267
- again on restart. Managed mode also works with the local webpage disabled.
268
-
269
- PI discovery reads its native session inventory without resuming conversations.
270
- AgentKnight can continue saved PI sessions, but cannot attach to a running PI
271
- terminal. Avoid continuing the same session concurrently in both applications.
272
-
273
- In Android, choose **Rename** from a supported session's menu to change its native
274
- name, not a local display alias. Renaming a group changes only its title, not its
275
- participants' names.
276
-
277
- Use **Agent 群聊** on the local webpage to enable or disable group chat without
278
- restarting the PC Agent. The saved choice takes precedence over the environment
279
- setting in [.env.example](.env.example), including after a restart. Disabling
280
- pauses active groups and keeps their history; enabling does not resume them automatically.
281
- Groups connect two shared Copilot sessions on the same PC, in either managed or
282
- single-engine mode, including sessions created in the CLI or restored after a restart.
283
- Both participants must be idle with no pending input. After restarting, groups remain
284
- paused without replay; send a new group message to continue with the existing members.
285
- Other engines do not support groups.
286
-
287
- For experimental online conversation between Copilot sessions on two PCs, see
288
- the [peer-chat setup](../../docs/remote-sessions/agent-group-chat-design.md#使用).
289
- It is separate from local groups and sends Relay-readable text.
290
- Use only non-sensitive test content.
291
-
292
- Explicit engine values retain single-engine operation without
293
- selection filtering. See [.env.example](.env.example) for configuration.
294
-
295
- | Engine | Setup |
296
- | --- | --- |
297
- | `copilot` | Authenticate the GitHub Copilot CLI as before. |
298
- | `pi` | Install the optional PI dependencies using the Node.js version required by their manifests. Authenticate through PI's CLI or supported provider environment variables. |
299
- | `codex` | Install and authenticate the [official Codex CLI](https://developers.openai.com/codex/cli/); executable overrides are in [.env.example](.env.example). |
300
- | `claude` | Enable optional dependencies and follow the [official Agent SDK setup](https://platform.claude.com/docs/en/agent-sdk/overview) for API-key or cloud-provider authentication. Personal subscription OAuth is not reused. |
301
- | `acp` | Install and authenticate an ACP-compatible agent or bridge. Set `AGENTKNIGHT_ACP_COMMAND` to its executable and `AGENTKNIGHT_ACP_ARGS` to a JSON string array, such as `["--stdio"]` if that agent requires it. |
302
-
303
- PI uses its native directory by default. `PI_CODING_AGENT_DIR` selects an
304
- alternative directory containing PI authentication, model configuration, and
305
- session history; use the same directory when authenticating PI. Install
306
- AgentKnight with optional dependencies enabled to use PI.
307
- Source builds and the complete adapter suite also require the PI-compatible Node
308
- version; Copilot-only operation retains the baseline version in the manifest.
309
-
310
- Enabling Codex or Claude synchronizes existing and newly discovered native
311
- sessions to the phone. Reading history does not start model work; sending resumes
312
- the original session. Disabling synchronization cancels only AgentKnight's work,
313
- not an external CLI process. Claude discovery and history do not require provider
314
- credentials; sending requires the authentication described above.
315
- Credentials stay on the PC; discovery does not verify authentication.
316
- Copilot-specific Workbench, group and peer-chat operations remain unsupported.
317
-
318
- Codex controls depend on the installed CLI's [App Server capabilities](https://developers.openai.com/codex/app-server/).
319
- Changes require an idle session and affect its subsequent turns, not approval or
320
- sandbox permissions.
321
-
322
- The ACP executable must speak the Agent Client Protocol over stdio; an ordinary
323
- Codex or Claude Code CLI is not automatically an ACP endpoint. Arguments are
324
- passed literally, without a shell. AgentKnight does not download or authenticate
325
- the configured executable. Choose a trusted local agent: its own tools execute
326
- with the PC user's privileges. ACP state is kept under the PC data directory,
327
- separately for each executable/argument configuration.
328
-
329
- Adapters expose only supported configuration and operations. PI executes tools
330
- natively, without an added per-tool approval layer. Project resources follow PI's
331
- native project trust decisions, with unresolved trust prompts routed to Android.
332
- Machine-wide features such as uploads and deletion are available only when every
333
- selected engine supports them; session controls use that session's own engine.
334
- ACP approvals use the agent's offered one-time permission option, never an
335
- automatic persistent grant. Unsupported operations return errors rather than
336
- pretending to succeed. Only Copilot exposes its remote-mode toggle.
337
- Generic file uploads remain Copilot-only; PI, Codex and Claude also reject image uploads, while
338
- ACP images require the agent's negotiated image support.
339
-
340
- Optional controls follow the [capability compatibility policy](../../docs/remote-sessions/protocol-compatibility-plan.md);
341
- the historical registration `sdkVersion` is a compatibility marker, while
342
- startup logs record the actual engine and SDK version.
343
-
344
- ## Copilot uploaded files
345
-
346
- Mobile uploads are integrity-checked transport bytes, not model API messages.
347
- The PC Agent keeps generic files in its Copilot session state (`COPILOT_HOME`,
348
- or the default Copilot home) and sends absolute paths through the official
349
- [SDK file attachment contract](https://github.com/github/copilot-sdk/blob/v1.0.11/nodejs/src/types.ts);
350
- images remain blob attachments. The local CLI decides native document handling
351
- versus file-tool access: even [document support](https://github.com/github/copilot-sdk/blob/v1.0.11/docs/features/citations.md#attach-documents-to-a-message)
352
- depends on the model, so an accepted upload does not guarantee every format is readable.
353
- Files remain across acknowledgements, queued turns, failed sends and local restarts/resumes;
354
- they are removed only after successful explicit session deletion, not after each turn.
355
- This requires the runtime to share the PC Agent's filesystem and Copilot home.
356
- The default stdio runtime and the SDK's in-process override are local; unverified
357
- external clients do not advertise file uploads and reject them with an actionable error.
358
- Moving a session to another machine does not transfer these local files.
1
+ # AgentKnight
2
+
3
+ AgentKnight PC Agent connects local coding-agent sessions to an AgentKnight
4
+ Relay Server through Copilot, PI SDK, or ACP adapters.
5
+
6
+ ## Embed
7
+
8
+ Use `@agentknight/sdk` to embed the PC Agent runtime in a Node.js application
9
+ without running the CLI or its local management service.
10
+ Call `initialize` with an explicit absolute `dataDirectory` and the connection,
11
+ identity and logging options, then manage the returned runtime with `start` and
12
+ `stop`. The SDK does not select `~/.ak` or read the CLI configuration for you.
13
+ Do not share a data directory between running instances.
14
+ After starting, `disconnectRelay()` pauses remote access while preserving local
15
+ providers and credentials. Use `reconnectRelay()` to resume and `getStatus()`
16
+ to verify recovery.
17
+
18
+ For renewable credentials, implement the [authorization provider](../../shared/sdk/src/relay-authorization.ts).
19
+ The host owns sign-in and cleanup; cloud image storage is not supported in this mode.
20
+
21
+ Azure Blob images are opt-in on the local PC page when the connected Relay offers
22
+ storage. See the [image API](../../docs/remote-sessions/session-image-api.md) for
23
+ client behavior and the non-E2EE storage boundary.
24
+
25
+ The CLI depends on the SDK; both use the same release version. The SDK can be
26
+ published independently through the [npm release workflow](../../.github/workflows/agentknight-npm-publish.yml).
27
+ See the [SDK entry point](../../shared/sdk/src/index.ts) for the public API.
28
+ For configuration and onboarding without loading the runtime, use
29
+ [`@agentknight/sdk/configuration`](../../shared/sdk/src/configuration.ts).
30
+
31
+ ## Run
32
+
33
+ Use the Node.js version required by [package.json](package.json) and authenticate
34
+ the coding agents you want to use.
35
+
36
+ ```powershell
37
+ npx @agentknight/client --env C:\path\to\agentknight.env
38
+ ```
39
+
40
+ Or install it globally:
41
+
42
+ ```powershell
43
+ npm install --global @agentknight/client
44
+ agentknight --env C:\path\to\agentknight.env
45
+ ```
46
+
47
+ To switch from the unscoped `agentknight` package, stop the Agent and its service,
48
+ run `npm uninstall --global agentknight`, then install `@agentknight/client` as
49
+ above. The command remains `agentknight`; keep the existing data home and
50
+ configuration. Re-register services that pin the old package path before
51
+ restarting. Updating the old package does not migrate it to the new name.
52
+
53
+ `AGENTKNIGHT_HOME` selects the PC data home, defaulting to `~/.ak`. Without
54
+ `--env`, AgentKnight reads `<home>/agentknight.env`, with process settings taking
55
+ precedence. With `--env`, the selected file is authoritative for PC settings:
56
+ missing settings use defaults or fail validation, rather than inheriting old
57
+ Relay credentials, machine names or data paths. OS and external provider
58
+ environment variables are retained; explicitly supplied file values override them.
59
+ Set custom `AGENTKNIGHT_HOME` in that file as well so restarts use the same home.
60
+
61
+ `AGENTKNIGHT_PI_DIRECTORY` is a deprecated input alias for PI's native
62
+ `PI_CODING_AGENT_DIR`; conflicting values are rejected. Use the native name
63
+ for new configuration. An empty value selects PI's native default.
64
+
65
+ The first normal startup can import legacy working-directory `.env` files or
66
+ the old macOS service configuration into `~/.ak/agentknight.env`. Conflicting
67
+ legacy values require selecting or reconciling the correct file; no source
68
+ silently wins. A selected custom home does not import another home's settings.
69
+ Status, stop and upgrade commands do not import or migrate configuration.
70
+
71
+ Identity, pairing keys and saved state belong only to the selected home.
72
+ Retired data directories and HOME aliases are ignored. Existing identities
73
+ are preserved; deleting the home requires pairing again. Conflicting identity
74
+ files require manual resolution, not an automatic reset.
75
+
76
+ Diagnostic JSONL files are under `<data-home>/logs/<version>/`. Existing
77
+ unversioned logs remain historical files; they are not assigned an invented
78
+ version. The local pairing page shows the running version, last successful
79
+ upgrade time, configuration location, and Relay URL.
80
+
81
+ ## Status and upgrades
82
+
83
+ ```powershell
84
+ agentknight --version
85
+ agentknight status
86
+ agentknight status --json
87
+ agentknight stop
88
+ agentknight upgrade --check
89
+ agentknight upgrade
90
+ ```
91
+
92
+ `stop` preserves data and refuses busy agents. External service managers may
93
+ restart it. See `agentknight --help` for command options.
94
+
95
+ `upgrade` uses the latest published version; `upgrade <version>` selects an exact
96
+ newer version. Self-upgrade requires a global npm installation, not an `npx`
97
+ cache or source checkout. Install a release containing this command through npm
98
+ before using it for subsequent upgrades.
99
+
100
+ Package resolution and installation try the official npm registry first, then
101
+ the Tencent npm mirror for network failures. Existing npm/proxy configuration
102
+ is respected without changing global settings. Archives and dependencies for
103
+ both the target and rollback are prepared before stopping the running Agent.
104
+
105
+ An independent worker waits for idle and performs the switch. Windows scheduled
106
+ tasks and the supplied macOS LaunchAgent retain their existing configuration;
107
+ foreground instances restart in the background. Persist their configuration and
108
+ provider credentials in the environment file before upgrading; shell-only values
109
+ that cannot be restored cause the upgrade to be refused. A stopped installation
110
+ remains stopped. User-level installations do not require elevation; protected npm
111
+ prefixes or service definitions need their existing permissions.
112
+
113
+ The command reports the handoff, not successful completion. Use `status` to see
114
+ the persistent result if the initiating connection closes. An Agent that remains
115
+ busy is left running. Startup failure triggers an offline rollback; readiness
116
+ requires the new instance's registration and initial synchronization, not merely
117
+ an HTTP health response. Upgrading briefly interrupts the PC connection and does
118
+ not migrate an active model turn between processes.
119
+
120
+ Successful upgrades remove their temporary installation materials. Failed jobs
121
+ retain their diagnostic files under `<data-home>/upgrades`; the last successful
122
+ upgrade timestamp changes only after recovery is confirmed.
123
+
124
+ ## Configuration
125
+
126
+ Create the environment file from the [PC Agent example](.env.example), set
127
+ `RELAY_URL` and sign in from the local page. Account-system discovery never falls
128
+ back on failure; select an explicit mode for older Relays without discovery.
129
+
130
+ AAD uses the OS authentication broker without password, API-key, browser or
131
+ device-code fallback. Before headless startup, run `agentknight login` with the
132
+ service's configuration and OS account.
133
+
134
+ `RELAY_URL` is used for HTTP APIs and Socket.IO, so an `https://` URL enables
135
+ HTTPS and WSS for the entire PC Agent connection. `AGENTKNIGHT_MACHINE_NAME`
136
+ controls the PC name shown to mobile clients. The selection and pairing webpage
137
+ listens only on loopback; `PAIRING_PAGE_PORT` changes its local port.
138
+
139
+ On the local page, expand a working-directory folder and select a session to
140
+ browse its conversation history. Viewing is read-only and does not change
141
+ mobile sync selection or create a separate archive.
142
+
143
+ The local pages remember your language choice. Phone authorization requests open
144
+ a verification dialog automatically. Compare its code with the phone before
145
+ allowing access; dismissing the dialog leaves the request pending for later review.
146
+
147
+ Use **重连** on the local page to retry with saved credentials without
148
+ restarting coding agents. Recognized authorization-service outages retry
149
+ automatically; other server-initiated disconnects require user action.
150
+ **断开连接** pauses remote access until **重连** or a PC Client restart,
151
+ without stopping local agents or clearing saved login.
152
+
153
+ Repository checkouts also include Windows Scheduled Task and macOS LaunchAgent
154
+ installers under `clients/pc-agent/scripts`. Services use the same canonical
155
+ configuration as the CLI, not a copied environment file. Service support files
156
+ and output logs live under `<home>/service` and `<home>/logs/service`; OS task and
157
+ LaunchAgent registrations stay in their required system locations. Reinstall the
158
+ service to update an older registration after stopping it and migrating its
159
+ configuration. Explicit external environment files remain referenced in place.
160
+ Uninstalling the service preserves configuration, identity and logs.
161
+ Installers resolve the data home through `agentknight status --json`, so they
162
+ must be used with the matching installed CLI. They pin the installation working
163
+ directory to preserve relative paths; reinstall after changing the configured
164
+ home or moving that directory. A missing canonical configuration must be
165
+ created or migrated before installing the default service. Both default and
166
+ explicit-file installations refuse a pending legacy-home migration; stop the old
167
+ service and complete a normal startup with the selected configuration first.
168
+
169
+ Services use the platform's trusted HTTPS certificates. Reinstall older services
170
+ that supplied a private CA, omitting certificate arguments.
171
+
172
+ ### Microsoft sign-in
173
+
174
+ For an MSA Relay, choose personal-account sign-in on the local page.
175
+ Complete Microsoft sign-in and any application consent in a browser on that same
176
+ computer. The browser returns to AgentKnight automatically; there is no device
177
+ code to copy or enter. The Relay must support browser callback sign-in, have
178
+ Microsoft sign-in enabled, and admit your account through its administrator.
179
+ An older Relay must be upgraded rather than silently switching to manual codes.
180
+
181
+ After approval, AgentKnight saves the machine-bound Relay credential in the
182
+ current OS user's credential store, confirms it with Relay, and connects. The
183
+ normal local page provides Android pairing: scan the QR code, match the verification
184
+ code, and approve on the PC. Manage and revoke individual clients on that page.
185
+ Upgrade Relay and Android before the PC; existing phones must pair again when
186
+ approval is first enabled.
187
+ See the [approval compatibility policy](../../docs/remote-sessions/protocol-compatibility-plan.md#手机连接审批与撤销)
188
+ for migration and revocation limits. Microsoft sign-in does not replace the
189
+ PC–phone encryption key or authenticate GitHub Copilot.
190
+
191
+ Microsoft sign-in supports Windows Credential Manager and macOS Keychain only.
192
+ Other operating systems are not supported for Microsoft sign-in; existing token
193
+ authentication is unchanged. There is no plaintext or nonpersistent-keyring fallback.
194
+ Run the service as the same OS user who signed in. Restarts reuse the saved
195
+ credential; no Microsoft password, browser cookie or client secret is stored by
196
+ the PC Agent.
197
+
198
+ Microsoft sign-in must remain enabled on Relay so the Agent can verify saved
199
+ credentials at startup. Verification failures retain the saved credential and
200
+ show an error instead of silently switching accounts.
201
+
202
+ To authorize a stopped installation explicitly, including before headless
203
+ startup, run:
204
+
205
+ ```powershell
206
+ agentknight login --env C:\path\to\agentknight.env
207
+ ```
208
+
209
+ Use the same environment file and data home as the service. Do not delete or
210
+ recreate `device.json` to sign in. A running Agent must be stopped before an
211
+ explicit login; the command does not stop it for you. Browser logout does not
212
+ revoke this PC: use the Relay's `/account` page to revoke its grant.
213
+
214
+ ### Existing tokens
215
+
216
+ An existing `RELAY_TOKEN` continues to select token authentication unless
217
+ `RELAY_AUTH` explicitly selects another mode. Microsoft sign-in uses the server's
218
+ returned user identity, not `USER_ID`, and never falls back to the old token on
219
+ failure. Keep legacy tokens in the environment file, not command-line arguments
220
+ or source control.
221
+
222
+ The local page shows the Relay account's username, role and authentication
223
+ method, separately from coding-agent connections. Generated Microsoft usernames
224
+ are displayed as "Microsoft account"; **查看账户** opens the Relay's browser account
225
+ page to view the Microsoft name and manage device grants. Account details require the
226
+ Relay's PC account endpoint; update Relay as well as the PC client. An older
227
+ Relay is reported explicitly instead of guessing a username from `USER_ID`.
228
+
229
+ See the [AgentKnight repository](https://github.com/hydraxman/AgentKnight) for
230
+ Relay Server and Android client setup.
231
+
232
+ ## Text input
233
+
234
+ Select text in Android and choose **Input to PC**. Relay delivery works without the
235
+ Windows app shell, but the PC Agent must run in the signed-in user's interactive
236
+ desktop. It copies the text and sends a paste shortcut without switching windows
237
+ or unlocking the PC. Confirmation does not prove insertion by the target app;
238
+ failed requests are not automatically replayed.
239
+
240
+ ## Windows app
241
+
242
+ Windows release packages include a private Node runtime and prebuilt PC Client.
243
+ The **PC Client** tab does not need a global Node/npm installation or a first-run
244
+ client download; update or repair it through the Windows app. WebView2 and
245
+ provider sign-in remain separate prerequisites. Source builds without a bundled
246
+ runtime retain the Node/npm setup path.
247
+
248
+ Closing the window keeps clients running in the notification area. **Open**
249
+ restores the window; **Exit** stops only app-owned clients, never external ones.
250
+ App-managed configuration is encrypted and saved separately from external ENV
251
+ files. See the [Windows runtime design](../../docs/remote-sessions/windows-runtime-design.md)
252
+ for configuration ownership and the limits of Windows user-scoped protection.
253
+
254
+ ## Coding agents
255
+
256
+ The Copilot SDK and bundled CLI are pinned together in the [SDK manifest](../../shared/sdk/package.json).
257
+ Keep separately installed Copilot terminals aligned with that CLI when attaching
258
+ to their live sessions; restart the terminal after upgrading it. A
259
+ `COPILOT_CLI_PATH` override must provide a compatible runtime.
260
+
261
+ With `AGENTKNIGHT_CODING_AGENT=managed`, saved agent selections are restored at
262
+ startup, including an intentionally empty selection. Without a saved selection,
263
+ GitHub Copilot sync is enabled without visiting the local webpage. Use the webpage
264
+ to enable agents and select **同步** (Sync), or explicitly show the QR code to pair Android.
265
+ Multiple agents share one PC connection. Enabling an agent syncs all of its
266
+ current and future locally discoverable sessions; individual sessions need no
267
+ selection. Unselected agents remain private. Selections survive PC Agent restarts.
268
+
269
+ Use `--agents copilot,pi` to enable agent sync at startup, or `--agents none` to disable
270
+ all agent sync. This switches to managed mode and overrides both the saved selection and
271
+ `AGENTKNIGHT_CODING_AGENT` for that start without overwriting saved settings.
272
+ Native agent configuration still comes from the environment file. Subsequent
273
+ webpage Sync actions apply immediately and save the selection; the startup flag takes precedence
274
+ again on restart. Managed mode also works with the local webpage disabled.
275
+
276
+ PI discovery reads its native session inventory without resuming conversations.
277
+ AgentKnight can continue saved PI sessions, but cannot attach to a running PI
278
+ terminal. Avoid continuing the same session concurrently in both applications.
279
+
280
+ In Android, choose **Rename** from a supported session's menu to change its native
281
+ name, not a local display alias. Renaming a group changes only its title, not its
282
+ participants' names.
283
+
284
+ Use **Agent 群聊** on the local webpage to enable or disable group chat without
285
+ restarting the PC Agent. The saved choice takes precedence over the environment
286
+ setting in [.env.example](.env.example), including after a restart. Disabling
287
+ pauses active groups and keeps their history; enabling does not resume them automatically.
288
+ Groups connect two shared Copilot sessions on the same PC, in either managed or
289
+ single-engine mode, including sessions created in the CLI or restored after a restart.
290
+ Both participants must be idle with no pending input. After restarting, groups remain
291
+ paused without replay; send a new group message to continue with the existing members.
292
+ Other engines do not support groups.
293
+
294
+ For experimental online conversation between Copilot sessions on two PCs, see
295
+ the [peer-chat setup](../../docs/remote-sessions/agent-group-chat-design.md#使用).
296
+ It is separate from local groups and sends Relay-readable text.
297
+ Use only non-sensitive test content.
298
+
299
+ Explicit engine values retain single-engine operation without
300
+ selection filtering. See [.env.example](.env.example) for configuration.
301
+
302
+ | Engine | Setup |
303
+ | --- | --- |
304
+ | `copilot` | Authenticate the GitHub Copilot CLI as before. |
305
+ | `pi` | Install the optional PI dependencies using the Node.js version required by their manifests. Authenticate through PI's CLI or supported provider environment variables. |
306
+ | `codex` | Install and authenticate the [official Codex CLI](https://developers.openai.com/codex/cli/); executable overrides are in [.env.example](.env.example). |
307
+ | `claude` | Enable optional dependencies and follow the [official Agent SDK setup](https://platform.claude.com/docs/en/agent-sdk/overview) for API-key or cloud-provider authentication. Personal subscription OAuth is not reused. |
308
+ | `acp` | Install and authenticate an ACP-compatible agent or bridge. Set `AGENTKNIGHT_ACP_COMMAND` to its executable and `AGENTKNIGHT_ACP_ARGS` to a JSON string array, such as `["--stdio"]` if that agent requires it. |
309
+
310
+ PI uses its native directory by default. `PI_CODING_AGENT_DIR` selects an
311
+ alternative directory containing PI authentication, model configuration, and
312
+ session history; use the same directory when authenticating PI. Install
313
+ AgentKnight with optional dependencies enabled to use PI.
314
+ Source builds and the complete adapter suite also require the PI-compatible Node
315
+ version; Copilot-only operation retains the baseline version in the manifest.
316
+
317
+ Enabling Codex or Claude synchronizes existing and newly discovered native
318
+ sessions to the phone. Reading history does not start model work; sending resumes
319
+ the original session. Disabling synchronization cancels only AgentKnight's work,
320
+ not an external CLI process. Claude discovery and history do not require provider
321
+ credentials; sending requires the authentication described above.
322
+ Credentials stay on the PC; discovery does not verify authentication.
323
+ Copilot-specific Workbench, group and peer-chat operations remain unsupported.
324
+
325
+ Codex controls depend on the installed CLI's [App Server capabilities](https://developers.openai.com/codex/app-server/).
326
+ Changes require an idle session and affect its subsequent turns, not approval or
327
+ sandbox permissions.
328
+
329
+ The ACP executable must speak the Agent Client Protocol over stdio; an ordinary
330
+ Codex or Claude Code CLI is not automatically an ACP endpoint. Arguments are
331
+ passed literally, without a shell. AgentKnight does not download or authenticate
332
+ the configured executable. Choose a trusted local agent: its own tools execute
333
+ with the PC user's privileges. ACP state is kept under the PC data directory,
334
+ separately for each executable/argument configuration.
335
+
336
+ Adapters expose only supported configuration and operations. PI executes tools
337
+ natively, without an added per-tool approval layer. Project resources follow PI's
338
+ native project trust decisions, with unresolved trust prompts routed to Android.
339
+ Machine-wide features such as uploads and deletion are available only when every
340
+ selected engine supports them; session controls use that session's own engine.
341
+ ACP approvals use the agent's offered one-time permission option, never an
342
+ automatic persistent grant. Unsupported operations return errors rather than
343
+ pretending to succeed. Only Copilot exposes its remote-mode toggle.
344
+ Generic file uploads remain Copilot-only; PI, Codex and Claude also reject image uploads, while
345
+ ACP images require the agent's negotiated image support.
346
+
347
+ Optional controls follow the [capability compatibility policy](../../docs/remote-sessions/protocol-compatibility-plan.md);
348
+ the historical registration `sdkVersion` is a compatibility marker, while
349
+ startup logs record the actual engine and SDK version.
350
+
351
+ ## Copilot uploaded files
352
+
353
+ Mobile uploads are integrity-checked transport bytes, not model API messages.
354
+ The PC Agent keeps generic files in its Copilot session state (`COPILOT_HOME`,
355
+ or the default Copilot home) and sends absolute paths through the official
356
+ [SDK file attachment contract](https://github.com/github/copilot-sdk/blob/v1.0.11/nodejs/src/types.ts);
357
+ images remain blob attachments. The local CLI decides native document handling
358
+ versus file-tool access: even [document support](https://github.com/github/copilot-sdk/blob/v1.0.11/docs/features/citations.md#attach-documents-to-a-message)
359
+ depends on the model, so an accepted upload does not guarantee every format is readable.
360
+ Files remain across acknowledgements, queued turns, failed sends and local restarts/resumes;
361
+ they are removed only after successful explicit session deletion, not after each turn.
362
+ This requires the runtime to share the PC Agent's filesystem and Copilot home.
363
+ The default stdio runtime and the SDK's in-process override are local; unverified
364
+ external clients do not advertise file uploads and reject them with an actionable error.
365
+ Moving a session to another machine does not transfer these local files.