update
This commit is contained in:
1 parent
1ba3147ed2
commit
0cd65521b8
32 files changed
+1853
-342
No files matched your search
@@ -0,0 +1,333 @@
|
||||
# AgentCompany Integrated Audit Matrix (2026-03-18)
|
||||
|
||||
## Scope
|
||||
|
||||
This audit covered:
|
||||
|
||||
- `PRD.md`
|
||||
- Electron main / preload / renderer source under `src/main`, `src/preload`, `src/renderer`, `src/shared`
|
||||
- Packaging and runtime config: `electron-builder.yml`, `electron.vite.config.ts`, `scripts/build-desktop.mjs`
|
||||
- Existing validation assets under `tests/unit`, `tests/integration`, `tests/e2e`
|
||||
- Runtime validation through a live Electron launch with real IPC, onboarding, org creation, approvals, and run orchestration
|
||||
|
||||
## Evidence Collected
|
||||
|
||||
Validation commands executed in this session:
|
||||
|
||||
- `pnpm typecheck`
|
||||
- `pnpm lint`
|
||||
- `pnpm test:unit`
|
||||
- `pnpm test:integration`
|
||||
- `pnpm test:e2e`
|
||||
- `pnpm electron-vite build`
|
||||
|
||||
Additional runtime scenarios executed against the built Electron app:
|
||||
|
||||
- full first-launch onboarding to desktop shell
|
||||
- navigation sweep across desktop sections
|
||||
- live hire request flow with `autoApproveHires = true`
|
||||
- live hire request flow with `autoApproveHires = false`
|
||||
- negative-path validation that legacy `saveAgent` creation and `pending_approval -> idle` status bypasses are rejected
|
||||
|
||||
## Current Architecture Reality
|
||||
|
||||
What already exists and is materially real:
|
||||
|
||||
- main / preload / renderer separation is implemented
|
||||
- renderer uses typed preload APIs instead of raw Node access
|
||||
- `contextIsolation: true`, `nodeIntegration: false`, `sandbox: true` are used for the main desktop shell
|
||||
- orchestration worker runs in an Electron utility process
|
||||
- SQLite-backed local-first state model exists
|
||||
- connectors for `codex_local`, `claude_local`, `gemini_local`, `opencode_local`, `kimi_local` exist
|
||||
- approvals, runs, costs, activity, automation, meetings, knowledge, documents, sprints, social, messages, workspaces, and onboarding all exist in code and UI
|
||||
|
||||
What is still structurally weak:
|
||||
|
||||
- several modules are still too large to be considered stable long-term coordination boundaries
|
||||
- cross-feature side effects still live in a few orchestration-heavy modules instead of a smaller explicit event-policy layer
|
||||
- some release/security/product rules exist in PRD and code, but not all are enforced uniformly in every write path
|
||||
|
||||
Largest modules by line count at audit time:
|
||||
|
||||
- `src/main/database.ts`: 3348
|
||||
- `src/renderer/components/execution.tsx`: 1726
|
||||
- `src/renderer/components/communication.tsx`: 1726
|
||||
- `src/main/api-server.ts`: 1697
|
||||
- `src/renderer/components/automation.tsx`: 1693
|
||||
- `src/renderer/App.tsx`: 1606
|
||||
- `src/main/prompt-builder.ts`: 1541
|
||||
|
||||
## PRD Matrix
|
||||
|
||||
### 1. Local Profile / Company
|
||||
|
||||
Status: implemented, with one policy caveat
|
||||
|
||||
Evidence:
|
||||
|
||||
- local profile bootstrap, backup/restore, company switching, settings persistence all exist
|
||||
- onboarding successfully creates company, workspace, goal, initial run, and opens desktop shell
|
||||
|
||||
Remaining risk:
|
||||
|
||||
- company policy toggles are present, but some governance behavior is still distributed across UI, IPC, API, and automation rather than centralized in a single policy service
|
||||
|
||||
### 2. Connector Management
|
||||
|
||||
Status: implemented
|
||||
|
||||
Evidence:
|
||||
|
||||
- connector registry UI exists
|
||||
- connector health service exists
|
||||
- model listing and auth terminal support exist
|
||||
- command/env binding handling exists
|
||||
|
||||
Remaining risk:
|
||||
|
||||
- connector execution policy is still sensitive to environment-based behavior and deserves a dedicated policy surface, not scattered guard clauses
|
||||
|
||||
### 3. Agent Registry / Org Structure
|
||||
|
||||
Status: implemented, previously inconsistent, partially hardened in this wave
|
||||
|
||||
Evidence:
|
||||
|
||||
- org chart, agent roster, hiring pipeline, manager/report relationships, and budget fields exist
|
||||
- pending-approval lifecycle exists in data model and approval resolution logic
|
||||
|
||||
Critical finding fixed in this wave:
|
||||
|
||||
- renderer previously allowed direct agent creation from the Agents page, bypassing `hire_agent` approval and breaking synchronization between Hiring, Approvals, onboarding, and org history
|
||||
- renderer also allowed direct status edits that could move a pending hire into an active state without an approval decision
|
||||
|
||||
Remediation added:
|
||||
|
||||
- dedicated `requestHire` IPC contract
|
||||
- transactional `createHireRequest(...)` persistence path
|
||||
- renderer Agent creation now submits hire requests instead of active agents
|
||||
- IPC `saveAgent` now rejects new-agent creation and rejects direct pending-hire activation
|
||||
|
||||
Runtime proof:
|
||||
|
||||
- with `autoApproveHires = false`, a new hire lands in `pending_approval`
|
||||
- direct `saveAgent` creation returns `AGENT_CREATION_REQUIRES_HIRE_REQUEST`
|
||||
- direct status bypass returns `AGENT_APPROVAL_REQUIRED`
|
||||
- formal approval transitions the same agent record to `idle`
|
||||
|
||||
### 4. Goals / Projects / Tasks
|
||||
|
||||
Status: implemented
|
||||
|
||||
Evidence:
|
||||
|
||||
- onboarding creates goal and project structure
|
||||
- task creation, comments, assignment, review states, kanban/list views, and run linkage exist
|
||||
- task status changes feed automation/orchestration paths
|
||||
|
||||
Remaining risk:
|
||||
|
||||
- feature is functionally present, but task + review + message + automation interactions are still distributed across large renderer and main modules
|
||||
|
||||
### 5. Run Orchestration / Session Continuity
|
||||
|
||||
Status: implemented, with scaling caveats
|
||||
|
||||
Evidence:
|
||||
|
||||
- run creation, queueing, worker dispatch, recovery, logs, cancellation, and run status events exist
|
||||
- utility-process worker is used instead of running orchestration in the renderer
|
||||
- integration tests cover autonomous chain and recovery cases
|
||||
|
||||
Remaining risk:
|
||||
|
||||
- orchestration and wake logic remain heavily centralized
|
||||
- cross-feature triggers are correct at current scope, but scaling behavior and event fan-out still need a slimmer event-policy boundary
|
||||
|
||||
### 6. Approvals / Governance
|
||||
|
||||
Status: implemented, materially improved in this wave
|
||||
|
||||
Evidence:
|
||||
|
||||
- approvals UI, decision handling, related task linkage, and automation callbacks exist
|
||||
- board-side approval decisions update state and trigger follow-up automations
|
||||
|
||||
Critical finding fixed in this wave:
|
||||
|
||||
- agent creation governance could be bypassed from the desktop UI and IPC write path
|
||||
|
||||
Remaining risk:
|
||||
|
||||
- other approval-governed domains, especially termination and production-deploy style flows, still deserve the same hard policy treatment across all entrypoints
|
||||
|
||||
### 7. Cost / Budget
|
||||
|
||||
Status: implemented
|
||||
|
||||
Evidence:
|
||||
|
||||
- budget fields, cost entries, cost dashboard, thresholds, and budget-related automation logic exist
|
||||
|
||||
Remaining risk:
|
||||
|
||||
- budgets are enforced operationally, but not all escalation policy is centralized; some cost behavior is still advisory rather than hard-stopping privileged actions
|
||||
|
||||
### 8. Activity / Audit / Logs
|
||||
|
||||
Status: implemented
|
||||
|
||||
Evidence:
|
||||
|
||||
- activity timeline exists
|
||||
- many core mutations add activity entries
|
||||
- run logs exist and are streamable into renderer console panels
|
||||
|
||||
Remaining risk:
|
||||
|
||||
- structured logging exists, but the audit trail is still assembled from multiple write sites instead of passing through a smaller domain-event backbone
|
||||
|
||||
### 9. Secrets / Config / Environment
|
||||
|
||||
Status: implemented, hardened in this wave
|
||||
|
||||
Evidence:
|
||||
|
||||
- Electron `safeStorage` is used where available
|
||||
- encrypted fallback vault exists behind explicit env opt-in
|
||||
- env binding resolution exists for connector runs
|
||||
|
||||
Security hardening added in this wave:
|
||||
|
||||
- `NODE_OPTIONS` was removed from the runtime environment allowlist so spawned agent runtimes do not inherit host-side Node injection flags by default
|
||||
|
||||
Remaining risk:
|
||||
|
||||
- preload API surface is still large, even if typed
|
||||
- env policy should eventually be expressed as explicit runtime capability profiles per connector, not only a static allowlist
|
||||
|
||||
### 10. Workspace / Repo / Artifact Management
|
||||
|
||||
Status: implemented
|
||||
|
||||
Evidence:
|
||||
|
||||
- workspace registry, path selection, repo URL/ref fields, primary workspace logic, and lock metadata exist
|
||||
- orchestration resolves workspace context into runtime env
|
||||
|
||||
Remaining risk:
|
||||
|
||||
- workspace locking and stale-lock cleanup exist, but deserve more explicit operator-facing conflict states in UI for complex multi-run contention
|
||||
|
||||
### 11. Notifications / State Awareness
|
||||
|
||||
Status: implemented
|
||||
|
||||
Evidence:
|
||||
|
||||
- desktop notifications exist
|
||||
- tray/menu/window controls exist
|
||||
- sidebar badges, inbox, and console surfacing exist
|
||||
|
||||
Remaining risk:
|
||||
|
||||
- notification strategy is present but not yet tuned as a full release-quality desktop attention model across macOS, Windows, and Linux
|
||||
|
||||
## Electron / Security / Release Audit
|
||||
|
||||
### Security Baseline
|
||||
|
||||
Status: mostly aligned
|
||||
|
||||
Confirmed:
|
||||
|
||||
- secure BrowserWindow defaults are in place
|
||||
- renderer does not receive raw Node primitives
|
||||
- preload uses typed IPC contract calls
|
||||
- utility process is used for background orchestration work
|
||||
- vault prefers OS-backed secret storage
|
||||
|
||||
New hardening applied:
|
||||
|
||||
- runtime env no longer forwards host `NODE_OPTIONS`
|
||||
- pending-hire governance cannot be bypassed from renderer IPC
|
||||
|
||||
Still open:
|
||||
|
||||
- preload surface is broader than ideal for a production app of this size
|
||||
- some domain rules are enforced in handlers rather than at a smaller dedicated policy layer
|
||||
|
||||
### Packaging / Release
|
||||
|
||||
Status: partially complete
|
||||
|
||||
Confirmed:
|
||||
|
||||
- `electron-builder.yml` targets macOS, Windows, Linux
|
||||
- build script cleans `/build`, stages a non-mutating build version, and outputs into `/build/release`
|
||||
- e2e and build use the current Electron/Vite packaging path correctly
|
||||
|
||||
Still open:
|
||||
|
||||
- this audit validated runtime on the current local platform only
|
||||
- cross-platform runtime differences and signing/notarization behavior still need explicit validation evidence per target platform
|
||||
- updater flow currently checks availability but does not yet provide a fully operator-visible download/install lifecycle
|
||||
|
||||
### Performance
|
||||
|
||||
Status: acceptable for current prototype depth, not yet release-optimized
|
||||
|
||||
Evidence:
|
||||
|
||||
- app launches and is usable in live runtime checks
|
||||
- worker isolation prevents heavy agent runs from living in renderer
|
||||
|
||||
Remaining risk:
|
||||
|
||||
- renderer build currently produces an approximately `1.7 MB` main JS chunk, which is too large for a polished long-term desktop shell
|
||||
- mega-components still make fine-grained performance work harder than it should be
|
||||
|
||||
## External Research Used
|
||||
|
||||
Primary references used for this audit:
|
||||
|
||||
- Electron security checklist: https://www.electronjs.org/docs/latest/tutorial/security
|
||||
- Electron process model / utility process guidance: https://www.electronjs.org/docs/latest/tutorial/process-model
|
||||
- Electron safe storage API: https://www.electronjs.org/docs/latest/api/safe-storage
|
||||
- electron-builder auto-update guidance: https://www.electron.build/auto-update
|
||||
|
||||
These references were used to validate:
|
||||
|
||||
- secure BrowserWindow / preload expectations
|
||||
- utility-process suitability for background work
|
||||
- safe secret storage expectations
|
||||
- updater/build configuration direction
|
||||
|
||||
## Remediation Implemented In This Wave
|
||||
|
||||
Files changed in this wave:
|
||||
|
||||
- `src/shared/contracts.ts`
|
||||
- `src/preload/index.ts`
|
||||
- `src/main/runtime-env.ts`
|
||||
- `src/main/database.ts`
|
||||
- `src/main/ipc-core-work-graph-handlers.ts`
|
||||
- `src/renderer/components/organization.tsx`
|
||||
- `src/renderer/App.tsx`
|
||||
|
||||
Concrete changes:
|
||||
|
||||
- added typed `requestHire` contract and preload API
|
||||
- added transactional `createHireRequest(...)` database path
|
||||
- rerouted renderer new-agent flow into hiring / approvals pipeline
|
||||
- blocked direct renderer IPC creation of active agents
|
||||
- blocked direct renderer status promotion of pending hires
|
||||
- tightened runtime env inheritance by removing `NODE_OPTIONS`
|
||||
|
||||
## Remaining High-Value Follow-Ups
|
||||
|
||||
1. Split `App.tsx`, `database.ts`, `api-server.ts`, `automation-service.ts`, `communication.tsx`, and `execution.tsx` into smaller domain slices.
|
||||
2. Pull wake / publish / automation side effects into an explicit domain-event policy layer instead of leaving them distributed in orchestration-heavy modules.
|
||||
3. Shrink the renderer entry chunk with section-level lazy loading for heavyweight desktop panels.
|
||||
4. Make updater lifecycle operator-visible beyond availability checks.
|
||||
5. Validate runtime behavior on Windows and Linux rather than relying only on configured targets.
|
||||
Reference in new issue
Block a user