thesyart/emperor-agent

1. Purpose and execution surfaces

Emperor Agent is a local-first, single-user desktop agent workbench for chat, project-bound work, planning, and persistent Goal execution. The production path is Electron hosting the TypeScript Core in-process; the renderer reaches it only through IPC. Python, HTTP, and WebSocket backends are retired.

Primary entry points:

• Electron main process: desktop/src/main/index.ts

• Core library composition/export: packages/core/src/index.ts

• Sandboxed renderer bootstrap: desktop/src/renderer/src/main.ts

• Headless local stdio ACP preview: packages/core/src/acp/stdio-entry.ts

2. Desktop process boundary

Electron main owns windows, runtime roots, Core host lifecycle, terminal hosting, and IPC/event bridges. Preload exposes a constrained API to the untrusted/sandboxed renderer; shared contracts define that boundary.

• Core hosting/config: desktop/src/main/core-host.ts, desktop/src/main/config.ts

• IPC and event forwarding: desktop/src/main/ipc.ts, desktop/src/main/event-bridge.ts

• Preload bridge: desktop/src/preload/index.ts, desktop/src/shared/ipc-contract.ts

Control flow is renderer action → preload IPC → main/Core API → runtime event → main event bridge → preload → renderer state update.

3. Core API, runtime, and persistence

CoreApi is the application façade for chat, configuration, workspace, Goal, diagnostics, and other services. Runtime establishes the local state root, resources, session lifecycle, and durable stores. User-private data is filesystem-backed under stateRoot; project folders remain separate from session/memory/Goal state.

• API façade and operations: packages/core/src/api/core-api.ts, packages/core/src/api/operations.ts

• Runtime/session ownership: packages/core/src/runtime/lifecycle.ts, packages/core/src/runtime/session-runtime.ts

• Durable primitives: packages/core/src/store/atomic-json.ts, packages/core/src/store/jsonl.ts

• Sessions and project state: packages/core/src/sessions/store.ts, packages/core/src/projects/state-store.ts

4. Agent turn pipeline and model boundary

A chat/build request becomes an agent run: assemble context, select/call the configured model provider, dispatch allowed tools, persist turn/session state, and emit progress events. Providers are external network boundaries; fallback behavior and cost/execution policy are Core-controlled.

• Agent loop and runner: packages/core/src/agent/loop.ts, packages/core/src/agent/runner.ts

• Context construction: packages/core/src/agent/context-builder.ts, packages/core/src/context/pipeline.ts

• Model routing/calling: packages/core/src/agent/model-caller.ts, packages/core/src/model/router.ts

• Provider adapters: packages/core/src/providers/openai-compat.ts, packages/core/src/providers/anthropic.ts

5. Control, permissions, plans, and Goals

Control is the principal safety/state-machine layer. It enforces Ask/Smart/Full policies, read-only Plan behavior, approvals, and execution constraints. Goal coordinates durable multi-turn work with scope, evidence, recovery, reviewer checks, and a completion gate; it serializes mutation ownership and fails closed on unsafe recovery.

• Control and Plan lifecycle: packages/core/src/control/manager.ts, packages/core/src/control/plan-execution.ts

• Permission pipeline: packages/core/src/permissions/pipeline.ts, packages/core/src/permissions/workspace-policy.ts

• Goal orchestration/gating: packages/core/src/goals/coordinator.ts, packages/core/src/goals/completion-gate.ts

• Goal persistence/recovery: packages/core/src/goals/store.ts, packages/core/src/goals/recovery.ts

6. Capabilities and renderer projection

Core-owned tools operate on files, terminals, Git, MCP, skills, attachments, memory, and scheduler jobs, subject to control and permission checks. The Vue renderer projects Core events into chat, plans, goals, workspace panes, and configuration panels rather than directly owning backend state.

• Tool dispatch/execution: packages/core/src/tools/dispatch.ts, packages/core/src/tools/execution.ts

• Workspace and terminal/Git boundary: packages/core/src/workspace/terminal.ts, packages/core/src/workspace/git.ts

• MCP lifecycle: packages/core/src/mcp/supervisor.ts, packages/core/src/mcp/adapter.ts

• Renderer state/event reduction: desktop/src/renderer/src/runtime/reducer.ts, desktop/src/renderer/src/runtime/runtimeEffects.ts

• Primary UI shell: desktop/src/renderer/src/App.vue, desktop/src/renderer/src/views/ChatView.vue