514946fd8b
* docs: grounded spec for ao start bootstrapper + npm deprecation Real-codebase-verified implementation spec (Track A: launcher + app-state marker + release asset wiring). Replaces the somthing.md draft's aspirational assumptions with file:line ground truth: correct bundle name (Agent Orchestrator.app), publish repo (aoagents/agent-orchestrator), draft-release + asset-rename gaps, unsigned-build reality, and the already-wired update-electron-app updater. Includes a dependency-ordered task breakdown for AO execution. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: reframe spec around Go ao start subcommand (not a JS launcher) The npm package ships the existing Go cobra CLI (backend/cmd/ao); this effort rewrites the `ao start` subcommand to fetch+open the desktop app. Corrections: - releases land on AgentWrapper/agent-orchestrator (aoagents was the temporary rewrite home; forge publisher must be repointed) - ao start stops starting the daemon; the frontend owns the daemon - adds the real Go CLI command surface (1.7), the npm-delivery gap for the Go binary (1.6), and the legacy first-boot import decision (6.4) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: separate prod vs test release targets in ao start spec Dev/test loop must never cut a production release. Download repo + forge publisher + npm scope are now build-time overridable: - prod: AgentWrapper/agent-orchestrator + real package name - test: harshitsinghbhandari/agent-orchestrator (fork) + @theharshitsingh/ao T3/T5 now release+test against the fork and the test scope, with prod cut as a separate gated step. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * feat(cli): rewrite ao start to fetch + open the desktop app (T1) ao start no longer starts the daemon (the desktop app owns it). It now resolves the installed app (~/.ao/app-state.json marker -> stat -> known- location scan), fetches the latest release zip and ditto-unpacks it on macOS when absent, opens it with --installed-via=npm-bootstrap, and prints an honest deprecation notice. releaseRepo is build-time overridable (-ldflags) so test builds fetch from the fork. Windows/Linux fetch/open are stubbed for T6/T7. Review fixes folded in: download() copies deps.HTTPClient and drops its 2s loopback-probe timeout (a real release asset is hundreds of MB), and fetchApp clears ~/.ao/staging before unpacking. Regression test covers the timeout. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * feat(desktop): write ~/.ao/app-state.json marker on launch (T4) The app is the sole writer of the marker ao start reads to locate the bundle. New frontend/src/main/app-state.ts does an atomic temp+rename write mirroring the daemon's runfile.Write, preserving installedAt/installSource across launches and refreshing appPath/version/lastReconciledAt. main.ts hooks it into app.whenReady ordered relocate (macOS) -> write marker -> createWindow, both non-fatal. Bundle path is derived from process.execPath (not app.getAppPath, which is the asar path); JSON keys match start.go's appState reader exactly. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * ci(desktop-release): overridable repo, published release, stable asset aliases (T3) Make the bootstrapper's constant releases/latest/download URL resolve: - forge publisher repo reads AO_RELEASE_REPO (default AgentWrapper/agent- orchestrator); the workflow sets it to github.repository so a fork run publishes to the fork and never to prod - draft:false so the release is immediately live (constant URL needs it) - add ubuntu-latest to the matrix (issue #2191) - post-publish steps upload stable space-free aliases (agent-orchestrator-darwin-arm64.zip, agent-orchestrator-win32-x64.exe) matching exactly what start.go fetches Review fix: the alias upload targeted GITHUB_REF_NAME (the git tag), but publisher-github creates the release as v<package.json version>; retargeted to that and relaxed the guard so workflow_dispatch also produces aliases. Known gaps (documented inline): macOS x64 needs an Intel runner (macos-latest is arm64-only); the Linux stable asset name awaits the deb/rpm-vs-AppImage decision. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore: format with prettier [skip ci] * feat(npm): deliver Go ao binary as @aoagents/ao via per-platform packages (T2) Ship the ao CLI to npm with ZERO install scripts using the esbuild model: - packages/ao: pure-JS @aoagents/ao with a bin/ao.js shim that resolves and execs the matching @aoagents/ao-<platform>-<arch> optionalDependency - four platform packages (darwin-arm64/x64, win32-x64, linux-x64), each os/cpu gated so npm installs only the host's; binary cross-compiled CGO-free (modernc.org/sqlite), gitignored, shipped via files - build-binaries.sh cross-compiles all four; releaseRepo keeps its prod default Not added as root workspaces on purpose: os/cpu-restricted members make root `npm ci` fail EBADPLATFORM (CI's api-drift job runs it). Packages publish standalone; the shim was verified in a published-like layout. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore(npm): set @aoagents/ao packages to 0.10.0 (above existing 0.9.5) The existing @aoagents/ao on npm is 0.9.5; the launcher must publish a higher version so npm latest advances and existing users get the new fetch-and-open binary on update. All five packages plus the four optionalDeps pins set to 0.10.0. * chore: format with prettier [skip ci] * fix(start): capture install provenance before macOS relocation moveToApplicationsFolder() relaunches the app from /Applications without forwarding the --installed-via arg, and code past a successful move never runs in the staging instance. The post-move instance therefore wrote installSource="unknown", and writeAppStateMarker's sticky logic then locked it there, losing the npm-bootstrap provenance in the exact path it exists for. Write the marker before relocation when --installed-via is present so the source is persisted while the arg is still available; the post-move launch preserves it (sticky installSource) while refreshing appPath to /Applications. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore: format with prettier [skip ci] --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> |
||
|---|---|---|
| .. | ||
| agent | ||
| cli | ||
| plans | ||
| superpowers | ||
| README.md | ||
| STATUS.md | ||
| ao-start-bootstrapper-and-npm-deprecation.md | ||
| architecture.md | ||
| backend-code-structure.md | ||
| daemon-environment.md | ||
| stack.md | ||
| telemetry.md | ||
README.md
agent-orchestrator rewrite docs
The agent-orchestrator is being rebuilt as a long-running Go backend daemon
(backend/) plus an Electron + TypeScript frontend (frontend/). The backend
supervises coding-agent sessions and exposes daemon control, project/session
state, terminal streaming, and CDC/event infrastructure.
Start with architecture.md for the current backend model and
cli/README.md for the CLI surface.
Reference docs
| Doc | What it covers |
|---|---|
| architecture.md | Current backend model, package layout, status derivation, persistence/CDC, and load-bearing rules. |
| backend-code-structure.md | Package ownership rules for the Go backend: domain, services, ports, adapters, storage, HTTP, CLI, and daemon wiring. |
| cli/README.md | CLI commands and daemon control surface. |
| agent/README.md | Agent adapter contract, hook methodology, and session-info derivation. |
| STATUS.md | What is shipped on main today and what is still in flight. |
| stack.md | Accepted library/runtime choices, pending stack decisions, and dependencies explicitly avoided for V1. |
Mental model
Persist durable facts, derive display status:
- session table:
activity_state,is_terminated, identity, metadata - PR tables: PR/CI/review facts
- derived read model:
service.Sessioncomputes display status from session + PR facts