feat: add iSphere live probe recorder

2026-07-10 10:59:48 +08:00
parent 349fbe4a44
commit f7914a63dc
13 changed files with 2209 additions and 16 deletions
--- a/docs/source-discovery/2026-07-10-live-probe-recorder.md
+++ b/docs/source-discovery/2026-07-10-live-probe-recorder.md
@@ -0,0 +1,106 @@
+# iSphere Live Probe Recorder
+
+Date: 2026-07-10
+Purpose: collect read-only runtime evidence from a machine where iSphere / IMPlatformClient can actually log in.
+
+## Why this recorder exists
+
+The current development machine cannot log in because the current network has no reachable server. Simulating login would only prove window rendering and would not prove the real logged-in runtime state required by the B-route sidecar connector.
+
+Therefore the selected path is to carry a dedicated recorder executable to a working environment, run it after manual login, and bring the generated JSON evidence back.
+
+## Built artifact
+
+Package directory:
+
+```text
+runs/live-probe-recorder-package/
+```
+
+Executable:
+
+```text
+runs/live-probe-recorder-package/ISphereLiveProbeRecorder.exe
+```
+
+Zip package:
+
+```text
+runs/live-probe-recorder-package.zip
+```
+
+The package is generated by:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\package-live-probe-recorder.ps1
+```
+
+## Operator steps
+
+1. Copy `runs/live-probe-recorder-package.zip` to the machine/network where iSphere can connect to its server.
+2. Extract the zip.
+3. Manually open and log in to iSphere / `IMPlatformClient.exe`.
+4. Manually open one direct-contact chat window and one group-chat window if possible. Keep the editor/send/attachment area visible, but do not send anything.
+5. Keep the client window open.
+6. Double-click `ISphereLiveProbeRecorder.exe`.
+7. The program writes a folder under:
+
+```text
+probe-output/isphere-live-probe-<timestamp>/
+```
+
+8. Compress that generated folder and return it.
+
+## What it records
+
+The recorder writes:
+
+```text
+manifest.json
+probe_client_runtime.json
+process_details.json
+network_inventory.json
+filesystem_inventory.json
+services_registry_shortcuts.json
+scan_windows.json
+uia_summary.json
+uia/*.json
+feasibility_summary.json
+README.txt
+NEXT_STEP.txt
+```
+
+The important evidence is:
+
+- target process PID/name/title/path;
+- process bitness;
+- loaded module list;
+- command-line metadata with basic secret redaction;
+- key module presence, including `smack.dll`, `IMPP.Interface.dll`, `IMPP.ServiceBase.dll`, `IMPP.Service.dll`, `TcpFileTransfer.dll`;
+- visible window metadata;
+- UIA tree for target windows, useful if route A UI/RPA is needed later.
+- install/cache/config/log/database candidate metadata;
+- version and SHA256 for important binaries;
+- redacted text samples for small config/log files;
+- uninstall registry entries;
+- related services and shortcuts;
+- target-process TCP connections;
+- related named pipes.
+
+## What it does not do
+
+The recorder does not:
+
+- send messages;
+- send or upload files;
+- click UI;
+- type text;
+- inject hooks;
+- attach instrumentation;
+- modify client files or data.
+
+## Decision after returned evidence
+
+If `probe_client_runtime.json` proves the loaded modules and bitness match the static evidence, continue with B-route sidecar design.
+
+If the running client cannot be inspected, or the expected modules are absent, switch to the A-route constrained UI/RPA fallback.
--- a/docs/source-discovery/2026-07-10-send-sidecar-b-first-plan.md
+++ b/docs/source-discovery/2026-07-10-send-sidecar-b-first-plan.md
@@ -0,0 +1,357 @@
+# Send Connector B-First Plan
+
+Date: 2026-07-10
+Node: C29 / write-side connector route correction
+Decision owner: user/business manager
+
+## Decision
+
+The selected send route is now:
+
+1. **Primary route B: in-process / sidecar connector** that reuses the already logged-in `IMPlatformClient.exe` runtime and its existing message/file send classes.
+2. **Fallback route A: constrained UI/RPA wrapper** only if B cannot attach, load, or invoke safely.
+3. **Network replay/protocol reimplementation remains deferred** because it would require independently reproducing login/session/ack behavior.
+
+This document supersedes the previous C15/R5 conclusion for future send work. The old conclusion was correct for the evidence available at that time: no write connector had been selected. This node records the newly approved route and the evidence that makes B worth trying first.
+
+## Business goal
+
+Expose controlled MCP actions for digital employees:
+
+- `isphere_send_message`
+- `isphere_send_file`
+
+The implementation must preserve these business controls:
+
+- target must be resolved from existing contact/group search results;
+- text/file content must be previewed before execution;
+- execution must use an `idempotency_key` and content hash;
+- every outbound attempt must produce an audit record;
+- early versions should support sandbox/test-target verification before normal production use.
+
+## Static evidence summary
+
+Offline package evidence under:
+
+```text
+runs/offline-evidence-intake/zyl-qqfile-20260709/
+```
+
+Relevant extracted binaries:
+
+```text
+zyl/Impp/IMPlatformClient.exe
+zyl/Impp/smack.dll
+zyl/Impp/IMPP.Interface.dll
+zyl/Impp/IMPP.ServiceBase.dll
+zyl/Impp/IMPP.Service.dll
+zyl/Impp/TcpFileTransfer.dll
+zyl/Impp/HYHC.IMPP.DAL.dll
+```
+
+Relevant IL snapshots:
+
+```text
+runs/offline-evidence-intake/zyl-qqfile-20260709/metadata/c28-il/IMPlatformClient.exe.il
+runs/offline-evidence-intake/zyl-qqfile-20260709/metadata/c28-il/smack.dll.il
+runs/offline-evidence-intake/zyl-qqfile-20260709/metadata/c28-il/IMPP.Interface.dll.il
+runs/offline-evidence-intake/zyl-qqfile-20260709/metadata/c28-il/IMPP.Service.dll.il
+runs/offline-evidence-intake/zyl-qqfile-20260709/metadata/c28-il/IMPP.ServiceBase.dll.il
+```
+
+## Text-send call chain
+
+### Preferred sidecar candidate
+
+`IMPlatformClient.exe` contains a high-level helper:
+
+```text
+IMPP.Client.Core.Plugins.Manager.AppContextManager.SendTxtMessageByJid(jid, chatType, content)
+```
+
+Observed behavior from IL:
+
+- for direct/P2P chat, it gets a `P2PChatManager` from `IMPPManager.Instance`;
+- it resolves a `Chat` by JID;
+- it finds or opens a chat form;
+- it calls `frmP2PChat.SendTxtMessage(content)`;
+- for temporary/reserved group chat, it calls the corresponding room form send method.
+
+This is the best B-route first target because it reuses the logged-in client's own state and UI/business rules.
+
+### Central message construction candidate
+
+`IMPlatformClient.exe` also contains:
+
+```text
+IMPP.Client.Core.MessageEngine.MessageScheduling.SendChatMessage(chat, msgText, toJid, messageType, isSaveMessage, msgGuid, IsReceipt)
+```
+
+Observed behavior from IL:
+
+- reads local font/style settings;
+- builds message body via `UtilsText.GetMessageStyleBodyText`;
+- decides `chat` vs `groupchat`;
+- creates `smack.packet.XmppMessage`;
+- sets body, subject, offline flag, receipt flag, time, and message type;
+- calls `chat.SendMessage(xmppMessage)`;
+- optionally persists/parses message through `MessageManager.MessageParsing`.
+
+This is the cleanest lower-level B candidate if the sidecar can obtain a valid `Chat` object from the running client context.
+
+### Protocol bottom
+
+`smack.dll` provides the real wire-send chain:
+
+```text
+com.vision.smack.Chat.SendMessage(XmppMessage)
+  -> com.vision.smack.XMPPConnection.send(string)
+  -> Sharp.Xmpp.Core.XmppCore.Send(string)
+  -> stream.Write(...)
+```
+
+This proves that the send capability exists in the installed client binaries. It also shows why an external reimplementation is less attractive: it would need the same active connection, stanza format, message id, receipt, and session state.
+
+## Important trap: plugin interface text send is not enough
+
+`IMPP.Interface.dll` declares:
+
+```text
+IAppContextManager.SendP2PMessage(string pJid, string pMessage)
+IAppContextManager.SendP2PFiles(UserInfo[] pUserInfo, string[] pFiles)
+IAppContextManager.SendChatRoomMessage(string pRoomJid, string pMessage, string pluginID)
+IAppContextManager.SendPluginMessage(string pluginID, int command, string para)
+```
+
+But the implementation of:
+
+```text
+IMPP.Client.Core.Plugins.Manager.AppContextManager.SendP2PMessage(...)
+```
+
+records the plugin call and then throws `NotImplementedException`.
+
+Therefore the B route must **not** choose `SendP2PMessage` as the text-send entry. The sidecar should prefer `SendTxtMessageByJid` or, if necessary, `MessageScheduling.SendChatMessage` with an existing `Chat` object.
+
+## File-send call chain
+
+File sending appears split into upload plus file-message notification.
+
+### Upload engine
+
+`IMPP.ServiceBase.dll` defines `IFileTransfer`.
+
+`IMPP.Service.dll` implements:
+
+```text
+IMPP.Service.BLL.FileTransfer.FileUpload(...)
+IMPP.Service.BLL.FileTransfer.AsynFileUpload(...)
+IMPP.Service.BLL.FileTransfer.FileDownload(...)
+IMPP.Service.BLL.FileTransfer.SyncFileTransfer(...)
+```
+
+### Offline file send
+
+`IMPlatformClient.exe` contains:
+
+```text
+IMPP.Client.OffLineFileSend.sendFile()
+IMPP.Client.OffLineFileSend.trans_UploadCompleted(fileId)
+```
+
+Observed behavior:
+
+- builds a generated file GUID;
+- builds remote name as `filename____guid.ext`;
+- uses `Config.ServerInfo.HTTPFileServer` and `FileTransferManager.GetDomain`;
+- creates `FileUploadPara`;
+- calls `IMPPManager.Instance.Service.FileTransfer.FileUpload(uploadPara)`;
+- after upload completion, creates an `OFFLINE_FILE_TRANSFER;...` message body;
+- calls `Chat.sendFileMessage(...)`;
+- sets packet id to `fileId` and records metadata.
+
+### Native TCP file transfer
+
+`TcpFileTransfer.dll` is native and exposes strings/exports indicating:
+
+```text
+Send
+SendFile
+GetTcpFileMsgGuid
+_StartWaitForSendFileThread@8
+_StartRecvFileThread@24
+```
+
+This is a candidate for online/TCP file transfer, but the first B route should use the managed offline-file path because it is closer to the normal client business flow and already integrates upload metadata with XMPP file messages.
+
+## Proposed sidecar architecture
+
+```text
+Go MCP Server
+  -> controlled action contract and audit
+  -> C# WinHelper / Sidecar command
+  -> B-route sidecar adapter
+  -> running IMPlatformClient context
+  -> existing AppContextManager / MessageScheduling / OffLineFileSend / smack.dll
+```
+
+The sidecar should be a narrow adapter, not a general-purpose remote code executor.
+
+### Candidate sidecar operations
+
+```text
+version
+self_check
+probe_client_runtime
+probe_send_entrypoints
+resolve_runtime_jid
+preview_send_message
+send_message_after_approval
+preview_send_file
+send_file_after_approval
+read_send_audit
+```
+
+The first implementation slice should stop before real production send:
+
+```text
+version
+self_check
+probe_client_runtime
+probe_send_entrypoints
+```
+
+Then run a live sandbox observation before enabling `send_message_after_approval`.
+
+## B-route validation gates
+
+### Gate B1: runtime discovery
+
+Pass condition:
+
+- find a running `IMPlatformClient.exe` process;
+- record PID, bitness, install path, module list summary;
+- confirm the discovered path matches the extracted evidence family;
+- confirm whether the sidecar must be x86 or x64.
+
+Stop condition:
+
+- no logged-in process;
+- process bitness incompatible with available sidecar build;
+- module names differ too much from the extracted package.
+
+### Gate B2: entrypoint availability
+
+Pass condition:
+
+- confirm `IMPlatformClient.exe` exposes `AppContextManager` and `MessageScheduling` in the runtime module set;
+- confirm `smack.dll` is loaded or loadable from the same install directory;
+- confirm `IMPP.Interface.dll` and `IMPP.Service*.dll` are present.
+
+Stop condition:
+
+- app is not .NET Framework / cannot inspect CLR runtime safely;
+- required assemblies are missing;
+- only `SendP2PMessage` is available but `SendTxtMessageByJid`/`MessageScheduling` cannot be reached.
+
+### Gate B3: non-mutating dynamic observation
+
+Pass condition:
+
+- during one operator-approved manual test send, observe the expected chain:
+  - `SendTxtMessageByJid` or UI send method;
+  - `MessageScheduling.SendChatMessage`;
+  - `Chat.SendMessage`;
+  - `XMPPConnection.send`;
+- capture only redacted method names, argument shape, message id/hash, and success/ack indicator.
+
+Stop condition:
+
+- method chain differs from static evidence;
+- no success/ack indicator can be mapped;
+- message id/idempotency cannot be correlated.
+
+### Gate B4: sidecar dry run
+
+Pass condition:
+
+- sidecar can resolve the target JID/chat type;
+- sidecar can build a preview object without sending;
+- preview contains target, content hash, connector, and proposed entrypoint;
+- audit event is appended.
+
+Stop condition:
+
+- no deterministic target resolution;
+- preview cannot distinguish direct vs group chat;
+- no auditable dry-run object.
+
+### Gate B5: one sandbox send
+
+Pass condition:
+
+- one explicit test target only;
+- one idempotency key only;
+- one message content hash only;
+- success/ack or local sent-record evidence captured;
+- duplicate retry with same idempotency key is rejected locally.
+
+Stop condition:
+
+- duplicate send risk;
+- wrong target risk;
+- no post-send verification.
+
+## A-route fallback
+
+A remains the backup route if B cannot be made reliable.
+
+A should not be arbitrary desktop control. It should expose only:
+
+```text
+search_contact(query)
+open_conversation(target)
+write_draft(text)
+verify_draft(target, text_hash)
+send_after_approval(approval_id)
+upload_file(path)
+verify_send_result()
+```
+
+A-route fallback is activated when any of these happen:
+
+- B cannot attach/probe safely;
+- required runtime classes are unavailable in the logged-in process;
+- B can observe but cannot invoke without unstable side effects;
+- B cannot provide idempotency/audit guarantees;
+- sidecar bitness/runtime mismatch is too costly to resolve in the current cycle.
+
+## MCP contract impact
+
+The MCP business tools should not expose B/A internals directly. They should keep the stable user-facing shape:
+
+```text
+isphere_send_message(target_type, target_id, content_text, mode, idempotency_key, content_sha256)
+isphere_send_file(target_type, target_id, file_path, mode, idempotency_key, file_sha256)
+```
+
+Connector metadata should show the route:
+
+```text
+connector = "implatform-sidecar" | "uia-rpa"
+connector_stage = "preview" | "sandbox_send" | "production"
+```
+
+## Next implementation loop
+
+Next node should be **C30 B-route runtime probe**:
+
+1. Use the C# WinHelper read-only op `probe_client_runtime`.
+2. Probe running `IMPlatformClient.exe` process, bitness, path, loaded modules, and installed assembly presence.
+3. Do not send, click, type, upload, or attach hooks in this node.
+4. Write probe output to `runs/real-loggedin-lab/sidecar-probe/` if a live client is available.
+5. Update `capability-source-matrix.md` after B1/B2 pass or fail.
+
+## Current status
+
+B is selected as the primary send/file-send route. The first non-mutating runtime probe op has been added to `ISphereWinHelper` as `probe_client_runtime`; local verification passed with no target client running. The next executable work is to run that probe while the real iSphere/`IMPlatformClient.exe` client is logged in, then perform non-mutating entrypoint confirmation.
--- a/docs/source-discovery/README.md
+++ b/docs/source-discovery/README.md
@@ -12,6 +12,8 @@ Build the first business read capability path for `isphere_receive_messages` fro
 - `docs/source-discovery/2026-07-09-n12-pre-zyl-index.md`
 - `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md`
 - `docs/source-discovery/capability-source-matrix.md`
+- `docs/source-discovery/2026-07-10-send-sidecar-b-first-plan.md`
+- `docs/source-discovery/2026-07-10-live-probe-recorder.md`
 - `docs/mcp-core-tools-contract.md`
 - `docs/mcp-core-business-plan.md`

@@ -41,3 +43,7 @@ See `docs/superpowers/plans/2026-07-09-stage-c-log-backed-receive-messages-loop.
 ## Last completed discovery result

 Stage B2 showed that selected `MsgLib.db` files are not direct SQLite. Decrypted `PacketReader.ProcessPacket` XML is now the first implementable source for `isphere_receive_messages`.
+
+C29 corrected the write-side route after static binary evidence review and user decision: `isphere_send_message` should prioritize the running-client sidecar / in-process connector route, with constrained UI/RPA as fallback. The next write-side loop is a non-mutating B-route runtime probe.
+
+C30 adds a portable `ISphereLiveProbeRecorder.exe` package for environments where iSphere can actually log in. The recorder collects read-only runtime evidence and writes JSON output for B-route sidecar feasibility analysis.
--- a/docs/source-discovery/capability-source-matrix.md
+++ b/docs/source-discovery/capability-source-matrix.md
@@ -7,11 +7,12 @@ Schema notes: `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md`

 ## Source priority

-1. Existing bridge / API / local service.
-2. Local data, log, cache, or database source.
-3. UIA helper source through C# WinHelper.
-4. Network/protocol source.
-5. Mock source for tests only.
+1. Running-client sidecar / in-process connector that reuses the logged-in `IMPlatformClient.exe` runtime.
+2. Existing bridge / API / local service.
+3. Local data, log, cache, or database source.
+4. UIA helper source through C# WinHelper.
+5. Network/protocol source.
+6. Mock source for tests only.

 ## Matrix

@@ -21,8 +22,8 @@ Schema notes: `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md`
 | `isphere_search_contacts` | bare sender/receiver JIDs extracted from normalized log-backed messages loaded from configured PacketReader file or directory source | validated copied `MsgLib.db` tables: `TD_Roster`, `TD_CustomEffigy`, `tblRecent`, `tblChatLevel`, `tblPersonMsg`; decrypted roster/contact stanzas from `Smark.SendReceive`; UIA helper source if display names are still missing | `docs/source-discovery/2026-07-10-msglib-readonly-schema-extraction.md`; `internal/isphere/contacts_test.go`; `internal/tools/isphere_contacts_test.go` | C34 documents optional MsgLib contact display enrichment; R2 adds deterministic exact-match-first ranking, case-insensitive de-duplication across log/MsgLib candidates, and preserves `source`/`raw_ref` | core contact search complete; optional richer fields later |
 | `isphere_search_groups` | decrypted `PacketReader.ProcessPacket` `type="groupchat"` stanzas and conference/MUC JIDs loaded from configured PacketReader file or directory source | validated copied `MsgLib.db` tables: `tblMsgGroupPersonMsg`, `TD_WorkGroupAuth`, `tblRecent`; UIA helper source if group display names are still missing | `docs/source-discovery/2026-07-10-msglib-readonly-schema-extraction.md`; `internal/isphere/groups_test.go`; `internal/tools/isphere_groups_test.go`; C9 ignored-log scan: PacketReader 86 groupchat/86 conference hits; Smark 24 groupchat/658 conference/631 muc hits | C34 documents optional MsgLib group display enrichment; R2 adds deterministic exact-match-first ranking, case-insensitive de-duplication across log/MsgLib candidates, and preserves `source`/`raw_ref` | core group search complete; optional member/owner hierarchy later |
 | `isphere_receive_files` | decrypted `PacketReader.ProcessPacket` file-transfer message stanzas via `internal/isphere.ListFilesFromMessages` and `isphere_receive_files` list mode; configured PacketReader file or directory source; `zyl\importal\<hash>` cache entries remain unlinked | MsgLib `TD_ReceiveFileRecord` safe metadata through explicit copied-DB path; decrypted `Smark.SendReceive` and `SaveToDB` traces for file-reference reconciliation; future UIA/client connector for download | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#c12-file-transfer-evidence-precheck`; `docs/source-discovery/2026-07-10-file-download-mapping-precheck.md`; `docs/source-discovery/2026-07-10-file-cache-mapping-diagnostic.md` | C22 verifies safe file-list contract args; R3 confirms list metadata is available; R3b diagnostic finds 0 current cache/archive matches, so R4 remains blocked | blocked pending better cache evidence or UI/client download connector |
-| `isphere_send_message` | none validated yet | existing bridge/API/local service preferred; UIA write connector only after internal-sandbox action evidence; network/protocol connector only after protocol discovery | `docs/source-discovery/2026-07-10-send-message-source-precheck.md`; `docs/source-discovery/2026-07-10-send-message-connector-selection.md` | C15 and R5 blocked: contract exists, but no committed bridge/API/local service, helper write op, UIA action chain, or protocol connector is validated | blocked pending connector evidence package |
-| `isphere_send_file` | none validated yet | depends on send-message connector plus outbound file/upload evidence | `docs/source-discovery/2026-07-10-send-message-source-precheck.md`; `docs/source-discovery/2026-07-10-send-message-connector-selection.md` | blocked behind `isphere_send_message` connector selection and file upload/source policy; R5 found no send connector | blocked pending send connector evidence |
+| `isphere_send_message` | B-route selected: running-client sidecar / in-process connector, preferring `AppContextManager.SendTxtMessageByJid(...)` or `MessageScheduling.SendChatMessage(...)` over the unimplemented `SendP2PMessage(...)` interface path | A-route fallback: constrained UI/RPA wrapper only if B cannot pass runtime probe, entrypoint availability, dynamic observation, and idempotent dry-run gates; network/protocol replay remains deferred | `docs/source-discovery/2026-07-10-send-message-source-precheck.md`; `docs/source-discovery/2026-07-10-send-message-connector-selection.md`; `docs/source-discovery/2026-07-10-send-sidecar-b-first-plan.md` | C29 route correction: previous C15/R5 block remains historical evidence; user approved B primary and A backup. Static IL evidence identifies the client-side send chain `IMPlatformClient.exe -> smack.dll`, but no runtime sidecar send is implemented yet | next: C30 B-route runtime probe, then non-mutating manual-send observation before enabling sandbox send |
+| `isphere_send_file` | B-route selected after send-message probe: managed offline-file path through `OffLineFileSend.sendFile()`, `IMPP.Service*.dll` `IFileTransfer.FileUpload(...)`, and `Chat.sendFileMessage(...)` | A-route fallback: constrained UI/RPA upload/send-file flow; native `TcpFileTransfer.dll` is a later candidate only after managed path is rejected | `docs/source-discovery/2026-07-10-send-message-source-precheck.md`; `docs/source-discovery/2026-07-10-send-message-connector-selection.md`; `docs/source-discovery/2026-07-10-send-sidecar-b-first-plan.md` | C29 route correction: static IL evidence identifies upload-plus-file-message chain, but runtime probe and one approved sandbox file-send observation are still required | next: wait for C30/C31 message-send probe; then C32 file-send runtime/upload probe |

 ## Stage C entry rule