isphere-ai-bridge/docs/superpowers/plans/2026-07-12-b-route-bridge-next-plan.md

B-Route Bridge Next Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Push the primary B-route from a dry-run shell toward a verifiable sidecar/API bridge without enabling real send yet.

Architecture: Keep the Go MCP tool contracts stable. B-route remains the primary product route: reuse the logged-in IMPlatformClient.exe runtime through a narrow sidecar/API bridge if a safe bridge transport exists. A-route/RPA remains backup-only and should be used only for UI action smoke or when B-route is proven blocked.

Tech Stack: Go 1.23.4, github.com/modelcontextprotocol/go-sdk, Windows PowerShell, .NET Framework C# helper/sidecar, stdin/stdout JSON protocols, Windows UI Automation only as fallback.

Global Constraints

• Repository root: E:\coding\codex\isphere-ai-bridge.
• Active branch for execution should be a new codex/ branch, not main directly.
• Do not use rg; use git ls-files, ag, grep -R, or PowerShell commands.
• Local machine cannot log in to iSphere; local work must use static analysis, fake sidecar processes, synthetic fixtures, or offline real-window UI only.
• B-route is primary: running-client sidecar / in-process connector / existing API comes before A-route/RPA.
• A-route/RPA is backup-only: keep it runnable, but do not make it the default product architecture.
• No real send/file upload in this plan. Stop at bridge feasibility, self_check, runtime probe, and dry-run preview.
• Keep audit redaction: do not store raw message body, raw idempotency key, raw file contents, or raw local file paths in committed outputs.

---

Offline reverse amendment

Because the next working day has no logged-in iSphere environment, execute docs/superpowers/plans/2026-07-12-offline-broute-reverse-plan.md before the online evidence/package tasks. This keeps B-route primary while using offline static reverse evidence to decide IPC/plugin/in-process/preview-only feasibility. A-route/RPA remains backup-only.

Current evidence summary

The current main state already has:

• isphere_send_message MCP contract, preview/dry-run metadata, audit, idempotency, and connector abstraction.
• internal/tools/send_message_broute_adapter.go with B-route disabled and dry_run_contract modes only.
• internal/tools/send_message_uia_adapter.go wired from env only for ISPHERE_SEND_CONNECTOR_MODE=uia_rpa.
• C# WinHelper probe_client_runtime, probe_send_entrypoints, probe_send_uia_controls, and uia_send_message.
• Offline real frmP2PChat opener for RPA backup validation.
• No B-route env wiring, no process-backed B-route sidecar client, no in-process bridge transport decision, and no real send/file-upload connector.

Important technical conclusion: an external C# process cannot automatically reuse the logged-in static runtime of IMPlatformClient.exe. Before building send invocation, the next B-route node must decide the bridge transport: existing API/IPC, plugin/extension loading, in-process adapter, or fallback.

---

Task 1: B-route bridge transport feasibility report

Files:

• Create: docs/source-discovery/2026-07-12-b-route-bridge-feasibility.md
• Modify: docs/source-discovery/capability-source-matrix.md

Interfaces:

• Consumes: existing docs docs/source-discovery/2026-07-10-send-sidecar-b-first-plan.md, docs/source-discovery/2026-07-10-send-connector-preflight.md, and current Go/C# connector files.

• Produces: a route decision table with exact choices: existing_ipc, plugin_extension, in_process_adapter, external_dry_run_only, or fallback_rpa.

• Re-read current B-route evidence.

Run:

Get-Content -LiteralPath docs\source-discovery\2026-07-10-send-sidecar-b-first-plan.md
Get-Content -LiteralPath docs\source-discovery\2026-07-10-send-connector-preflight.md
Get-Content -LiteralPath internal\tools\send_message_broute_adapter.go
Get-Content -LiteralPath internal\tools\send_message_uia_adapter.go

Expected: confirm B-route entrypoint names exist, but no bridge transport is implemented.

• Write the feasibility report with this required conclusion block:

## Decision

B-route remains primary. The immediate next implementation is not production send; it is bridge transport selection plus dry-run sidecar plumbing.

| Candidate | Can reuse logged-in runtime? | Local feasibility | Next action |
| --- | --- | --- | --- |
| existing_ipc/local_service | unknown | inspect live probe named pipes/services/network metadata | continue if concrete API appears |
| plugin_extension | unknown | inspect install/plugin loader evidence | continue if client loads local plugin DLL/exe |
| in_process_adapter | possible but highest risk | requires explicit bridge mechanism | defer until IPC/plugin ruled out |
| external_dry_run_only | cannot reuse logged-in static runtime | useful for protocol/client tests only | implement as non-mutating sidecar boundary |
| fallback_rpa | can drive UI only | already backup-ready | keep as backup, not primary |

• Update capability-source-matrix.md so the next slice says: “B-route bridge transport feasibility and dry-run sidecar boundary”, not “RPA send”.

• Verify docs.

Run:

git diff --check

Expected: exit 0.

Task 2: Add B-route connector env selection without starting real send

Files:

• Modify: internal/tools/send_message_uia_adapter.go or split env loading into internal/tools/send_message_connector_env.go
• Modify: internal/tools/send_message_uia_adapter_test.go or create internal/tools/send_message_connector_env_test.go
• Modify: docs/go-mcp-runbook.md

Interfaces:

• Consumes: NewBRouteSendMessageConnector(BRouteSendAdapterConfig).

• Produces: NewSendMessageConnectorFromEnv() supports:

  • ISPHERE_SEND_CONNECTOR_MODE=broute_dry_run
  • ISPHERE_SEND_CONNECTOR_MODE=broute_sidecar
  • ISPHERE_SEND_BROUTE_MODE=disabled|dry_run_contract|sidecar_preview
  • ISPHERE_SEND_BROUTE_SIDECAR_EXE=<path>
  • ISPHERE_SEND_BROUTE_TIMEOUT_SECONDS=<positive int>

• Write failing env-loader tests.

Test cases:

mode empty -> nil connector
mode uia_rpa -> existing UIA connector
mode broute_dry_run -> B-route connector mode dry_run_contract
mode broute_sidecar without sidecar exe -> connector returns blocked sidecar config error, not panic

Run:

go test ./internal/tools -run "TestNewSendMessageConnectorFromEnv" -count=1

Expected before implementation: fail for B-route modes.

• Implement env parsing with no real send.

Required behavior:

broute_dry_run -> NewBRouteSendMessageConnector(BRouteSendAdapterConfig{Mode:"dry_run_contract"})
broute_sidecar -> NewBRouteSendMessageConnector(BRouteSendAdapterConfig{Mode:"sidecar_preview", SidecarPath: env path, TimeoutSeconds: parsed timeout})

• Run focused tests.

go test ./internal/tools -run "TestNewSendMessageConnectorFromEnv|TestBRoute" -count=1

Expected: pass.

Task 3: Process-backed B-route sidecar client boundary

Files:

• Create: internal/broute/send_sidecar_client.go
• Create: internal/broute/send_sidecar_client_test.go
• Modify: internal/tools/send_message_broute_adapter.go
• Modify: internal/tools/send_message_broute_adapter_test.go

Interfaces:

• Produces protocol: isphere.broute.send.v1.

• Produces sidecar ops:

  • self_check
  • probe_runtime
  • preview_send_message

• No op named send_message in this task.

• Write fake-process tests for internal/broute.

The fake sidecar must accept stdin JSON and return:

{"protocol":"isphere.broute.send.v1","request_id":"...","op":"preview_send_message","ok":true,"data":{"connector_mode":"broute-sidecar-preview","would_send":false,"entrypoint":"AppContextManager.SendTxtMessageByJid","target_ref":"direct:demo","content_sha256":"..."}}

• Implement the client with timeout, stderr capture, protocol/op/request_id validation, and structured sidecar errors.

Use internal/msglib/sidecar_client.go as the pattern, but keep the package separate as internal/broute.

• Update send_message_broute_adapter.go so Mode="sidecar_preview" calls preview_send_message and returns:

Accepted=false
Status=blocked
ErrorCode=broute_sidecar_preview_only
ConnectorMode=broute-sidecar-preview
ProductionEnabled=false
SideEffects all false

• Verify no accidental production send path exists.

Run:

go test ./internal/broute ./internal/tools -run "BRoute|Sidecar" -count=1

Expected: pass; no test should require iSphere login.

Task 4: Native B-route sidecar skeleton, preview-only

Files:

• Create: native/ISphereSendSidecar/Program.cs
• Create: native/ISphereSendSidecar/SidecarProtocol.cs
• Create: scripts/build-send-sidecar.ps1
• Create: scripts/verify-send-sidecar.ps1
• Create: docs/broute-send-sidecar-contract.md

Interfaces:

• Native executable accepts stdin JSON and writes stdout JSON.

• Protocol: isphere.broute.send.v1.

• Ops implemented:

  • self_check
  • probe_runtime
  • preview_send_message

• Explicitly not implemented:

  • send_message
  • send_file
  • upload_file
  • hooks/injection/network replay.

• Implement self_check returning sidecar name, version, process bitness, and mutates_client=false.

• Implement probe_runtime by reusing safe process/module discovery logic from WinHelper where possible.

• Implement preview_send_message as contract validation only; it must echo hashes/target refs and would_send=false.

• Build and verify.

Run:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\build-send-sidecar.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-send-sidecar.ps1
go test ./...

Expected: all pass; sidecar verification prints only booleans/counts and no message body.

Task 5: Online B-route evidence package v3

Files:

• Create: scripts/package-broute-bridge-probe.ps1
• Create: scripts/verify-broute-bridge-probe-package.ps1
• Create: scripts/validate-returned-broute-bridge-probe.ps1
• Create: docs/source-discovery/2026-07-12-broute-bridge-probe-package.md

Interfaces:

• Package includes:

  • live probe recorder;
  • send sidecar preview executable;
  • RUN-BROUTE-BRIDGE-PROBE.bat;
  • BROUTE-BRIDGE-INPUTS.template.json;
  • return zip helper.

• Package only non-mutating probes.

• Require operator to be logged in before running.

• Validate returned package for:

  • running client present;
  • module availability;
  • sidecar self_check passed;
  • sidecar preview returned would_send=false;
  • no real send attempted.

Run:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\package-broute-bridge-probe.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-broute-bridge-probe-package.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\validate-returned-broute-bridge-probe.ps1 -UseFixture

Expected: package builds and fixture validation passes.

Task 6: Business smoke split for send readiness

Files:

• Modify: scripts/verify-business-goals-smoke.ps1
• Modify: docs/reports/2026-07-12-main-business-status-correction.md
• Create or modify: docs/reports/2026-07-12-broute-next-smoke.md

Interfaces:

• Produces separate booleans:

  • send_message_preview_ready
  • send_message_broute_bridge_preview_ready
  • send_message_ui_action_ready
  • send_message_business_delivery_ready
  • send_file_preview_ready
  • send_file_business_delivery_ready

• Update smoke script to avoid one ambiguous send_message_production_ready field.

• Ensure current expected state is:

{
  "send_message_preview_ready": true,
  "send_message_broute_bridge_preview_ready": true,
  "send_message_ui_action_ready": true,
  "send_message_business_delivery_ready": false,
  "send_file_preview_ready": true,
  "send_file_business_delivery_ready": false
}

• Verify.

Run:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-business-goals-smoke.ps1
git diff --check
go test ./...

Expected: pass.

---

Stop conditions

Stop and ask the business owner if any of these occur:

1. B-route bridge transport requires invasive in-process loading and no plugin/IPC path exists.
2. Online probe shows the logged-in client does not expose the expected modules/entrypoints.
3. B-route preview cannot distinguish direct contact vs group target.
4. Any step would perform real send/upload before explicit online evidence gates are ready.
5. A-route becomes the only viable path; this requires an explicit business decision because RPA is backup-only.

Recommended next action

Start with Task 1 and Task 2 only. That creates a clear B-route bridge feasibility decision and lets the MCP server select a B-route dry-run connector from env without touching real send.