hap-cli 0.8.6__tar.gz → 0.8.7__tar.gz

{hap_cli-0.8.6 → hap_cli-0.8.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hap-cli
-Version: 0.8.6
+Version: 0.8.7
 Summary: CLI harness for MingDAO HAP - Enterprise no-code platform
 Author: hap-cli
 License: Apache-2.0
@@ -40,6 +40,15 @@ pip install hap-cli
 The package ships with the v3 tool schemas it needs, so no extra setup is
 required after `pip install`.
 
+## Prerequisite: enable CLI access for your organization
+
+**`hap` can only access an organization's data after the organization has
+enabled CLI access.** Ask an organization administrator to turn on the
+switch under Organization Admin → Security → Data & Access → CLI access
+policy. Commands are blocked until it is enabled; once an administrator
+turns it on, just re-run the command. Use `hap auth list-my-orgs` to see
+each organization's status (`CLI:on/off`).
+
 ## Quick start
 
 ### 1. Login
@@ -102,8 +111,9 @@ hap app select APP_ID
 hap app unselect                     # clear it
 ```
 
-`hap auth set-current-org` only changes the default organization. The default app
-is managed independently with `hap app select` / `hap app unselect`.
+`hap auth set-current-org` switches the default organization; moving to a
+different organization also clears the default app (apps belong to an
+organization). Pick a new one with `hap app select`.
 
 ### 3. Explore worksheets and records
 
@@ -140,8 +150,8 @@ discover every subcommand.
 | `auth use NAME` | Switch the environment/account used next |
 | `auth logout` | Log out the current account (`-p NAME` for a specific one, `-a/--all` for every one) |
 | `auth whoami` | Show current user, current environment/account, and current organization |
-| `auth list-my-orgs` | List every org for the current account (current marked `*`) |
-| `auth set-current-org ORG_ID` | Switch the saved current organization |
+| `auth list-my-orgs` | List every org for the current account (current marked `*`; each row shows whether the org allows CLI access, `CLI:on/off`, checked live; omitted where the environment has no such switch) |
+| `auth set-current-org ORG_ID` | Switch the saved current organization (clears the default app when the org changes) |
 
 ### app — application management
 
@@ -322,22 +332,6 @@ overrides the persisted level.
 
 ---
 
-## Organization CLI access control
-
-Organizations can control whether CLI tools are allowed to call their
-APIs. Before each command runs, `hap` checks this setting for the
-current organization:
-
-- **Enabled** — the command runs normally; the result is remembered for
-  5 minutes, so back-to-back commands stay fast.
-- **Disabled** — the command is blocked with a message asking you to
-  contact an organization administrator to enable CLI access.
-- **Setting not available** (older server versions) — the command runs
-  normally; the check is retried about once an hour.
-
-If an administrator enables access after a command was blocked, just
-re-run the command — the change takes effect immediately.
-
 ## Default app & organization
 
 Every command that needs an `--app-id` resolves it in this order:
@@ -346,8 +340,8 @@ Every command that needs an `--app-id` resolves it in this order:
 2. The default app saved by `hap app select`;
 3. Otherwise the command exits with an error suggesting `hap app select APP_ID`.
 
-`hap auth set-current-org` changes the default *organization* only — it does not
-touch the default app.
+`hap auth set-current-org` switches the default *organization*; switching to a
+different organization also clears the default app.
 
 ## REPL mode
 

{hap_cli-0.8.6/hap_cli → hap_cli-0.8.7}/README.md

@@ -11,6 +11,15 @@ pip install hap-cli
 The package ships with the v3 tool schemas it needs, so no extra setup is
 required after `pip install`.
 
+## Prerequisite: enable CLI access for your organization
+
+**`hap` can only access an organization's data after the organization has
+enabled CLI access.** Ask an organization administrator to turn on the
+switch under Organization Admin → Security → Data & Access → CLI access
+policy. Commands are blocked until it is enabled; once an administrator
+turns it on, just re-run the command. Use `hap auth list-my-orgs` to see
+each organization's status (`CLI:on/off`).
+
 ## Quick start
 
 ### 1. Login
@@ -73,8 +82,9 @@ hap app select APP_ID
 hap app unselect                     # clear it
 ```
 
-`hap auth set-current-org` only changes the default organization. The default app
-is managed independently with `hap app select` / `hap app unselect`.
+`hap auth set-current-org` switches the default organization; moving to a
+different organization also clears the default app (apps belong to an
+organization). Pick a new one with `hap app select`.
 
 ### 3. Explore worksheets and records
 
@@ -111,8 +121,8 @@ discover every subcommand.
 | `auth use NAME` | Switch the environment/account used next |
 | `auth logout` | Log out the current account (`-p NAME` for a specific one, `-a/--all` for every one) |
 | `auth whoami` | Show current user, current environment/account, and current organization |
-| `auth list-my-orgs` | List every org for the current account (current marked `*`) |
-| `auth set-current-org ORG_ID` | Switch the saved current organization |
+| `auth list-my-orgs` | List every org for the current account (current marked `*`; each row shows whether the org allows CLI access, `CLI:on/off`, checked live; omitted where the environment has no such switch) |
+| `auth set-current-org ORG_ID` | Switch the saved current organization (clears the default app when the org changes) |
 
 ### app — application management
 
@@ -293,22 +303,6 @@ overrides the persisted level.
 
 ---
 
-## Organization CLI access control
-
-Organizations can control whether CLI tools are allowed to call their
-APIs. Before each command runs, `hap` checks this setting for the
-current organization:
-
-- **Enabled** — the command runs normally; the result is remembered for
-  5 minutes, so back-to-back commands stay fast.
-- **Disabled** — the command is blocked with a message asking you to
-  contact an organization administrator to enable CLI access.
-- **Setting not available** (older server versions) — the command runs
-  normally; the check is retried about once an hour.
-
-If an administrator enables access after a command was blocked, just
-re-run the command — the change takes effect immediately.
-
 ## Default app & organization
 
 Every command that needs an `--app-id` resolves it in this order:
@@ -317,8 +311,8 @@ Every command that needs an `--app-id` resolves it in this order:
 2. The default app saved by `hap app select`;
 3. Otherwise the command exits with an error suggesting `hap app select APP_ID`.
 
-`hap auth set-current-org` changes the default *organization* only — it does not
-touch the default app.
+`hap auth set-current-org` switches the default *organization*; switching to a
+different organization also clears the default app.
 
 ## REPL mode
 

{hap_cli-0.8.6 → hap_cli-0.8.7/hap_cli}/README.md

@@ -11,6 +11,15 @@ pip install hap-cli
 The package ships with the v3 tool schemas it needs, so no extra setup is
 required after `pip install`.
 
+## Prerequisite: enable CLI access for your organization
+
+**`hap` can only access an organization's data after the organization has
+enabled CLI access.** Ask an organization administrator to turn on the
+switch under Organization Admin → Security → Data & Access → CLI access
+policy. Commands are blocked until it is enabled; once an administrator
+turns it on, just re-run the command. Use `hap auth list-my-orgs` to see
+each organization's status (`CLI:on/off`).
+
 ## Quick start
 
 ### 1. Login
@@ -73,8 +82,9 @@ hap app select APP_ID
 hap app unselect                     # clear it
 ```
 
-`hap auth set-current-org` only changes the default organization. The default app
-is managed independently with `hap app select` / `hap app unselect`.
+`hap auth set-current-org` switches the default organization; moving to a
+different organization also clears the default app (apps belong to an
+organization). Pick a new one with `hap app select`.
 
 ### 3. Explore worksheets and records
 
@@ -111,8 +121,8 @@ discover every subcommand.
 | `auth use NAME` | Switch the environment/account used next |
 | `auth logout` | Log out the current account (`-p NAME` for a specific one, `-a/--all` for every one) |
 | `auth whoami` | Show current user, current environment/account, and current organization |
-| `auth list-my-orgs` | List every org for the current account (current marked `*`) |
-| `auth set-current-org ORG_ID` | Switch the saved current organization |
+| `auth list-my-orgs` | List every org for the current account (current marked `*`; each row shows whether the org allows CLI access, `CLI:on/off`, checked live; omitted where the environment has no such switch) |
+| `auth set-current-org ORG_ID` | Switch the saved current organization (clears the default app when the org changes) |
 
 ### app — application management
 
@@ -293,22 +303,6 @@ overrides the persisted level.
 
 ---
 
-## Organization CLI access control
-
-Organizations can control whether CLI tools are allowed to call their
-APIs. Before each command runs, `hap` checks this setting for the
-current organization:
-
-- **Enabled** — the command runs normally; the result is remembered for
-  5 minutes, so back-to-back commands stay fast.
-- **Disabled** — the command is blocked with a message asking you to
-  contact an organization administrator to enable CLI access.
-- **Setting not available** (older server versions) — the command runs
-  normally; the check is retried about once an hour.
-
-If an administrator enables access after a command was blocked, just
-re-run the command — the change takes effect immediately.
-
 ## Default app & organization
 
 Every command that needs an `--app-id` resolves it in this order:
@@ -317,8 +311,8 @@ Every command that needs an `--app-id` resolves it in this order:
 2. The default app saved by `hap app select`;
 3. Otherwise the command exits with an error suggesting `hap app select APP_ID`.
 
-`hap auth set-current-org` changes the default *organization* only — it does not
-touch the default app.
+`hap auth set-current-org` switches the default *organization*; switching to a
+different organization also clears the default app.
 
 ## REPL mode
 

{hap_cli-0.8.6 → hap_cli-0.8.7}/hap_cli/README_CN.md

@@ -10,6 +10,10 @@ pip install hap-cli
 
 安装包内已附带 CLI 启动需要的 v3 工具 schema，`pip install` 之后无需额外配置。
 
+## 使用前提：开启组织的 CLI 访问权限
+
+**只有组织开启了 CLI 访问权限，`hap` 才能访问该组织的数据。** 请组织管理员前往「组织管理后台 → 安全 → 数据与访问 → CLI 访问策略」开启允许访问开关。未开启时命令会被拦截；管理员开启后直接重跑命令即可。可用 `hap auth list-my-orgs` 查看各组织的开启状态（`CLI:on/off`）。
+
 ## 快速上手
 
 ### 1. 登录
@@ -67,7 +71,7 @@ hap app select APP_ID
 hap app unselect                     # 清除默认应用
 ```
 
-`hap auth set-current-org` 只切换默认组织，不会改写默认应用。默认应用通过 `hap app select` / `hap app unselect` 单独管理。
+`hap auth set-current-org` 切换默认组织；切换到不同组织时会同时清除默认应用（应用从属于组织）。之后用 `hap app select` 重新选择默认应用。
 
 ### 3. 浏览工作表与记录
 
@@ -102,8 +106,8 @@ hap --json worksheet record list WORKSHEET_ID
 | `auth use NAME` | 切换当前使用的环境/账号 |
 | `auth logout` | 登出当前账号（`-p NAME` 指定，`-a/--all` 全部） |
 | `auth whoami` | 当前用户、当前环境/账号与当前组织 |
-| `auth list-my-orgs` | 当前账号所属组织（当前组织标 `*`） |
-| `auth set-current-org ORG_ID` | 切换默认组织 |
+| `auth list-my-orgs` | 当前账号所属组织（当前组织标 `*`，并实时显示各组织是否开启 CLI 访问权限 `CLI:on/off`，环境不支持该开关时不显示） |
+| `auth set-current-org ORG_ID` | 切换默认组织（切到不同组织时会清除默认应用） |
 
 ### app — 应用管理
 
@@ -269,18 +273,6 @@ hap --json worksheet record list WORKSHEET_ID
 
 ---
 
-## 组织 CLI 访问控制
-
-组织可以控制是否允许 CLI 工具调用其接口。每条命令运行前，`hap`
-会检查当前组织的这项设置：
-
-- **已开启** — 命令正常执行；结果保留 5 分钟，连续命令不会变慢。
-- **已关闭** — 命令被拦截，并提示联系组织管理员开启 CLI 访问权限。
-- **服务器暂不支持该设置**（旧版本环境）— 命令正常执行，约每小时
-  重试一次检查。
-
-如果命令被拦后管理员开启了权限，直接重跑命令即可，立即生效。
-
 ## 默认应用与组织
 
 任何需要 `--app-id` 的命令解析顺序：
@@ -289,7 +281,7 @@ hap --json worksheet record list WORKSHEET_ID
 2. 否则使用 `hap app select APP_ID` 保存的默认应用；
 3. 仍为空时报错并提示设置默认应用。
 
-`hap auth set-current-org` 切换的是默认**组织**，**不**会改默认应用。
+`hap auth set-current-org` 切换默认**组织**；切到不同组织时会同时清除默认应用。
 
 ## REPL 模式
 

{hap_cli-0.8.6 → hap_cli-0.8.7}/hap_cli/__init__.py

@@ -1,3 +1,3 @@
 """CLI harness for MingDAO HAP (hap-cli)."""
 
-__version__ = "0.8.6"
+__version__ = "0.8.7"

{hap_cli-0.8.6 → hap_cli-0.8.7}/hap_cli/commands/auth_cmd.py

@@ -102,6 +102,21 @@ def _save_and_report(ctx, token, webui, user_info, meta, profile_name):
     session.save(profile=profile_name)
     set_active_profile(profile_name)
 
+    # Probe the org CLI-access switch for the org we just saved as
+    # current, so the user learns right away that commands will be
+    # blocked. Only an explicit "off" verdict prints the warning
+    # (404 / network trouble stays silent — same fail-open policy as
+    # the request gate). Covers all login paths (browser, paste,
+    # --token), unlike the browser success page.
+    from hap_cli.core import cli_access
+
+    access_denied = False
+    if cli_access.GATE_ENABLED and current_org.get("projectId"):
+        access_denied = (
+            cli_access.probe_cli_access(webui, token, current_org["projectId"])
+            is False
+        )
+
     data = {
         "status": "ok",
         "profile": profile_name,
@@ -109,17 +124,24 @@ def _save_and_report(ctx, token, webui, user_info, meta, profile_name):
         "user": user_info,
         "current_org": current_org,
     }
-    ctx.output(
-        data,
-        lambda d: click.echo(
+    if access_denied:
+        data["cli_access_denied"] = True
+
+    def _human(_d):
+        click.echo(
             f"Logged in as: {user_info.get('name', '')} "
             f"({user_info.get('email', '')})\n"
             f"Saved as: {profile_name}\n"
             f"Server: {webui}\n"
             f"Current org: {current_org.get('projectId', '')} "
             f"{current_org.get('companyName', '')}".rstrip()
-        ),
-    )
+        )
+        if access_denied:
+            # Deliberately NOT localized: the surrounding login summary
+            # is English-only, so this line stays English too.
+            click.echo(f"Error: {cli_access.DENIED_MESSAGE_EN}")
+
+    ctx.output(data, _human)
 
 
 @auth.command("login")
@@ -290,17 +312,33 @@ def _print_orgs(session, data):
         pid = p.get("projectId", "")
         name = p.get("companyName", p.get("name", ""))
         role = p.get("roleName", "")
-        marker = "*" if pid and pid == current_org_id else " "
-        click.echo(f"{marker} {pid}  {name}  {role}".rstrip())
+        # Only render the CLI column when the server gave an explicit
+        # verdict; environments without the org switch show no column.
+        enabled = p.get("cliAccessEnabled")
+        cli_col = ""
+        if isinstance(enabled, bool):
+            cli_col = "CLI:on" if enabled else "CLI:off"
+        click.echo(
+            f"{'*' if pid and pid == current_org_id else ' '} "
+            f"{pid}  {name}  {role}  {cli_col}".rstrip()
+        )
 
 
 @auth.command("list-my-orgs")
 @pass_context
 def auth_list_my_orgs(ctx):
-    """List all organizations the current user belongs to."""
+    """List all organizations the current user belongs to.
+
+    Each row also shows whether the organization currently allows
+    CLI access (checked live against the server).
+    """
     try:
+        from hap_cli.core import cli_access
+
         session = ctx.get_session()
         data = auth_mod.list_my_orgs(session)
+        if cli_access.GATE_ENABLED:
+            cli_access.annotate_orgs_cli_access(session, data)
         ctx.output(data, lambda d: _print_orgs(session, d))
     except Exception as e:
         ctx.handle_error(e)
@@ -314,6 +352,9 @@ def auth_set_current_org(ctx, org_id):
 
     Run 'hap auth list-my-orgs' first to see the organizations you
     belong to and their IDs.
+
+    Switching to a different organization also clears the saved
+    default app — pick a new one with 'hap app select' afterwards.
     """
     try:
         session = ctx.get_session()

{hap_cli-0.8.6 → hap_cli-0.8.7}/hap_cli/commands/record_cmd.py

@@ -155,6 +155,10 @@ def record_update(ctx, worksheet_id, row_id, field, fields_json, no_workflow):
 
     Pass values either as repeated -f CONTROL_ID=VALUE pairs or as one
     --fields-json array.
+
+    A sub-table value is the full list of child rows (each a dict keyed
+    by child field name) and replaces the existing rows; an empty list
+    clears the sub-table.
     """
     if field and fields_json:
         raise click.UsageError("Pass exactly one of -f or --fields-json.")
@@ -164,7 +168,8 @@ def record_update(ctx, worksheet_id, row_id, field, fields_json, no_workflow):
             raw = _fields_json_to_raw(fields_json)
         else:
             raw = _parse_fields(field)
-        controls = rec_mod.encode_controls_by_id(session, worksheet_id, raw)
+        controls = rec_mod.encode_controls_by_id(
+            session, worksheet_id, raw, for_update=True)
         data = rec_mod.update_record(
             session, worksheet_id, row_id, controls,
             trigger_workflow=not no_workflow,

{hap_cli-0.8.6 → hap_cli-0.8.7}/hap_cli/commands/workflow_cmd.py

@@ -63,7 +63,7 @@ def workflow_list(ctx, app_id, keyword, enabled, page_size, page):
         if not aid:
             raise click.UsageError("App ID required.")
         result = wf_mod.get_process_list(
-            session, aid, keyword=keyword,
+            session, aid, keyword=keyword, enabled=enabled,
             page_index=page, page_size=page_size,
         )
         ctx.output(

{hap_cli-0.8.6 → hap_cli-0.8.7}/hap_cli/commands/worksheet_cmd.py

@@ -605,17 +605,34 @@ def worksheet_delete_view(ctx, worksheet_id, view_id, app_id, yes):
               help="Comma-separated advancedSetting sub-keys to update "
                    "(narrows an advancedSetting edit so unrelated "
                    "settings survive).")
+@click.option("--view-spec", default="",
+              help="High-level view JSON (same shape as 'view create "
+                   "--view-spec') applied onto this existing view. "
+                   "Everything the spec expresses is updated; other "
+                   "settings are preserved. Field references may be "
+                   "names, aliases or control IDs. When given, the "
+                   "other options are ignored.")
 @click.option("--app-id", "-a", default="", help="Application ID")
 @pass_context
 def worksheet_update_view(ctx, worksheet_id, view_id, name, view_json,
-                          edit_attrs, edit_ad_keys, app_id):
+                          edit_attrs, edit_ad_keys, view_spec, app_id):
     """Update a view's properties in place.
 
     Only the attributes named in --edit-attrs are changed; all other
     view settings are left as they are. For a simple rename, just pass
-    --name.
+    --name. To rewrite the view from a high-level description (grouping,
+    filters, quick filters, left-nav categories, cards, action buttons),
+    pass --view-spec.
     """
     try:
+        if view_spec:
+            session = ctx.get_session()
+            data = ws_mod.update_view_spec(
+                session, worksheet_id, view_id, json.loads(view_spec),
+                app_id=app_id,
+            )
+            ctx.output(data, lambda d: output_json(d))
+            return
         view: dict = json.loads(view_json) if view_json else {}
         attrs = [a.strip() for a in edit_attrs.split(",") if a.strip()]
         if name:

{hap_cli-0.8.6 → hap_cli-0.8.7}/hap_cli/core/action_spec_adapter.py

@@ -28,10 +28,14 @@ Wire semantics (authoritative: pd-openweb
   * ``filters`` — the enableWhen gating condition (same wire shape as a
     view filter; built via ``filter_translator``)
 
-Every button, regardless of type, gets a behind-the-scenes "shadow"
-workflow on the server. Its ``processId`` (and trigger node id) is
-fetched after creation via
-``GET /workflow/process/getProcessByTriggerId?appId=&triggerId=<btnId>``.
+A button that drives a workflow (``clickType`` 1 or ``workflowType`` 1)
+gets a behind-the-scenes "shadow" workflow on the server. Its
+``processId`` (and trigger node id) is resolved after creation via
+``GET /workflow/process/getProcessByTriggerId?appId=&triggerId=<btnId>``
+— note that GET lazily *creates* the shadow process when missing, so it
+must only be called for workflow-driving buttons (the frontend gates it
+the same way: CreateCustomBtn.jsx ``getProcessByTriggerId``, and skips
+the editor entirely for 填写指定内容+不执行 buttons).
 """
 from __future__ import annotations
 
@@ -62,19 +66,24 @@ def build_button_payload(spec: dict[str, Any]) -> dict[str, Any]:
         # wins. Evidence: sources/v3-design/2026-06-10-mcp-tools/
         # mcp_json_schema.json#create_custom_actions.
         "desc": spec.get("desc", spec.get("remark", "")),
-        # workflowType 1 = the button drives a (shadow) worksheet workflow.
-        "workflowType": 1,
         "isAllView": spec.get("isAllView", 1),
     }
 
     confirm = spec.get("confirm")
     confirm_msg = spec.get("confirmMsg")
 
+    # workflowType: 1 = 执行（按钮驱动一条 shadow 工作流） · 2 = 不执行。
+    # Fill-type buttons default to 2 (no workflow) — the frontend only
+    # creates the shadow process for clickType 1 / workflowType 1 buttons
+    # (CreateCustomBtn.jsx:353 "创建时，除'填写指定内容+不执行'外，直接进入
+    # 编辑流"). triggerWorkflow buttons are exactly the workflow-driving
+    # kind, so they keep 1. runWorkflowAfterSubmit (below) overrides.
     if action_type == "updateCurrentRecord":
         # 填写本记录字段。
         out["clickType"] = 3
         out["writeType"] = 1
         out["writeObject"] = 1
+        out["workflowType"] = 2
         out["writeControls"] = [
             {"controlId": cid, "type": _WRITE_CONTROL_FILL}
             for cid in (spec.get("updateFields") or [])
@@ -84,6 +93,7 @@ def build_button_payload(spec: dict[str, Any]) -> dict[str, Any]:
         out["clickType"] = 3
         out["writeType"] = 2
         out["writeObject"] = 2
+        out["workflowType"] = 2
         rel = spec.get("relationField", "")
         out["addRelationControlId"] = rel
         out["relationControl"] = spec.get("relationControl", "")
@@ -92,6 +102,7 @@ def build_button_payload(spec: dict[str, Any]) -> dict[str, Any]:
         out["clickType"] = 2 if (confirm or confirm_msg) else 1
         out["writeType"] = ""
         out["writeObject"] = ""
+        out["workflowType"] = 1
 
     # 二次确认文案（任意类型都可带）。
     if confirm or confirm_msg:

{hap_cli-0.8.6 → hap_cli-0.8.7}/hap_cli/core/auth.py

@@ -264,6 +264,12 @@ def switch_org(session, org_id: str) -> dict:
     orgs = list_my_orgs(session)
     for org in orgs:
         if org.get("projectId") == org_id:
+            # Apps live inside an organization, so a default app saved
+            # under the previous org is meaningless (or worse, wrong)
+            # after the switch — drop it. A no-op "switch" to the org
+            # already current keeps the default app.
+            if session.default_project_id != org_id:
+                session.default_app_id = ""
             session.default_project_id = org_id
             # Refresh routing table + default org name from the server of
             # record. Failures here should NOT block the org switch — the

{hap_cli-0.8.6 → hap_cli-0.8.7}/hap_cli/core/chat.py

@@ -37,6 +37,13 @@ def _chatmq_get(
 
     from hap_cli.core.session import hap_user_agent
 
+    # Chat is a cross-org service (sessions span networks), so chatmq has
+    # no org of its own to check — the CLI access gate runs against the
+    # CURRENT org instead, same as ``Session._post``. Lazy import to
+    # mirror the other transport hooks.
+    from hap_cli.core import cli_access
+
+    cli_access.ensure_before_request(session, url)
     headers = {
         "Authorization": f"md_pss_id {session.auth_token}",
         "X-Requested-With": "XMLHttpRequest",
@@ -389,6 +396,14 @@ def _socket_emit(
         return None
 
     ws_base = session.chat_ws_base()
+    # Chat is a cross-org service, so the websocket channel is gated
+    # against the CURRENT org (same policy as ``_chatmq_get``). The gate
+    # runs OUTSIDE the strict/swallow try below: a policy denial must
+    # propagate even for fire-and-forget emits, unlike transport errors.
+    from hap_cli.core import cli_access
+    from hap_cli.core.session import hap_user_agent
+
+    cli_access.ensure_before_request(session, ws_base)
     # pd-openweb passes the session token as a `pss_id` query string on
     # the socket.io handshake (src/socket/index.js -> `query: { pss_id }`).
     connect_url = f"{ws_base}?pss_id={session.auth_token}"
@@ -400,6 +415,7 @@ def _socket_emit(
             connect_url,
             socketio_path="/mds2",
             transports=["websocket"],
+            headers={"User-Agent": hap_user_agent()},
             wait_timeout=10,
         )
         logger.info("SOCKET emit %r payload=%s", event, payload)
@@ -407,10 +423,20 @@ def _socket_emit(
         logger.info("SOCKET %r -> ack=%s", event, ack)
         return ack
     except Exception as exc:
+        # engineio masks the underlying handshake failure (TLS verify,
+        # proxy, 4xx upgrade rejection) behind a generic 'Connection
+        # error' — log with exc_info so the chained original exception
+        # lands in the log for diagnosis.
         if strict:
-            logger.error("Failed to emit %s payload=%s: %s", event, payload, exc)
+            logger.error(
+                "Failed to emit %s payload=%s: %s", event, payload, exc,
+                exc_info=True,
+            )
             raise
-        logger.warning("Failed to emit %s payload=%s: %s", event, payload, exc)
+        logger.warning(
+            "Failed to emit %s payload=%s: %s", event, payload, exc,
+            exc_info=True,
+        )
         return None
     finally:
         try: