codebase-summary.md

Codebase Summary

Repository Layout

Top-level repo currently contains:

• spec-studio-manager/: the desktop application
• docs/: repo-level specs, plans, memory, and project docs
• plans/: repo-level implementation notes and historical plans
• local-only tooling folders such as .claude/ and .agents/

Application Layout

spec-studio-manager/ is the main product workspace.

Backend and runtime

• app.go

  • Wails entrypoint
  • bridges UI actions to backend services
  • starts and restarts the self-agent runtime

• cmd/remote-agent/

  • standalone remote-agent entrypoint
  • local config load/save
  • pair-only bootstrap, auth reconnect, and runtime startup
  • process smoke coverage for pair/run/dispatch on the current hub protocol

• backend/models/

  • shared DTOs for Wails bridge and dashboard state
  • includes structured browser task payload types
  • includes internal-goal DTOs for the goals surface

• backend/services/

  • SQLite schema, seed, queries, and mutations
  • hub WebSocket server
  • pairing token lifecycle
  • execution dispatch and timeout reconciliation
  • self-agent Donut connection/profile helpers
  • execution retention preview, cleanup, and persisted policy config
  • internal-goal persistence (CRUD/progress/status/delete)

• agent/

  • agent supervisor protocol client
  • runtime loop
  • worker runner
  • embedded worker asset materialization for non-checkout environments
  • Donut API client
  • Node browser worker

Frontend

• frontend/src/router.tsx

  • hash-routed runtime shell entry with summary, queue, executions, runtime, machines, and goals routes

• frontend/src/pages/dashboard-runtime-shell.tsx

  • shared operator shell with sidebar, top bar, route outlet, and status panel

• frontend/src/pages/dashboard-runtime-controller.ts

  • route-level orchestration for polling, actions, and shared runtime state across routed surfaces

• frontend/src/pages/dashboard.tsx

  • overview route for machine health, agent cards, and recent activity

• frontend/src/pages/task-queue.tsx

  • queue route for browser task creation and queued task control

• frontend/src/pages/execution-history.tsx

  • execution route for recent execution history and artifact inspection

• frontend/src/pages/runtime-settings.tsx

  • runtime settings route for pairing, self-agent controls, runtime fleet visibility, and execution retention policy

• frontend/src/pages/machines.tsx

  • machine/runtime route for runtime-aware machine rows from the hub store

• frontend/src/pages/goals.tsx

  • internal goals route for ops-goal tracking with search/status filters/counts/create/progress/status/delete actions

• frontend/src/components/

  • operator panels for agents, queue, executions, pairing, self-agent runtime, and internal goals
  • execution retention panel with preview, prune, and startup policy controls
  • remote-agent enrollment helpers and copyable command snippets for manual LAN pairing
  • browser task form now captures URL, wait selector, and JSON action steps
  • route surfaces are componentized across top bar, sidebar, agent detail, recent activity, queue, execution, pairing, runtime, machine, and goals panels

• frontend/src/lib/

  • Wails bridge wrappers and dashboard utility helpers

• frontend/src/hooks/

  • polling and dashboard refresh logic

Scripts and verification

• scripts/agent-dev-loop.js

  • full local verification gate

• scripts/donut-local-smoke.mjs

  • browser worker smoke helper for simulate, donut, and local-playwright

• scripts/capture-dashboard-screenshot.mjs

  • route-aware screenshot capture for product docs

Data Model Summary

Main runtime tables:

• agents
• agent_runtime_state
• pairing_tokens
• tasks
• executions
• internal_goals

Legacy/supporting tables still present:

• machine_status
• scheduled_tasks
• activity_logs
• backup_history

internal_goals v1 columns include:

• title
• metricKey
• currentValue
• targetValue
• unit
• status
• dueAt
• trend_json (JSON text stored in-row for v1)
• timestamps

Behavior notes:

• goal deletion is hard-delete in v1
• currentValue may exceed targetValue to represent over-achievement

Runtime Flow Summary

High-level runtime flow:

1. Hub creates or leases a task from SQLite
2. Supervisor authenticates and receives hub.execution.assign
3. Agent accepts, starts, and runs the browser executor
4. Worker executes structured browser payload and reports progress/final artifacts
5. Hub updates executions, tasks, and agent_runtime_state
6. Timeout reconciliation requeues or fails stuck work

Internal goals flow (v1):

1. Operator navigates to /goals from runtime shell sidebar (Muc tieu noi bo)
2. UI calls Wails bridge methods to create/list/update/delete local goals
3. Store persists goal rows in SQLite internal_goals
4. UI updates filtered counts/status views and renders trend snapshots from trend_json

Execution Modes

Current worker supports:

• simulate
• donut
• local-playwright

Current built-in recipe ids:

• open-page-snapshot
• local-navigation-demo
• local-queue-triage-demo
• local-login-demo
• local-form-demo
• local-checklist-demo
• local-settings-demo

Browser task payload supports:

• optional recipeId
• url for network-backed recipes
• embedded local deterministic recipes that do not require a URL
• dashboard self-agent local smoke runs now use the embedded deterministic local recipe path instead of relying on https://example.com

Current action support:

• wait_for
• wait_for_url
• click
• hover
• check
• uncheck
• fill
• press
• select_option
• assert_text
• assert_value
• assert_title
• assert_url
• assert_visible
• not_contains
• not_url
• not_visible
• assert_count

Current match mode support:

• contains
• exact
• regex for assert_text and assert_url

Verification

Primary verification command:

npm run agent:dev:loop

Latest local verification: green on 2026-05-12 after shipping Internal Goal UI v1 and syncing docs.

Current validation scope includes:

• go test ./...
• npm run lint
• npm run test
• npm run test:smoke
• npm run build
• wails build -platform windows/amd64

Explicit Non-goals for Internal Goal UI v1

• no GA4/GSC/Stripe/email integrations
• no cloud sync
• no marketing analytics suite behavior
• no agent lifecycle/protocol changes