@agentknight/client 0.9.49 → 0.9.51

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