@agentknight/client 0.9.47 → 0.9.48

package/README.md

@@ -1,305 +1,324 @@
-# AgentKnight
-
-AgentKnight PC Agent connects local coding-agent sessions to an AgentKnight
-Relay Server through Copilot, PI SDK, or ACP adapters.
-
-## Embed
-
-Use `@agentknight/sdk` to embed the PC Agent runtime in a Node.js application
-without running the CLI or its local management service.
-Call `initialize` with an explicit absolute `dataDirectory` and the connection,
-identity and logging options, then manage the returned runtime with `start` and
-`stop`. The SDK does not select `~/.ak` or read the CLI configuration for you.
-Do not share a data directory between running instances.
-
-The CLI depends on the SDK; both use the same release version. The SDK can be
-published independently through the [npm release workflow](../../.github/workflows/agentknight-npm-publish.yml).
-See the [SDK entry point](../../shared/sdk/src/index.ts) for the public API.
-
-## Run
-
-Use the Node.js version required by [package.json](package.json) and authenticate
-the coding agents you want to use.
-
-```powershell
-npx @agentknight/client --env C:\path\to\agentknight.env
-```
-
-Or install it globally:
-
-```powershell
-npm install --global @agentknight/client
-agentknight --env C:\path\to\agentknight.env
-```
-
-To switch from the unscoped `agentknight` package, stop the Agent and its service,
-run `npm uninstall --global agentknight`, then install `@agentknight/client` as
-above. The command remains `agentknight`; keep the existing data home and
-configuration. Re-register services that pin the old package path before
-restarting. Updating the old package does not migrate it to the new name.
-
-`AGENTKNIGHT_HOME` selects the PC data home, defaulting to `~/.ak`. Without
-`--env`, AgentKnight reads `<home>/agentknight.env`, with process settings taking
-precedence. With `--env`, the selected file is authoritative for PC settings:
-missing settings use defaults or fail validation, rather than inheriting old
-Relay credentials, machine names or data paths. OS and external provider
-environment variables are retained; explicitly supplied file values override them.
-Set custom `AGENTKNIGHT_HOME` in that file as well so restarts use the same home.
-
-`COPILOT_REMOTE_HOME` and `AGENTKNIGHT_PI_DIRECTORY` are deprecated input aliases
-for `AGENTKNIGHT_HOME` and PI's native `PI_CODING_AGENT_DIR`. Conflicting aliases
-in the same source are rejected. New configuration and restart metadata use only
-the canonical names. PI's native tilde, file URL and Windows shell path syntax
-is preserved; an explicitly empty PI directory selects its native default.
-
-The first normal startup can import legacy working-directory `.env` files or
-the old macOS service configuration into `~/.ak/agentknight.env`. Conflicting
-legacy values require selecting or reconciling the correct file; no source
-silently wins. A selected custom home does not import another home's settings.
-Status and upgrade commands do not import or migrate configuration.
-
-A legacy `~/.copilot-remote` home is copied only while the old Agent is stopped,
-preserving its machine identity, pairing keys and saved state. The stable device
-ID now lives in `<home>/device-id` alongside `device.json`; existing identities
-are preserved when importing a retired client layout's ID. Fresh custom homes have
-independent identities. No retired client directory or compatibility symlink is
-created. Conflicting identities or homes require manual resolution, not an
-automatic reset. Retained legacy files are rollback copies, never dual-written;
-remove them only after verifying the migrated installation while old agents are stopped.
-
-Diagnostic JSONL files are under `<data-home>/logs/<version>/`. Existing
-unversioned logs remain historical files; they are not assigned an invented
-version. The local pairing page shows the running version, last successful
-upgrade time, configuration location, and Relay URL.
-
-## Status and upgrades
-
-```powershell
-agentknight --version
-agentknight status
-agentknight status --json
-agentknight upgrade --check
-agentknight upgrade
-```
-
-`upgrade` uses the latest published version; `upgrade <version>` selects an exact
-newer version. Self-upgrade requires a global npm installation, not an `npx`
-cache or source checkout. Install a release containing this command through npm
-before using it for subsequent upgrades.
-
-Package resolution and installation try the official npm registry first, then
-the Tencent npm mirror for network failures. Existing npm/proxy configuration
-is respected without changing global settings. Archives and dependencies for
-both the target and rollback are prepared before stopping the running Agent.
-
-An independent worker waits for idle and performs the switch. Windows scheduled
-tasks and the supplied macOS LaunchAgent retain their existing configuration;
-foreground instances restart in the background. Persist their configuration and
-provider credentials in the environment file before upgrading; shell-only values
-that cannot be restored cause the upgrade to be refused. A stopped installation
-remains stopped. User-level installations do not require elevation; protected npm
-prefixes or service definitions need their existing permissions.
-
-The command reports the handoff, not successful completion. Use `status` to see
-the persistent result if the initiating connection closes. An Agent that remains
-busy is left running. Startup failure triggers an offline rollback; readiness
-requires the new instance's registration and initial synchronization, not merely
-an HTTP health response. Upgrading briefly interrupts the PC connection and does
-not migrate an active model turn between processes.
-
-Successful upgrades remove their temporary installation materials. Failed jobs
-retain their diagnostic files under `<data-home>/upgrades`; the last successful
-upgrade timestamp changes only after recovery is confirmed.
-
-## Configuration
-
-Create the environment file from the
-[PC Agent example](https://github.com/hydraxman/AgentKnight/blob/main/clients/pc-agent/.env.example).
-
-`RELAY_URL` is used for HTTP APIs and Socket.IO, so an `https://` URL enables
-HTTPS and WSS for the entire PC Agent connection. `AGENTKNIGHT_MACHINE_NAME`
-controls the PC name shown to mobile clients. The selection and pairing webpage
-listens only on loopback; `PAIRING_PAGE_PORT` changes its local port.
-
-Repository checkouts also include Windows Scheduled Task and macOS LaunchAgent
-installers under `clients/pc-agent/scripts`. Services use the same canonical
-configuration as the CLI, not a copied environment file. Service support files
-and output logs live under `<home>/service` and `<home>/logs/service`; OS task and
-LaunchAgent registrations stay in their required system locations. Reinstall the
-service to update an older registration after stopping it and migrating its
-configuration. Explicit external environment files remain referenced in place.
-Uninstalling the service preserves configuration, identity and logs.
-Installers resolve the data home through `agentknight status --json`, so they
-must be used with the matching installed CLI. They pin the installation working
-directory to preserve relative paths; reinstall after changing the configured
-home or moving that directory. A missing canonical configuration must be
-created or migrated before installing the default service. Both default and
-explicit-file installations refuse a pending legacy-home migration; stop the old
-service and complete a normal startup with the selected configuration first.
-
-Re-register older Windows tasks
-that use `-CaCertPath` with `agentknight-service.ps1 install -EnvFile <path>`
-(and `-TaskName <name>` for a custom task), omitting `-CaCertPath`.
-
-### Microsoft sign-in
-
-Set `RELAY_URL` and `RELAY_AUTH=microsoft` in the environment file, then start
-AgentKnight. Open the printed loopback URL and select **使用 Microsoft 登录**.
-Complete Microsoft sign-in and any application consent in a browser on that same
-computer. The browser returns to AgentKnight automatically; there is no device
-code to copy or enter. The Relay must support browser callback sign-in, have
-Microsoft sign-in enabled, and admit your account through its administrator.
-An older Relay must be upgraded rather than silently switching to manual codes.
-
-After approval, AgentKnight saves the machine-bound Relay credential in the
-current OS user's credential store, confirms it with Relay, and connects. The
-normal local page then provides Android pairing. Android still only scans or
-imports the pairing information; Microsoft sign-in does not replace the
-PC–phone encryption key or authenticate GitHub Copilot.
-
-Microsoft sign-in supports Windows Credential Manager and macOS Keychain only.
-Other operating systems are not supported for Microsoft sign-in; existing token
-authentication is unchanged. There is no plaintext or nonpersistent-keyring fallback.
-Run the service as the same OS user who signed in. Restarts reuse the saved
-credential; no Microsoft password, browser cookie or client secret is stored by
-the PC Agent.
-
-Microsoft sign-in must remain enabled on Relay so the Agent can verify saved
-credentials at startup. Verification failures retain the saved credential and
-show an error instead of silently switching accounts.
-
-To authorize a stopped installation explicitly, including before headless
-startup, run:
-
-```powershell
-agentknight login --env C:\path\to\agentknight.env
-```
-
-Use the same environment file and data home as the service. Do not delete or
-recreate `device.json` to sign in. A running Agent must be stopped before an
-explicit login; the command does not stop it for you. Browser logout does not
-revoke this PC: use the Relay's `/account` page to revoke its grant.
-
-### Existing tokens
-
-An existing `RELAY_TOKEN` continues to select token authentication unless
-`RELAY_AUTH=microsoft` is explicitly set. Microsoft sign-in uses the server's
-returned user identity, not `USER_ID`, and never falls back to the old token on
-failure. Keep legacy tokens in the environment file, not command-line arguments
-or source control.
-
-The local page shows the Relay account's username, role and authentication
-method, separately from coding-agent connections. Generated Microsoft usernames
-are displayed as "Microsoft account"; **查看账户** opens the Relay's browser account
-page to view the Microsoft name and manage device grants. Account details require the
-Relay's PC account endpoint; update Relay as well as the PC client. An older
-Relay is reported explicitly instead of guessing a username from `USER_ID`.
-
-See the [AgentKnight repository](https://github.com/hydraxman/AgentKnight) for
-Relay Server and Android client setup.
-
-## Coding agents
-
-The Copilot SDK and bundled CLI are pinned together in the [SDK manifest](../../shared/sdk/package.json).
-Keep separately installed Copilot terminals aligned with that CLI when attaching
-to their live sessions; restart the terminal after upgrading it. A
-`COPILOT_CLI_PATH` override must provide a compatible runtime.
-
-With `AGENTKNIGHT_CODING_AGENT=managed`, saved agent selections are restored at
-startup, including an intentionally empty selection. Without a saved selection,
-GitHub Copilot sync is enabled without visiting the local webpage. Use the webpage
-to enable agents and select **同步** (Sync), or explicitly show the QR code to pair Android.
-Multiple agents share one PC connection. Enabling an agent syncs all of its
-current and future locally discoverable sessions; individual sessions need no
-selection. Unselected agents remain private. Selections survive PC Agent restarts.
-
-Use `--agents copilot,pi` to enable agent sync at startup, or `--agents none` to disable
-all agent sync. This switches to managed mode and overrides both the saved selection and
-`AGENTKNIGHT_CODING_AGENT` for that start without overwriting saved settings.
-Native agent configuration still comes from the environment file. Subsequent
-webpage Sync actions apply immediately and save the selection; the startup flag takes precedence
-again on restart. Managed mode also works with the local webpage disabled.
-
-PI discovery reads its native session inventory without resuming conversations.
-AgentKnight can continue saved PI sessions, but cannot attach to a running PI
-terminal. Avoid continuing the same session concurrently in both applications.
-
-In Android, choose **Rename** from a supported session's menu to change its native
-name, not a local display alias. Renaming a group changes only its title, not its
-participants' names.
-
-Use **Agent 群聊** on the local webpage to enable or disable group chat without
-restarting the PC Agent. The saved choice takes precedence over the environment
-setting in [.env.example](.env.example), including after a restart. Disabling
-pauses active groups and keeps their history; enabling does not resume them automatically.
-Groups connect two shared Copilot sessions on the same PC, in either managed or
-single-engine mode, including sessions created in the CLI or restored after a restart.
-Both participants must be idle with no pending input. After restarting, groups remain
-paused without replay; send a new group message to continue with the existing members.
-Other engines do not support groups.
-
-For experimental online conversation between Copilot sessions on two PCs, see
-the [peer-chat setup](../../docs/remote-sessions/agent-group-chat-design.md#使用).
-It is separate from local groups and sends Relay-readable text.
-Use only non-sensitive test content.
-
-Explicit engine values retain single-engine operation without
-selection filtering. See [.env.example](.env.example) for configuration.
-
-| Engine | Setup |
-| --- | --- |
-| `copilot` | Authenticate the GitHub Copilot CLI as before. |
-| `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. |
-| `codex` | Install and authenticate the [official Codex CLI](https://developers.openai.com/codex/cli/); executable overrides are in [.env.example](.env.example). |
-| `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. |
-| `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. |
-
-PI uses its native directory by default. `PI_CODING_AGENT_DIR` selects an
-alternative directory containing PI authentication, model configuration, and
-session history; use the same directory when authenticating PI. Install
-AgentKnight with optional dependencies enabled to use PI.
-Source builds and the complete adapter suite also require the PI-compatible Node
-version; Copilot-only operation retains the baseline version in the manifest.
-
-Codex (App Server) and Claude (Agent SDK) expose only AgentKnight-created
-conversations and their saved history, not existing CLI/IDE conversations.
-Credentials stay on the PC; discovery does not verify authentication.
-Copilot-specific Workbench, group and peer-chat operations remain unsupported.
-
-The ACP executable must speak the Agent Client Protocol over stdio; an ordinary
-Codex or Claude Code CLI is not automatically an ACP endpoint. Arguments are
-passed literally, without a shell. AgentKnight does not download or authenticate
-the configured executable. Choose a trusted local agent: its own tools execute
-with the PC user's privileges. ACP state is kept under the PC data directory,
-separately for each executable/argument configuration.
-
-Adapters expose only supported configuration and operations. PI executes tools
-natively, without an added per-tool approval layer. Project resources follow PI's
-native project trust decisions, with unresolved trust prompts routed to Android.
-Machine-wide features such as uploads and deletion are available only when every
-selected engine supports them; session controls use that session's own engine.
-ACP approvals use the agent's offered one-time permission option, never an
-automatic persistent grant. Unsupported operations return errors rather than
-pretending to succeed. Only Copilot exposes its remote-mode toggle.
-Generic file uploads remain Copilot-only; PI, Codex and Claude also reject image uploads, while
-ACP images require the agent's negotiated image support.
-
-Optional controls follow the [capability compatibility policy](../../docs/remote-sessions/protocol-compatibility-plan.md);
-the historical registration `sdkVersion` is a compatibility marker, while
-startup logs record the actual engine and SDK version.
-
-## Copilot uploaded files
-
-Mobile uploads are integrity-checked transport bytes, not model API messages.
-The PC Agent keeps generic files in its Copilot session state (`COPILOT_HOME`,
-or the default Copilot home) and sends absolute paths through the official
-[SDK file attachment contract](https://github.com/github/copilot-sdk/blob/v1.0.11/nodejs/src/types.ts);
-images remain blob attachments. The local CLI decides native document handling
-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)
-depends on the model, so an accepted upload does not guarantee every format is readable.
-Files remain across acknowledgements, queued turns, failed sends and local restarts/resumes;
-they are removed only after successful explicit session deletion, not after each turn.
-This requires the runtime to share the PC Agent's filesystem and Copilot home.
-The default stdio runtime and the SDK's in-process override are local; unverified
-external clients do not advertise file uploads and reject them with an actionable error.
-Moving a session to another machine does not transfer these local files.
+# AgentKnight
+
+AgentKnight PC Agent connects local coding-agent sessions to an AgentKnight
+Relay Server through Copilot, PI SDK, or ACP adapters.
+
+## Embed
+
+Use `@agentknight/sdk` to embed the PC Agent runtime in a Node.js application
+without running the CLI or its local management service.
+Call `initialize` with an explicit absolute `dataDirectory` and the connection,
+identity and logging options, then manage the returned runtime with `start` and
+`stop`. The SDK does not select `~/.ak` or read the CLI configuration for you.
+Do not share a data directory between running instances.
+After starting, `disconnectRelay()` pauses remote access while preserving local
+providers and credentials. Use `reconnectRelay()` to resume and `getStatus()`
+to verify recovery.
+
+The CLI depends on the SDK; both use the same release version. The SDK can be
+published independently through the [npm release workflow](../../.github/workflows/agentknight-npm-publish.yml).
+See the [SDK entry point](../../shared/sdk/src/index.ts) for the public API.
+
+## Run
+
+Use the Node.js version required by [package.json](package.json) and authenticate
+the coding agents you want to use.
+
+```powershell
+npx @agentknight/client --env C:\path\to\agentknight.env
+```
+
+Or install it globally:
+
+```powershell
+npm install --global @agentknight/client
+agentknight --env C:\path\to\agentknight.env
+```
+
+To switch from the unscoped `agentknight` package, stop the Agent and its service,
+run `npm uninstall --global agentknight`, then install `@agentknight/client` as
+above. The command remains `agentknight`; keep the existing data home and
+configuration. Re-register services that pin the old package path before
+restarting. Updating the old package does not migrate it to the new name.
+
+`AGENTKNIGHT_HOME` selects the PC data home, defaulting to `~/.ak`. Without
+`--env`, AgentKnight reads `<home>/agentknight.env`, with process settings taking
+precedence. With `--env`, the selected file is authoritative for PC settings:
+missing settings use defaults or fail validation, rather than inheriting old
+Relay credentials, machine names or data paths. OS and external provider
+environment variables are retained; explicitly supplied file values override them.
+Set custom `AGENTKNIGHT_HOME` in that file as well so restarts use the same home.
+
+`COPILOT_REMOTE_HOME` and `AGENTKNIGHT_PI_DIRECTORY` are deprecated input aliases
+for `AGENTKNIGHT_HOME` and PI's native `PI_CODING_AGENT_DIR`. Conflicting aliases
+in the same source are rejected. New configuration and restart metadata use only
+the canonical names. PI's native tilde, file URL and Windows shell path syntax
+is preserved; an explicitly empty PI directory selects its native default.
+
+The first normal startup can import legacy working-directory `.env` files or
+the old macOS service configuration into `~/.ak/agentknight.env`. Conflicting
+legacy values require selecting or reconciling the correct file; no source
+silently wins. A selected custom home does not import another home's settings.
+Status and upgrade commands do not import or migrate configuration.
+
+A legacy `~/.copilot-remote` home is copied only while the old Agent is stopped,
+preserving its machine identity, pairing keys and saved state. The stable device
+ID now lives in `<home>/device-id` alongside `device.json`; existing identities
+are preserved when importing a retired client layout's ID. Fresh custom homes have
+independent identities. No retired client directory or compatibility symlink is
+created. Conflicting identities or homes require manual resolution, not an
+automatic reset. Retained legacy files are rollback copies, never dual-written;
+remove them only after verifying the migrated installation while old agents are stopped.
+
+Diagnostic JSONL files are under `<data-home>/logs/<version>/`. Existing
+unversioned logs remain historical files; they are not assigned an invented
+version. The local pairing page shows the running version, last successful
+upgrade time, configuration location, and Relay URL.
+
+## Status and upgrades
+
+```powershell
+agentknight --version
+agentknight status
+agentknight status --json
+agentknight upgrade --check
+agentknight upgrade
+```
+
+`upgrade` uses the latest published version; `upgrade <version>` selects an exact
+newer version. Self-upgrade requires a global npm installation, not an `npx`
+cache or source checkout. Install a release containing this command through npm
+before using it for subsequent upgrades.
+
+Package resolution and installation try the official npm registry first, then
+the Tencent npm mirror for network failures. Existing npm/proxy configuration
+is respected without changing global settings. Archives and dependencies for
+both the target and rollback are prepared before stopping the running Agent.
+
+An independent worker waits for idle and performs the switch. Windows scheduled
+tasks and the supplied macOS LaunchAgent retain their existing configuration;
+foreground instances restart in the background. Persist their configuration and
+provider credentials in the environment file before upgrading; shell-only values
+that cannot be restored cause the upgrade to be refused. A stopped installation
+remains stopped. User-level installations do not require elevation; protected npm
+prefixes or service definitions need their existing permissions.
+
+The command reports the handoff, not successful completion. Use `status` to see
+the persistent result if the initiating connection closes. An Agent that remains
+busy is left running. Startup failure triggers an offline rollback; readiness
+requires the new instance's registration and initial synchronization, not merely
+an HTTP health response. Upgrading briefly interrupts the PC connection and does
+not migrate an active model turn between processes.
+
+Successful upgrades remove their temporary installation materials. Failed jobs
+retain their diagnostic files under `<data-home>/upgrades`; the last successful
+upgrade timestamp changes only after recovery is confirmed.
+
+## Configuration
+
+Create the environment file from the
+[PC Agent example](https://github.com/hydraxman/AgentKnight/blob/main/clients/pc-agent/.env.example).
+
+`RELAY_URL` is used for HTTP APIs and Socket.IO, so an `https://` URL enables
+HTTPS and WSS for the entire PC Agent connection. `AGENTKNIGHT_MACHINE_NAME`
+controls the PC name shown to mobile clients. The selection and pairing webpage
+listens only on loopback; `PAIRING_PAGE_PORT` changes its local port.
+
+Use **重连** on the local page to retry with saved credentials without
+restarting coding agents. Recognized authorization-service outages retry
+automatically; other server-initiated disconnects require user action.
+**断开连接** pauses remote access until **重连** or a PC Client restart,
+without stopping local agents or clearing saved login.
+
+Repository checkouts also include Windows Scheduled Task and macOS LaunchAgent
+installers under `clients/pc-agent/scripts`. Services use the same canonical
+configuration as the CLI, not a copied environment file. Service support files
+and output logs live under `<home>/service` and `<home>/logs/service`; OS task and
+LaunchAgent registrations stay in their required system locations. Reinstall the
+service to update an older registration after stopping it and migrating its
+configuration. Explicit external environment files remain referenced in place.
+Uninstalling the service preserves configuration, identity and logs.
+Installers resolve the data home through `agentknight status --json`, so they
+must be used with the matching installed CLI. They pin the installation working
+directory to preserve relative paths; reinstall after changing the configured
+home or moving that directory. A missing canonical configuration must be
+created or migrated before installing the default service. Both default and
+explicit-file installations refuse a pending legacy-home migration; stop the old
+service and complete a normal startup with the selected configuration first.
+
+Re-register older Windows tasks
+that use `-CaCertPath` with `agentknight-service.ps1 install -EnvFile <path>`
+(and `-TaskName <name>` for a custom task), omitting `-CaCertPath`.
+
+### Microsoft sign-in
+
+Set `RELAY_URL` and `RELAY_AUTH=microsoft` in the environment file, then start
+AgentKnight. Open the printed loopback URL and select **使用 Microsoft 登录**.
+Complete Microsoft sign-in and any application consent in a browser on that same
+computer. The browser returns to AgentKnight automatically; there is no device
+code to copy or enter. The Relay must support browser callback sign-in, have
+Microsoft sign-in enabled, and admit your account through its administrator.
+An older Relay must be upgraded rather than silently switching to manual codes.
+
+After approval, AgentKnight saves the machine-bound Relay credential in the
+current OS user's credential store, confirms it with Relay, and connects. The
+normal local page then provides Android pairing. Android still only scans or
+imports the pairing information; Microsoft sign-in does not replace the
+PC–phone encryption key or authenticate GitHub Copilot.
+
+Microsoft sign-in supports Windows Credential Manager and macOS Keychain only.
+Other operating systems are not supported for Microsoft sign-in; existing token
+authentication is unchanged. There is no plaintext or nonpersistent-keyring fallback.
+Run the service as the same OS user who signed in. Restarts reuse the saved
+credential; no Microsoft password, browser cookie or client secret is stored by
+the PC Agent.
+
+Microsoft sign-in must remain enabled on Relay so the Agent can verify saved
+credentials at startup. Verification failures retain the saved credential and
+show an error instead of silently switching accounts.
+
+To authorize a stopped installation explicitly, including before headless
+startup, run:
+
+```powershell
+agentknight login --env C:\path\to\agentknight.env
+```
+
+Use the same environment file and data home as the service. Do not delete or
+recreate `device.json` to sign in. A running Agent must be stopped before an
+explicit login; the command does not stop it for you. Browser logout does not
+revoke this PC: use the Relay's `/account` page to revoke its grant.
+
+### Existing tokens
+
+An existing `RELAY_TOKEN` continues to select token authentication unless
+`RELAY_AUTH=microsoft` is explicitly set. Microsoft sign-in uses the server's
+returned user identity, not `USER_ID`, and never falls back to the old token on
+failure. Keep legacy tokens in the environment file, not command-line arguments
+or source control.
+
+The local page shows the Relay account's username, role and authentication
+method, separately from coding-agent connections. Generated Microsoft usernames
+are displayed as "Microsoft account"; **查看账户** opens the Relay's browser account
+page to view the Microsoft name and manage device grants. Account details require the
+Relay's PC account endpoint; update Relay as well as the PC client. An older
+Relay is reported explicitly instead of guessing a username from `USER_ID`.
+
+See the [AgentKnight repository](https://github.com/hydraxman/AgentKnight) for
+Relay Server and Android client setup.
+
+## Windows app
+
+The Windows app's **PC Client** tab downloads and caches the published client;
+it is not bundled with the app. Follow the dependency prompts, then configure
+your Relay connection. Closing the app stops only clients it started;
+an existing client is reused without changing its settings or lifetime.
+
+## Coding agents
+
+The Copilot SDK and bundled CLI are pinned together in the [SDK manifest](../../shared/sdk/package.json).
+Keep separately installed Copilot terminals aligned with that CLI when attaching
+to their live sessions; restart the terminal after upgrading it. A
+`COPILOT_CLI_PATH` override must provide a compatible runtime.
+
+With `AGENTKNIGHT_CODING_AGENT=managed`, saved agent selections are restored at
+startup, including an intentionally empty selection. Without a saved selection,
+GitHub Copilot sync is enabled without visiting the local webpage. Use the webpage
+to enable agents and select **同步** (Sync), or explicitly show the QR code to pair Android.
+Multiple agents share one PC connection. Enabling an agent syncs all of its
+current and future locally discoverable sessions; individual sessions need no
+selection. Unselected agents remain private. Selections survive PC Agent restarts.
+
+Use `--agents copilot,pi` to enable agent sync at startup, or `--agents none` to disable
+all agent sync. This switches to managed mode and overrides both the saved selection and
+`AGENTKNIGHT_CODING_AGENT` for that start without overwriting saved settings.
+Native agent configuration still comes from the environment file. Subsequent
+webpage Sync actions apply immediately and save the selection; the startup flag takes precedence
+again on restart. Managed mode also works with the local webpage disabled.
+
+PI discovery reads its native session inventory without resuming conversations.
+AgentKnight can continue saved PI sessions, but cannot attach to a running PI
+terminal. Avoid continuing the same session concurrently in both applications.
+
+In Android, choose **Rename** from a supported session's menu to change its native
+name, not a local display alias. Renaming a group changes only its title, not its
+participants' names.
+
+Use **Agent 群聊** on the local webpage to enable or disable group chat without
+restarting the PC Agent. The saved choice takes precedence over the environment
+setting in [.env.example](.env.example), including after a restart. Disabling
+pauses active groups and keeps their history; enabling does not resume them automatically.
+Groups connect two shared Copilot sessions on the same PC, in either managed or
+single-engine mode, including sessions created in the CLI or restored after a restart.
+Both participants must be idle with no pending input. After restarting, groups remain
+paused without replay; send a new group message to continue with the existing members.
+Other engines do not support groups.
+
+For experimental online conversation between Copilot sessions on two PCs, see
+the [peer-chat setup](../../docs/remote-sessions/agent-group-chat-design.md#使用).
+It is separate from local groups and sends Relay-readable text.
+Use only non-sensitive test content.
+
+Explicit engine values retain single-engine operation without
+selection filtering. See [.env.example](.env.example) for configuration.
+
+| Engine | Setup |
+| --- | --- |
+| `copilot` | Authenticate the GitHub Copilot CLI as before. |
+| `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. |
+| `codex` | Install and authenticate the [official Codex CLI](https://developers.openai.com/codex/cli/); executable overrides are in [.env.example](.env.example). |
+| `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. |
+| `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. |
+
+PI uses its native directory by default. `PI_CODING_AGENT_DIR` selects an
+alternative directory containing PI authentication, model configuration, and
+session history; use the same directory when authenticating PI. Install
+AgentKnight with optional dependencies enabled to use PI.
+Source builds and the complete adapter suite also require the PI-compatible Node
+version; Copilot-only operation retains the baseline version in the manifest.
+
+Enabling Codex or Claude synchronizes existing and newly discovered native
+sessions to the phone. Reading history does not start model work; sending resumes
+the original session. Disabling synchronization cancels only AgentKnight's work,
+not an external CLI process. Claude discovery and history do not require provider
+credentials; sending requires the authentication described above.
+Credentials stay on the PC; discovery does not verify authentication.
+Copilot-specific Workbench, group and peer-chat operations remain unsupported.
+
+The ACP executable must speak the Agent Client Protocol over stdio; an ordinary
+Codex or Claude Code CLI is not automatically an ACP endpoint. Arguments are
+passed literally, without a shell. AgentKnight does not download or authenticate
+the configured executable. Choose a trusted local agent: its own tools execute
+with the PC user's privileges. ACP state is kept under the PC data directory,
+separately for each executable/argument configuration.
+
+Adapters expose only supported configuration and operations. PI executes tools
+natively, without an added per-tool approval layer. Project resources follow PI's
+native project trust decisions, with unresolved trust prompts routed to Android.
+Machine-wide features such as uploads and deletion are available only when every
+selected engine supports them; session controls use that session's own engine.
+ACP approvals use the agent's offered one-time permission option, never an
+automatic persistent grant. Unsupported operations return errors rather than
+pretending to succeed. Only Copilot exposes its remote-mode toggle.
+Generic file uploads remain Copilot-only; PI, Codex and Claude also reject image uploads, while
+ACP images require the agent's negotiated image support.
+
+Optional controls follow the [capability compatibility policy](../../docs/remote-sessions/protocol-compatibility-plan.md);
+the historical registration `sdkVersion` is a compatibility marker, while
+startup logs record the actual engine and SDK version.
+
+## Copilot uploaded files
+
+Mobile uploads are integrity-checked transport bytes, not model API messages.
+The PC Agent keeps generic files in its Copilot session state (`COPILOT_HOME`,
+or the default Copilot home) and sends absolute paths through the official
+[SDK file attachment contract](https://github.com/github/copilot-sdk/blob/v1.0.11/nodejs/src/types.ts);
+images remain blob attachments. The local CLI decides native document handling
+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)
+depends on the model, so an accepted upload does not guarantee every format is readable.
+Files remain across acknowledgements, queued turns, failed sends and local restarts/resumes;
+they are removed only after successful explicit session deletion, not after each turn.
+This requires the runtime to share the PC Agent's filesystem and Copilot home.
+The default stdio runtime and the SDK's in-process override are local; unverified
+external clients do not advertise file uploads and reject them with an actionable error.
+Moving a session to another machine does not transfer these local files.