@agentknight/client 0.9.39 → 0.9.40

package/LICENSE

@@ -1,201 +1,201 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,299 +1,299 @@
-# 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 the old `.bluepaw` ID. Fresh custom homes have
-independent identities. No new `.bluepaw` 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.
-
-Discovery reads native session inventories without resuming their conversations.
-AgentKnight can continue PI's saved sessions, but does not attach to an already
-running PI terminal. Avoid continuing the same native session concurrently in both
-applications. Provider credentials and history stay in their native stores.
-
-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.
-PI and ACP 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 `copilot`, `pi`, or `acp` 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` | Requires Node.js >=22.19.0 and the optional PI dependencies from the [SDK manifest](../../shared/sdk/package.json). Authenticate PI using its own CLI (`/login`) or supported provider API-key environment variables. |
-| `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.
-
-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. PI and ACP do not expose Copilot's remote-mode toggle.
-Generic file uploads remain Copilot-only; PI also rejects 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.
+
+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 the old `.bluepaw` ID. Fresh custom homes have
+independent identities. No new `.bluepaw` 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.
+
+Discovery reads native session inventories without resuming their conversations.
+AgentKnight can continue PI's saved sessions, but does not attach to an already
+running PI terminal. Avoid continuing the same native session concurrently in both
+applications. Provider credentials and history stay in their native stores.
+
+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.
+PI and ACP 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 `copilot`, `pi`, or `acp` 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` | Requires Node.js >=22.19.0 and the optional PI dependencies from the [SDK manifest](../../shared/sdk/package.json). Authenticate PI using its own CLI (`/login`) or supported provider API-key environment variables. |
+| `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.
+
+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. PI and ACP do not expose Copilot's remote-mode toggle.
+Generic file uploads remain Copilot-only; PI also rejects 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.

package/dist/cli.js

@@ -1730,6 +1730,7 @@ var SessionOptionsResultSchema = z18.discriminatedUnion("ok", [
     currentAgentMode: SessionAgentModeSchema.optional(),
     currentReasoningEffort: CurrentReasoningEffortSchema.optional(),
     environment: SessionEnvironmentInfoSchema.optional(),
+    environmentPending: z18.literal(true).optional(),
     agentName: z18.string().trim().min(1).max(260).optional(),
     configOptions: z18.array(AgentConfigurationOptionSchema).max(32).optional()
   }),
@@ -2176,7 +2177,8 @@ var SessionAssistantPreviewSchema = z22.object({
   sourceEventIds: z22.array(IdSchema).min(1).max(1e3),
   text: z22.string().max(4096),
   final: z22.boolean(),
-  attachments: z22.array(ConversationAttachmentSchema.refine((attachment) => attachment.kind === "image" && attachment.imageRef === "sha256", "Assistant previews contain image references only")).max(4)
+  attachments: z22.array(ConversationAttachmentSchema.refine((attachment) => attachment.kind === "image" && attachment.imageRef === "sha256", "Assistant previews contain image references only")).max(4),
+  kind: z22.enum(["assistant-message", "task-completion"]).optional()
 });
 var SESSION_TIMELINE_PAGE_SIZE = 100;
 var SessionTimelinePageRequestSchema = z22.object({
@@ -2248,6 +2250,10 @@ var SessionTimelineInvalidatedSchema = z22.object({
 }).strict();
 
 // ../../shared/protocol/dist/sessions/prompts.js
+var SessionAvatarPersonaSchema = z23.object({
+  role: z23.enum(["designer", "filmmaker", "developer", "secretary", "default"]),
+  displayName: z23.string().trim().min(1).max(40).regex(/^[^\u0000-\u001f\u007f-\u009f]*$/).optional()
+}).strict().refine((value) => value.role === "default" ? value.displayName === void 0 : value.displayName !== void 0, { message: "A role requires a display name; default must not include one" });
 var MAX_PROMPT_IMAGE_BYTES = 3 * 1024 * 1024;
 var SessionPromptRequestSchema = z23.object({
   requestId: IdSchema,
@@ -2257,6 +2263,7 @@ var SessionPromptRequestSchema = z23.object({
   prompt: z23.string().trim().max(1e5),
   attachments: z23.array(PromptImageAttachmentSchema).max(4).optional(),
   fileAttachments: z23.array(PromptFileAttachmentSchema).max(4).optional(),
+  avatarPersona: SessionAvatarPersonaSchema.optional(),
   mode: z23.enum(["enqueue", "immediate"]).default("enqueue")
 }).strict().superRefine((request, context) => {
   if (request.prompt.length === 0 && (request.attachments?.length ?? 0) === 0 && (request.fileAttachments?.length ?? 0) === 0) {

package/dist/upgrade-worker.js

@@ -19391,7 +19391,7 @@ async function installPreparedPackage(options) {
 import { createConnection, createServer } from "node:net";
 import { join as join5, resolve as resolve3 } from "node:path";
 
-// ../../shared/sdk/dist/chunks/chunk-E3XCZWRK.js
+// ../../shared/sdk/dist/chunks/chunk-OV77TRIH.js
 var IdSchema = external_exports.string().trim().min(1).max(256);
 var IsoDateSchema = external_exports.iso.datetime({ offset: true });
 var Base64UrlKeyIdSchema = external_exports.string().regex(/^[A-Za-z0-9_-]{22}$/u, "Expected a 16-byte base64url key ID");
@@ -19609,6 +19609,7 @@ var SessionOptionsResultSchema = external_exports.discriminatedUnion("ok", [
     currentAgentMode: SessionAgentModeSchema.optional(),
     currentReasoningEffort: CurrentReasoningEffortSchema.optional(),
     environment: SessionEnvironmentInfoSchema.optional(),
+    environmentPending: external_exports.literal(true).optional(),
     agentName: external_exports.string().trim().min(1).max(260).optional(),
     configOptions: external_exports.array(AgentConfigurationOptionSchema).max(32).optional()
   }),
@@ -20029,7 +20030,8 @@ var SessionAssistantPreviewSchema = external_exports.object({
   sourceEventIds: external_exports.array(IdSchema).min(1).max(1e3),
   text: external_exports.string().max(4096),
   final: external_exports.boolean(),
-  attachments: external_exports.array(ConversationAttachmentSchema.refine((attachment) => attachment.kind === "image" && attachment.imageRef === "sha256", "Assistant previews contain image references only")).max(4)
+  attachments: external_exports.array(ConversationAttachmentSchema.refine((attachment) => attachment.kind === "image" && attachment.imageRef === "sha256", "Assistant previews contain image references only")).max(4),
+  kind: external_exports.enum(["assistant-message", "task-completion"]).optional()
 });
 var SESSION_TIMELINE_PAGE_SIZE = 100;
 var SessionTimelinePageRequestSchema = external_exports.object({
@@ -21321,6 +21323,10 @@ var GroupChatCreateDataSchema = external_exports.object({
 var GroupChatCreateResultDataSchema = external_exports.object({
   session: SessionSummarySchema.refine((session) => session.groupChat !== void 0, "Group creation must return a virtual group session")
 }).strict();
+var SessionAvatarPersonaSchema = external_exports.object({
+  role: external_exports.enum(["designer", "filmmaker", "developer", "secretary", "default"]),
+  displayName: external_exports.string().trim().min(1).max(40).regex(/^[^\u0000-\u001f\u007f-\u009f]*$/).optional()
+}).strict().refine((value) => value.role === "default" ? value.displayName === void 0 : value.displayName !== void 0, { message: "A role requires a display name; default must not include one" });
 var MAX_PROMPT_IMAGE_BYTES = 3 * 1024 * 1024;
 var SessionPromptRequestSchema = external_exports.object({
   requestId: IdSchema,
@@ -21330,6 +21336,7 @@ var SessionPromptRequestSchema = external_exports.object({
   prompt: external_exports.string().trim().max(1e5),
   attachments: external_exports.array(PromptImageAttachmentSchema).max(4).optional(),
   fileAttachments: external_exports.array(PromptFileAttachmentSchema).max(4).optional(),
+  avatarPersona: SessionAvatarPersonaSchema.optional(),
   mode: external_exports.enum(["enqueue", "immediate"]).default("enqueue")
 }).strict().superRefine((request, context) => {
   if (request.prompt.length === 0 && (request.attachments?.length ?? 0) === 0 && (request.fileAttachments?.length ?? 0) === 0) {
@@ -21905,7 +21912,7 @@ var AndroidProtocolSchemas = {
   ProtocolError: ProtocolErrorSchema
 };
 
-// ../../shared/sdk/dist/chunks/chunk-UE4QYZCG.js
+// ../../shared/sdk/dist/chunks/chunk-CVWUKZX7.js
 var OwnerSchema = external_exports.object({ pid: external_exports.number().int().positive(), instanceId: external_exports.uuid().optional() });
 var PeerChatRequestSchema = external_exports.object({
   sessionId: IdSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentknight/client",
-  "version": "0.9.39",
+  "version": "0.9.40",
   "description": "AgentKnight PC Agent CLI for remote Copilot, PI and ACP coding sessions",
   "license": "Apache-2.0",
   "type": "module",
@@ -41,7 +41,7 @@
     "qrcode": "1.5.4",
     "qrcode-terminal": "0.12.0",
     "zod": "4.5.4",
-    "@agentknight/sdk": "0.9.39"
+    "@agentknight/sdk": "0.9.40"
   },
   "devDependencies": {
     "@types/qrcode": "1.5.6",
@@ -49,8 +49,8 @@
     "esbuild": "0.28.2",
     "sharp": "0.34.5",
     "socket.io-client": "4.8.3",
-    "@agentknight/shared": "0.1.0",
-    "@agentknight/protocol": "0.1.0"
+    "@agentknight/protocol": "0.1.0",
+    "@agentknight/shared": "0.1.0"
   },
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",