Skip to content

0.6.0 — the fleet UI

Choose a tag to compare

@AnmolMajithia AnmolMajithia released this 04 Sep 15:01
· 3412 commits to main since this release
f4c3387

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: asq with 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 attach shows the same session from any terminal. New fleet
    group — spawn · ls · status · tell · stop · attach · reap · rename · pause · resume, --json everywhere — and an explicit ui command. Fleet roles
    manager (the planner with fleet authority), tester (the fleet's name for
    runner) and reviewer (read-only PR review), which launch accepts too.
    Store schema v11: fleet_agent, and a per-project codename
    (adjective-animal, deterministic from the project id; fleet rename
    changes it) that names the tmux session and the fleet/<codename>/…
    branches. A [fleet] config section in which every value is a default —
    permission mode auto for every role, a worktree per coder and reviewer,
    four agents per project, F12 as the escape key, Claude's native agent
    teams off in fleet launches — overridable per spawn or
    in config. Scripts, pipes and --json callers of bare aisquare still 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
    check job 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-down errored on the three test_runbook_json_paths.py tests and
      proxy-up on test_json_stdout_is_empty_or_parseable[proxy-down] — disjoint,
      neither catching the other's, while all three check variants 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 status rather than a curl at a literal port: it
      probes whatever the config says, so it cannot drift from what the suite
      reads, and it checks the service/mode contract 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_HOME plus the explainability variables
      tests/conftest.py goes 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 to check twice, green. Deliberately
      NOT a job-level env: block — that was tried and rejected: runner.temp is
      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 unknown matrix property
      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.py rather than inlining a server: probe_proxy
      checks service and mode, 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), so package covers that axis at import level instead.
  • 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 one site-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 six explainability subcommands,
    because --version cannot distinguish a build that has this integration from
    one that does not.
  • tests/test_ci_covers_the_ambient_environment.py pins 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 serve runs on mcp 2.x. The serve and dev extras require
    mcp>=2.1,<3 (was >=1.10,<2). mcp 2.0.0 renamed FastMCP to MCPServer and
    deleted mcp.server.fastmcp, the module this CLI imported, so the Dependabot
    bump (#73) went red on mypy and the <2 pin was the only thing keeping a
    fresh install green. The port is confined to services/mcp_server.py, the
    serve dependency 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's ToolError into Error 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 sees error: reopen requires a note (the feedback), verbatim,
      as an isError result — tests/test_serve.py asserts 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 sees Error 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_side pins both
      halves: nothing of the exception on the wire, all of it in the log.
    • HTTP transport settings moved off the server object: host is 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 serve guard probes mcp.server.mcpserver, and its message for an
      incompatible major points the other way now — a 1.x is the one that cannot
      work — with pip 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.py drives the server through mcp.client.Client(server),
      the in-memory replacement for the removed
      create_connected_server_and_client_session, and reads is_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 the UnexpectedToolError
      import — the distinction above did not exist yet, so >=2.1.

pip install aisquare-cli (or pipx install aisquare-cli) resolves to this version. Full diff: v0.5.0...v0.6.0