@agentknight/client 0.9.52 → 0.9.53

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