fix(agent): restore exec utility host

[zerob13]

Summary

• add a dedicated background exec utility host main entrypoint so utilityProcess no longer loads the normal app bootstrap bundle
• keep utility-host imports free of Electron main-only exports and handle Electron parentPort MessageEvent payloads
• add SDD notes and focused coverage for the host/proxy path

Closes #1695

Validation

• pnpm exec vitest --config vitest.config.ts --project main test/main/lib/agentRuntime/backgroundExecUtilityHost.test.ts test/main/lib/agentRuntime/backgroundExecSessionManager.test.ts test/main/lib/agentRuntime/sessionPaths.test.ts test/main/lib/agentRuntime/shellEnvHelper.test.ts --run
• pnpm exec electron-vite build
• utilityProcess.fork(out/main/backgroundExecUtilityHost.js) list/start probes return ok:true
• pnpm run format
• pnpm run i18n
• pnpm run lint
• pre-commit typecheck hook passed

Summary by CodeRabbit

• Bug Fixes

  • Fixed a crash/hang in the background execution utility host so quick foreground exec commands complete reliably; improved message handling and kept the host alive while awaiting requests.
  • Removed dependence on main-process-only APIs in the utility host to avoid startup failures.

• Refactor

  • Isolated app startup and added a dedicated utility-host entrypoint; converted several lazy imports to static imports to stabilize startup and build behavior.
  • Extracted MIME detection into a focused implementation for more consistent file type detection.

• Documentation

  • Added spec, plan, and task docs describing the investigation and fix.

• Tests

  • Added unit tests for message payload handling and updated runtime tests.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ab70db89-d83b-444a-808c-904169bd0cf0

📥 Commits

Reviewing files that changed from the base of the PR and between ecedfe1 and 5abd713.

📒 Files selected for processing (11)

• docs/issues/vite-mixed-import-warnings/plan.md
• docs/issues/vite-mixed-import-warnings/spec.md
• docs/issues/vite-mixed-import-warnings/tasks.md
• src/main/presenter/agentRuntimePresenter/messageStore.ts
• src/main/presenter/devicePresenter/index.ts
• src/main/presenter/filePresenter/BaseFileAdapter.ts
• src/main/presenter/filePresenter/mime.ts
• src/main/presenter/filePresenter/mimeDetection.ts
• src/main/presenter/lifecyclePresenter/index.ts
• src/main/presenter/sqlitePresenter/index.ts
• src/main/presenter/syncPresenter/index.ts

✅ Files skipped from review due to trivial changes (4)

• docs/issues/vite-mixed-import-warnings/tasks.md
• docs/issues/vite-mixed-import-warnings/plan.md
• src/main/presenter/agentRuntimePresenter/messageStore.ts
• docs/issues/vite-mixed-import-warnings/spec.md

---

📝 Walkthrough

Walkthrough

This PR isolates the exec utility host from main app bootstrap (new backgroundExecUtilityHost entry and build input), moves app startup into exported startApp(), normalizes parent-port RPC payloads with unwrapping and keep-alive, removes Electron main-process dependencies from utility-host code, extracts MIME detection, and adds tests.

Changes

Agent Exec Utility Process Crash Fix

Layer / File(s)	Summary
Issue specification and implementation plan docs/issues/agent-exec-utility-process-crash/spec.md, docs/issues/agent-exec-utility-process-crash/plan.md, docs/issues/agent-exec-utility-process-crash/tasks.md, docs/issues/vite-mixed-import-warnings/*	Problem statement, acceptance criteria, non-goals, constraints, and implementation/validation plans for isolating the utility host, normalizing RPC handling, and addressing Vite mixed-import warnings.
Build configuration and dual entry points electron.vite.config.ts	Rollup main build updated to expose explicit index and backgroundExecUtilityHost inputs; removed inline-dynamic-imports output setting and set deterministic entry/chunk filenames.
Main app startup refactoring src/main/appMain.ts	Encapsulates Electron startup side effects into exported startApp() guarded by appStarted, moving top-level side effects into controlled startup.
Utility host entry point and unconditional main startup src/main/backgroundExecUtilityHostEntry.ts, src/main/index.ts	Adds backgroundExecUtilityHostEntry.ts that runs the exec utility host runtime when appropriate; index.ts now unconditionally invokes startApp().
Utility host spawn and entrypoint resolution src/main/lib/agentRuntime/backgroundExecSessionManager.ts	Spawn logic now uses app.getAppPath() to resolve bundle candidates and falls back to filesystem-based candidate search; logger import switched to local logger.
Parent port message normalization and lifecycle src/main/lib/agentRuntime/backgroundExecUtilityHost.ts	Adds optional ParentPort.start(), getParentPortMessagePayload() to unwrap raw and MessageEvent payloads, long-lived keep-alive interval, and message filtering before dispatching RPC requests.
Removing main-process-only Electron dependencies from utility host src/main/lib/agentRuntime/backgroundExecLogger.ts, src/main/lib/agentRuntime/sessionPaths.ts, src/main/lib/agentRuntime/shellEnvHelper.ts	Introduce console-backed logger, derive sessions root from os.homedir() instead of app.getPath(), and compute default PATH entries from process.env with platform-specific defaults (removing Electron/RuntimeHelper reliance).
MIME detection extraction and static imports src/main/presenter/filePresenter/mimeDetection.ts, src/main/presenter/filePresenter/mime.ts, src/main/presenter/filePresenter/BaseFileAdapter.ts	Extract detectMimeType/isLikelyTextFile into mimeDetection.ts, re-export from mime.ts, and replace dynamic imports with top-level static imports in BaseFileAdapter.
Presenter static imports and minor refactors src/main/presenter/*, src/main/presenter/sqlitePresenter/index.ts	Replace various dynamic import() calls with static imports for presenter and LegacyChatImportService, and make SQLitePresenter a type-only import to avoid runtime side effects.
Tests for message handling and dependency de-coupling test/main/lib/agentRuntime/*	Add unit tests for parent-port payload unwrapping, update session-path and shell-env tests to use OS-level mocks, and update utility-host spawn tests to expect the dedicated background entrypoint.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• ThinkInAIXYZ/deepchat#718: Updates electron.vite.config.ts Rollup output configuration, including changes to rollupOptions.output.inlineDynamicImports behavior similar to this PR's build-config refactoring.

Poem

🐰 In a burrow where processes quietly nap,
I unwrapped messages, fixed the startup trap.
Two entries now guide who stays and who goes,
The utility host listens, not quick to doze.
Hopping on logs, console prints light the track—execs come back!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main fix: restoring the exec utility host, which directly addresses the regression issue #1695.
Linked Issues check	✅ Passed	The PR comprehensively addresses #1695 by fixing the root cause: utility process now loads a dedicated entrypoint without app bootstrap, preventing crashes from conflicting startup code and Electron-main-only dependencies.
Out of Scope Changes check	✅ Passed	All changes are within scope of fixing the utility host regression and eliminating Vite mixed-import warnings. The fix includes utility host refactoring, app bootstrap separation, dependency isolation, and documentation.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-1695-exec-utility-host

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

Warning

Review ran into problems

🔥 Problems

Stopped waiting for pipeline failures after 30000ms. One of your pipelines takes longer than our 30000ms fetch window to run, so review may not consider pipeline-failure results for inline comments if any failures occurred after the fetch window. Increase the timeout if you want to wait longer or run a @coderabbit review after the pipeline has finished.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/main/appMain.ts`:
- Around line 86-91: The code currently logs raw process.argv and the full
deeplink value which may expose secrets; update the initialization logging
around findStartupDeepLink and storeStartupDeepLink to avoid printing raw argv
or the full startupDeepLink: remove or change console.log(process.argv) and
console.log(startupDeepLink) to redact sensitive data (e.g., log only presence,
host/domain, or a masked/deferred version like "<redacted>…last4" or length) and
use a debug/log-level guard so full values are only emitted in debug mode; apply
the same redaction/guarding pattern to the analogous logging near the later
startup handling (the other findStartupDeepLink/storeStartupDeepLink usage).
- Around line 77-81: When requestSingleInstanceLock() fails, call app.quit() and
immediately return to stop further initialization; modify the block around
app.requestSingleInstanceLock() so that after app.quit() the function exits
(e.g., add an early return) to prevent the secondary instance from registering
handlers or continuing startup logic.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 303736d5-1263-4e34-af1f-230da4dcbcf6

📥 Commits

Reviewing files that changed from the base of the PR and between 7c62924 and 06a6436.

📒 Files selected for processing (16)

• docs/issues/agent-exec-utility-process-crash/plan.md
• docs/issues/agent-exec-utility-process-crash/spec.md
• docs/issues/agent-exec-utility-process-crash/tasks.md
• electron.vite.config.ts
• src/main/appMain.ts
• src/main/backgroundExecUtilityHostEntry.ts
• src/main/index.ts
• src/main/lib/agentRuntime/backgroundExecLogger.ts
• src/main/lib/agentRuntime/backgroundExecSessionManager.ts
• src/main/lib/agentRuntime/backgroundExecUtilityHost.ts
• src/main/lib/agentRuntime/sessionPaths.ts
• src/main/lib/agentRuntime/shellEnvHelper.ts
• test/main/lib/agentRuntime/backgroundExecSessionManager.test.ts
• test/main/lib/agentRuntime/backgroundExecUtilityHost.test.ts
• test/main/lib/agentRuntime/sessionPaths.test.ts
• test/main/lib/agentRuntime/shellEnvHelper.test.ts

[coderabbitai]

Actionable comments posted: 0

[coderabbitai]

Actionable comments posted: 0