Repository navigation
0.6.0 — the fleet UI
The fleet UI: bare asq opens one view over every project, agent and
session. This is the first release where the CLI has a front door — a
two-pane, mouse-driven terminal UI over your projects, the manager agent in
each, and the agents that manager spawns, every one of them a real Claude Code
session you can type into. Everything it does is still a plain command with
--json, and both halves below it — memory and orchestration — work exactly as
they did without ever opening it.
Shipping ahead of feature-complete on purpose, to make internal testing easier;
known gaps are listed in docs/plans/fleet-tui.md and land as 0.6.x.
Added
- The fleet:
asqwith no arguments opens one view over every project,
agent and session. A two-pane, mouse-driven UI — a navigator of projects,
the agents running in each and a Doctor summary on the left; onboarding, a
project's manager (an agent you task in prose, which plans, spawns and
steers the others), any agent's real Claude Code session, the board and
doctor findings with their fixes on the right. Never a chat relayed through
us: agents run as windows of a per-project session on a private tmux server
(tmux -L asq, bundled config, tmux ≥ 3.2), so they outlive the UI and
aisquare fleet attachshows the same session from any terminal. Newfleet
group —spawn · ls · status · tell · stop · attach · reap · rename · pause · resume,--jsoneverywhere — and an explicituicommand. Fleet roles
manager(the planner with fleet authority),tester(the fleet's name for
runner) andreviewer(read-only PR review), whichlaunchaccepts too.
Store schema v11:fleet_agent, and a per-projectcodename
(adjective-animal, deterministic from the project id;fleet rename
changes it) that names the tmux session and thefleet/<codename>/…
branches. A[fleet]config section in which every value is a default —
permission modeautofor every role, a worktree per coder and reviewer,
four agents per project,F12as the escape key, Claude's native agent
teams off in fleet launches — overridable per spawn or
in config. Scripts, pipes and--jsoncallers of bareaisquarestill get
usage and exit 2. User guide:docs/fleet.md; the plan and its decisions
log:docs/plans/fleet-tui.md. Delivered in phases (plan §9); the plan's
Decisions log records what has landed. - CI runs the suite against a machine that looks like a developer's. The
checkjob installs.[dev]into a pristine runner — no~/.aisquare,
nothing listening on any port, no optional extra — while anyone who followed
the setup guide has all three. Three fixtures in this repo were green here and
red for them, and the third was introduced while fixing the second, which is
what moves this from "be careful" to "have a job".- Two variants, because the leaks need opposite proxy states. Measured in
CI, not assumed: with both regressions reintroduced on a throwaway branch,
proxy-downerrored on the threetest_runbook_json_paths.pytests and
proxy-upontest_json_stdout_is_empty_or_parseable[proxy-down]— disjoint,
neither catching the other's, while all threecheckvariants stayed green.
One configuration would have covered half the class and looked like it
covered the class. - Both variants assert their own premise, on both sides of the suite, using
aisquare explainability statusrather than acurlat a literal port: it
probes whatever the config says, so it cannot drift from what the suite
reads, and it checks theservice/modecontract rather than "something
answered 200". A variant whose distinguishing condition never held, or which
lost it midway, is a job reporting the other variant twice — so it fails
instead, before or after the suite, saying which. - The ambient environment has one definition, exported through
$GITHUB_ENV:AISQUARE_HOMEplus the explainability variables
tests/conftest.pygoes out of its way to clear, whose own comment notes an
operator's shell has them sourced. A per-step home could be dropped from the
step that runs pytest, degrading the job tochecktwice, green. Deliberately
NOT a job-levelenv:block — that was tried and rejected:runner.tempis
unavailable there and GitHub rejects the whole workflow file for it, a
near-silent failure that yields a run with zero jobs and no log, and reads
from outside as "CI has not started". - The variant name is checked against a closed set before anything
dispatches on it. Every dispatch is[ "$AMBIENT" = "proxy-up" ], so any
other value — including the empty string, which is what deleting the export
or renaming the matrix key produces, since an unknownmatrixproperty
expands to""with no error — is silently proxy-down, and the matrix reports
both of its names having run one ambient. - It reuses
tests/proxy_stub.pyrather than inlining a server:probe_proxy
checksserviceandmode, so a stub is a contract, and the copy nobody
runs locally is the one that drifts. - Two of the three conditions above are reproduced, and the job says so: the
extra cannot be installed where the suite runs (it shadows an editable
checkout), sopackagecovers that axis at import level instead.
- Two variants, because the leaks need opposite proxy states. Measured in
- The packaging job installs the extra.
pip install "aisquare-cli[explainability]"is the line the setup guide gives people and
nothing tested it. The SDK shares this package's top-level import name, so both
distributions land in onesite-packages/aisquare/and the last writer wins
the shared__init__.py— a build that read__version__off that module died
at import with the extra installed, and no job would have caught it. The job
asserts both packages import and names the sixexplainabilitysubcommands,
because--versioncannot distinguish a build that has this integration from
one that does not. tests/test_ci_covers_the_ambient_environment.pypins all of the above. Its
checks assert the order and placement of things inside the job rather than
the presence of a string in the file, because an independent review mutated the
literal version and found five ways to make the job vacuous with every guard
green — drop the home from the step that matters, hardcode the stub's port,
delete either premise assertion, run pytest ahead of the listener, or invert
the variant condition so the two run under each other's names. Each of those is
caught now, and the edits a maintainer would legitimately make — reordering the
variants, adding a third, rewriting the matrix in block style — do not cause a
false failure.
Changed
aisquare serveruns on mcp 2.x. Theserveanddevextras require
mcp>=2.1,<3(was>=1.10,<2). mcp 2.0.0 renamedFastMCPtoMCPServerand
deletedmcp.server.fastmcp, the module this CLI imported, so the Dependabot
bump (#73) went red on mypy and the<2pin was the only thing keeping a
fresh install green. The port is confined toservices/mcp_server.py, the
servedependency guard, and the two test files that drive them; the nine
tools, their wording, and both transports' behaviour are unchanged.- The error-wording contract survives, on the seam the SDK now provides.
mcp 2 still folds a tool'sToolErrorintoError executing tool <name>: <msg>, so the handler that unwraps our own message back out is still
needed. It moves from the removed_mcp_server.call_tool()decorator to
add_request_handler("tools/call", …)on_lowlevel_server, which is what
the SDK's own migration guide names for replacing a protocol handler (and
what the SDK itself uses to wrap this method for extensions). A remote
agent still seeserror: reopen requires a note (the feedback), verbatim,
as anisErrorresult —tests/test_serve.pyasserts every one of those
strings end-to-end through a real client session. - A crashed tool is now logged server-side. New in mcp 2.1, not chosen
here: the SDK tells a crash apart from a deliberate failure by type
(UnexpectedToolError) and keeps the crash's detail off the wire, so the
agent seesError executing tool <name>and nothing else. In 1.x the
message rode along in the result, which was the only place it went. The
replacement handler logs the traceback on the server (stderr, which is
never the protocol channel on either transport) where the SDK's own handler
would have, so a bug in a tool is still readable somewhere. A rejected
argument set is the caller's mistake, not a crash, and is not logged as
one.test_a_crashed_tool_is_an_error_result_logged_server_sidepins both
halves: nothing of the exception on the wire, all of it in the log. - HTTP transport settings moved off the server object:
hostis passed to
streamable_http_app(), whose only use for it is deciding whether loopback
DNS-rebinding protection auto-enables (it does, as before), and the port is
uvicorn's alone, as it already was. - The
serveguard probesmcp.server.mcpserver, and its message for an
incompatible major points the other way now — a 1.x is the one that cannot
work — withpip install 'mcp>=2.1,<3'. The distribution-versus-module
distinction it was written for (#55) is exactly what makes a 1.x a
sentence rather than a traceback. It tells majors apart, not minors: the
pin is what keeps a 2.0.x out, and pip reports that at install time. tests/test_serve.pydrives the server throughmcp.client.Client(server),
the in-memory replacement for the removed
create_connected_server_and_client_session, and readsis_error: field
names are snake_case in 2.x.- Also inherited from 2.x: synchronous tool bodies run on a worker thread
rather than inline on the event loop. Each of the nine opens its own store
session per call and touches nothing thread-affine, so nothing crosses. - The floor is measured, not guessed: against every 2.x release on PyPI,
the serve suite, the stdio idle-deadline suite and mypy strict are green on
2.1.0 and 2.1.1, and 2.0.0 and 2.0.1 fail on theUnexpectedToolError
import — the distinction above did not exist yet, so>=2.1.
- The error-wording contract survives, on the seam the SDK now provides.
pip install aisquare-cli (or pipx install aisquare-cli) resolves to this version. Full diff: v0.5.0...v0.6.0