70 lines
2.3 KiB
Markdown
70 lines
2.3 KiB
Markdown
# Mosaic tmux Fleet PoC
|
|
|
|
This directory contains the first durable tmux-backed fleet primitives for the
|
|
Mosaic software-factory model.
|
|
|
|
The lifecycle model follows the organization-neutral AI Guide playbook
|
|
`mosaicstack/aiguide:playbooks/tmux-fleet.md` (commit `2a0b0b5`): a dedicated
|
|
holder owns the tmux server/socket; agent units join it and stop only their own
|
|
exact-match session.
|
|
|
|
## Layout
|
|
|
|
- `mosaic-tmux-holder.service` — user-mode holder that owns the named tmux server.
|
|
- `mosaic-agent@.service` — user-mode template for one reusable agent session.
|
|
- `mosaic-interaction-agent@.service` — generic Pi operator-interaction template
|
|
that fails fast when its pinned runtime policy is incomplete or changed.
|
|
- `test-fleet-units.sh` — validates unit syntax and required relationships.
|
|
|
|
The agent template calls:
|
|
|
|
```text
|
|
~/.config/mosaic/tools/fleet/start-agent-session.sh <agent-name>
|
|
```
|
|
|
|
which starts or reuses a tmux session on `MOSAIC_TMUX_SOCKET`.
|
|
|
|
## Local customization
|
|
|
|
Per-agent overrides live outside the package in:
|
|
|
|
```text
|
|
~/.config/mosaic/fleet/agents/<agent>.env
|
|
```
|
|
|
|
Example:
|
|
|
|
```dotenv
|
|
MOSAIC_TMUX_SOCKET=mosaic-fleet
|
|
MOSAIC_AGENT_RUNTIME=claude
|
|
MOSAIC_AGENT_WORKDIR=$HOME/src/your-project
|
|
# Optional escape hatch for PoC/canary agents:
|
|
# MOSAIC_AGENT_COMMAND=mosaic yolo claude
|
|
```
|
|
|
|
## Manual canary sequence
|
|
|
|
```bash
|
|
mkdir -p ~/.config/systemd/user ~/.config/mosaic/tools/fleet ~/.config/mosaic/fleet/agents
|
|
cp packages/mosaic/framework/systemd/user/mosaic-*.service ~/.config/systemd/user/
|
|
cp packages/mosaic/framework/tools/fleet/*.sh ~/.config/mosaic/tools/fleet/
|
|
chmod +x ~/.config/mosaic/tools/fleet/*.sh
|
|
systemctl --user daemon-reload
|
|
systemctl --user start mosaic-tmux-holder.service
|
|
systemctl --user start mosaic-agent@canary.service
|
|
tmux -L mosaic-fleet ls
|
|
|
|
# For an operator-interaction service, the roster/env identity selects the
|
|
# generic unit instance; no service source is renamed for an instance.
|
|
systemctl --user start mosaic-interaction-agent@<agent-name>.service
|
|
MOSAIC_AGENT_NAME=<agent-name> \
|
|
MOSAIC_AGENT_RUNTIME=pi \
|
|
MOSAIC_AGENT_MODEL=openai/gpt-5.6-sol \
|
|
MOSAIC_AGENT_REASONING=high \
|
|
MOSAIC_AGENT_TOOL_POLICY=operator-interaction \
|
|
~/.config/mosaic/tools/fleet/print-interaction-effective-policy.sh
|
|
```
|
|
|
|
Do not use `tmux kill-server` without `-L mosaic-fleet`; this pattern is meant
|
|
to avoid disturbing the user's default tmux server.
|