Files
AgentCompany/docs/2026-03-17-audit-and-rebuild-plan.md
T
2026-03-18 01:15:58 -04:00

13 KiB
Raw Blame History

2026-03-17 Audit And Rebuild Plan

Execution Order

This document is the Phase 1-4 artifact required by AGENTS.md.

  1. ProjectManager: read the full PRD and define milestone gates.
  2. ResearchAnalyst: verify Electron runtime, security, packaging, updater, and OS constraints.
  3. TechnicalImplementationResearcher: freeze main/preload/renderer/storage/runtime boundaries.
  4. EnterpriseArchitect: validate dependency direction, module seams, IPC contracts, and naming rules.

Implementation work starts only after the decisions below are recorded.

Scope

The audit covers:

  • PRD alignment
  • Electron main / preload / renderer boundaries
  • IPC contracts, sender validation, and company scoping
  • connector runtime execution, orchestration, and background work
  • local persistence, backup / restore, workspace locking, and crash recovery
  • renderer information architecture, onboarding, and desktop UX
  • packaging, updater, release, and verification posture
  • adapter package quality and test coverage

Baseline Evidence

Repository state

  • The working tree is already in a large, incomplete refactor state.
  • The repo is no longer a prototype shell; it already contains a local data model, automation engine, workflow engine, browser automation surface, and an Electron shell.
  • The implementation breadth is now large enough that coherence, not feature count, is the main problem.

Verification results on 2026-03-17

  • pnpm typecheck: pass
  • pnpm test:unit: pass
  • pnpm test:integration: pass
  • pnpm test:packages: pass
  • pnpm test:e2e: pass
  • pnpm build:verify: pass
  • pnpm build:dir: pass, producing build/release/AgentCompany-0.4.26-arm64-mac.zip
  • pnpm lint: fail

Current build posture

  • Main bundle: out/main/index.js about 592 kB
  • Preload bundle: out/preload/index.js about 151 kB
  • Renderer bundle: out/renderer/assets/index-*.js about 1.69 MB
  • Packaging currently succeeds only on the host platform tested locally.

Research Notes

The following external references were re-checked during this audit:

These references matter because the PRD explicitly requires secure preload exposure, custom protocol usage, sandboxing, OS-backed secret storage, release signing, and update integrity.

Current State Summary

The application already has the following real subsystems:

  • Electron shell with contextIsolation, nodeIntegration: false, sandbox: true, and a custom app:// protocol
  • local DatabaseSync SQLite store with WAL mode
  • local API server for agent-driven actions
  • utility-process worker for connector execution
  • run orchestration, automation rules, workflow pipelines, messages, approvals, documents, meetings, sprints, and browser actions

The main issue is not “missing a single feature”.

The issue is that the system surface is broader than the stability and architecture boundaries that currently support it.

Findings

High severity

  1. Main-process data access is concentrated in a single synchronous repository that is too large to remain reliable.

    • Evidence: src/main/database.ts is 3292 lines and owns schema setup, migrations, snapshots, orchestration state, cost accounting, approvals, messaging, workflow persistence, backup/restore, workspace locking, and dashboard aggregation.
    • Impact:
      • blocks maintainability
      • encourages cross-domain coupling
      • increases renderer-visible latency because many IPC calls read the same monolith
  2. The renderer shell is still a god component and does not match the desktop-native operating model in the PRD.

    • Evidence: src/renderer/App.tsx is 1520 lines and owns navigation, data loading, company switching, command palette, modal orchestration, run log buffering, and page composition for every domain.
    • Impact:
      • feature interaction is hard to reason about
      • state ownership is blurred
      • operator workflows such as run monitoring are buried behind a console drawer instead of having first-class surfaces
  3. The verification gate defined by the project itself is currently broken because lint does not run.

    • Evidence: pnpm lint fails with ENOENT ... electron.vite.config.<timestamp>.mjs.
    • Impact:
      • the release checklist in AGENTS.md is not met
      • CI or local quality enforcement is unreliable
  4. Update and release readiness are not production-grade.

    • Evidence:
      • electron-builder.yml still defaults to a generic placeholder publish URL
      • src/main/updater-service.ts only checks availability; it does not implement a complete download/apply flow or pre-update backup
      • local mac packaging falls back to ad-hoc signing and skips notarization
    • Impact:
      • no shippable trust chain for public release
      • updater behavior is not aligned with PRD requirements
  5. Automatic internal coordination is still mostly emergent behavior from prompts and heuristics, not a hardened orchestration contract.

    • Evidence:
      • src/main/prompt-builder.ts contains the majority of “real company behavior” instructions
      • src/main/automation-service.ts uses rule-triggered wakeups and message dispatch to simulate organization flow
      • no dedicated coordination state model exists for “conversation pending response”, “delegation awaiting acceptance”, or “review SLA breached”
    • Impact:
      • the system can appear intelligent in happy paths while remaining hard to debug in stalled paths
      • message flow, approvals, and delegation are not deterministic enough for a production control plane

Medium severity

  1. Snapshot loading is coarse-grained and expensive.

    • Evidence:
      • db.listSnapshot() reads nearly every table every time
      • db.listRendererSnapshot() still calls listSnapshot() first and only then filters by company
      • App.refresh() reloads the entire current company snapshot on most domain events
    • Impact:
      • unnecessary main-process work
      • unnecessary renderer re-renders
      • future scale problems once run/message/activity volume increases
  2. Run log access is full-file based, not incremental.

    • Evidence:
      • src/main/database.ts#readRunLog returns the entire log file
      • renderer keeps in-memory log buffers in App.tsx
    • PRD mismatch:
      • PRD requires offset-based incremental log reading
    • Impact:
      • degraded performance on large logs
      • poor long-running run observability
  3. The preload bridge is typed but too broad for the current architecture maturity.

    • Evidence: src/preload/index.ts exposes dozens of direct CRUD and orchestration methods.
    • Impact:
      • large privileged surface area
      • difficult contract governance
      • weak module boundaries between renderer and domain actions
  4. Workflow and automation configuration crosses boundaries as opaque JSON strings.

    • Evidence:
      • conditionsJson, actionConfigJson, stepsJson, triggerConfigJson, metadataJson, attachmentsJson are passed across IPC and persistence as raw strings
    • Impact:
      • weak compile-time guarantees
      • more runtime parsing failures
      • harder migration and refactoring path
  5. Onboarding still optimizes for spectacle more than operator clarity.

    • Evidence:
      • src/renderer/components/CompanyOnboarding.tsx strongly promises “autonomous company” behavior
      • connector choice and capability differences are not explicit enough
      • initial run review is not operator-first
    • Impact:
      • weak first-use trust
      • harder diagnosis when the selected connector is degraded or capability-limited
  6. Browser/social automation is fragile and outside the core PRD center of gravity.

    • Evidence:
      • src/main/browser-manager.ts relies on direct DOM selectors, timed delays, and third-party site structure
    • Impact:
      • brittle surface
      • expands support burden
      • competes with higher-priority core orchestration work
  7. The app supports many domains, but there is no dedicated Runs page.

    • Evidence:
      • run monitoring exists only through dashboard widgets and the bottom console drawer
    • PRD mismatch:
      • PRD requires live runs and log console as first-class operating surfaces

Low severity

  1. Renderer design language is coherent but still too web-dashboard-like for a desktop control plane.

    • Evidence:
      • system font stack in src/renderer/styles.css
      • single-column content area on many dense surfaces
      • heavy modal use for editing
  2. Package-level runtime verification is narrow.

    • Evidence:
      • test:packages covers only adapter-opencode-local and adapter-kimi-local
      • codex, claude, and gemini packages do not have equivalent package test commands here

Detailed Gap List By Domain

Main / preload / IPC

  • Sender validation exists and the custom protocol is correct, which is a good baseline.
  • Contracts are typed, but not versioned and not yet narrowed by capability groups.
  • ipc-core-common.ts and ipc-domain-common.ts still use any-heavy dependency wiring.
  • The privileged bridge still mirrors domain CRUD too directly instead of exposing operator use-cases.

Data / orchestration

  • Workspace lock handling exists, but it is still embedded inside the database class.
  • Queued-run recovery exists, but recovery semantics are still best-effort.
  • Workflow execution is inline, stateful, and sync-heavy in the main process service layer.
  • Aggregation views such as inbox, standup, and metrics are built inside the same DB class.

Connectors

  • Codex / Claude / Gemini / OpenCode have deeper execution paths than Kimi.
  • Kimi remains generic CLI mode with explicit capability downgrade.
  • Connector health checks use command probes and status translation, but operator feedback is still too shallow.
  • Connector discovery and operator selection are still secondary in first-launch UX.

Renderer

  • The UI covers a large domain surface, but the operating hierarchy is inverted:
    • overview first
    • CRUD pages second
    • runs/logs/workspaces hidden as secondary tools
  • The app does not yet “scream” workspace, run, and coordination as the primary desktop tasks.

Testing / release

  • Current automated coverage is better than zero, but still not close to the PRD completion criteria.
  • E2E currently proves only first-launch onboarding and console toggle.
  • No E2E covers:
    • task run lifecycle
    • approval resolution
    • message routing
    • workflow execution
    • connector health state changes
    • backup/restore
    • workspace locking / recovery
  • Release docs do not yet define signed beta, RC, and production lanes.

Rebuild Direction

Tranche A: operator shell and observability

  • add first-class Runs navigation and run triage workflow
  • move run logs to chunked readers instead of whole-file loads
  • make onboarding explicitly choose connector and workspace intent
  • fix lint so the repo’s minimum quality gate works again

Tranche B: boundary extraction

  • split AppDatabase into read models, command repositories, and orchestration state store
  • reduce preload surface to bounded capability groups
  • split renderer shell from feature pages and detail inspectors

Tranche C: release hardening

  • define real update lanes and signing rules
  • add updater backup/install flow
  • document mac notarization, Windows signing, Linux packaging behavior
  • flip relevant Electron fuses during packaging

Milestone Gates

Architecture Freeze

  • audit findings accepted
  • platform target confirmed
  • process boundaries frozen
  • core run / workspace / connector model frozen

Interactive Prototype

  • onboarding, connectors, agents, tasks, runs, console, workspaces all coherent

Internal Alpha

  • connector lifecycle, approvals, message routing, and crash recovery usable end-to-end

Cross-Platform Validation

  • macOS, Windows, Linux behavior documented and smoke-validated

Signed Beta Build

  • signing path defined
  • updater feed real
  • rollback / backup strategy documented

Release Candidate

  • lint, typecheck, unit, integration, E2E, build, and packaging gates all green

Production Readiness

  • security audit complete
  • no placeholder release config remains
  • operator workflows are deterministic and observable

Next Implementation Slice

The next code tranche will target:

  1. repair the lint gate
  2. add first-class Runs navigation and incremental log loading
  3. make onboarding force an explicit connector choice
  4. keep build packaging green while making these changes