Files

T

jason.woltje 7db4c5c2ed feat(agent): interactive TUI launcher + identity + TOOLS.md (#35 )

- scripts/agent.sh <name>: launches interactive pi TUI in the container
  with contracts + optional mission + agent identity + named session +
  optional workspace/tools; the Mosaic alternative to vanilla pi
- pi adapter: MOSAIC_INTERACTIVE branch (clean TUI, no -p, no initial
  prompt); headless exec rebuilt via positional args (no word-splitting
  on the request); MOSAIC_AGENT_NAME optional in headless
- loader: AGENT IDENTITY section when the launcher names the agent
- compose: fixed command removed (request defaults live in run-agent.sh);
  MOSAIC_INTERACTIVE/MOSAIC_AGENT_NAME passthrough
- docs/TOOLS.md: full on-demand tool reference; AGENTS.md routes to it
- RELEASE -> 0.0.8 (container change); build verified

Closes #35

2026-09-03 11:24:56 -05:00

4.0 KiB

Raw Blame History

TOOLS.md — command and tool reference

On-demand reference for agent sessions (conductors, bootstrapping agents, reviewers). AGENTS.md routes here; this file carries the depth: usage, inputs/outputs, exit codes, and safety notes for every entry point.

Reading guide: all entry points are scripts/*.sh (bash) or invoked via node scripts/mosaic-task.mjs (node). Every script fails closed — missing or invalid configuration/policy refuses the operation with a nonzero exit and changes nothing.

Lifecycle

Command	Purpose	Notes
`scripts/bootstrap.sh`	Create `~/.config/mosaic-dev/config.json` if absent	Idempotent; existing config validated, never rewritten
`scripts/build.sh`	Build the release image	Tag derived from `RELEASE` + pinned pi version
`scripts/hello.sh`	One-shot startup request	Prints model response on stdout
`scripts/verify.sh`	Full gated test	Exit 0 only on exact `MOSAIC_HELLO_OK`; `EXPECTED_MARKER` overrides for negative drills

Tasks (missions, runs, evidence)

Command	Purpose	Notes
`scripts/run-task.sh run <task.json>`	Execute a task	Immutable run record under `<dataRoot>/runs/`
`scripts/run-task.sh validate <task.json>`	Strict validation	Writes nothing
`node scripts/mosaic-task.mjs show <runId>`	Inspect a run	Full record + snapshots + artifacts
`node scripts/mosaic-task.mjs list`	List runs	task/workspace/session columns
`node scripts/mosaic-task.mjs retry <runId>`	Re-execute a run's snapshot	New run dir; `retriedFrom` lineage recorded
`node scripts/mosaic-task.mjs prune [--keep=N] [--yes]`	Retention	Dry-run default; receipt in `runs/.pruned.log`

Task fields: prompt (required), mission (path), expectExact, timeoutSeconds (5–600), workspace (:run or named), capabilities.tools (allowlist: read write edit bash grep find ls), session, sessionForkFrom (requires session). Mission fields: objective, directives[], optional governing capabilities.tools. Policy: a task may narrow a mission's tools, never widen; empty intersection = tool-free run.

Agent (interactive TUI)

scripts/agent.sh <name> [--mission <file>] [--workspace <ws>] [--session <s>] [--tools <list>]

Launches an interactive pi TUI inside the container with the four immutable contracts + optional mission + agent identity as its system prompt, persistent named session, optional workspace. Exit with /quit.

Release

Command	Purpose	Notes
`scripts/release.sh package`	Build + tag the release image	Tag: `mosaic-poc-agent:<pi>-r<release>`
`scripts/release.sh activate`	Health gate → atomic pointer swap	`--fault-injection` proves the refusal path
`scripts/release.sh rollback`	Health-gated return to previous	Refuses if image missing
`scripts/release.sh status`	Release, tag, active pointer, log	Safe on empty state

Conductor (worker patches)

scripts/conductor-apply.sh <runId> [--dry-run]

Auto-applies a worker's patch under roles/conductor-policy.json: succeeded run → clean target tree → path allowlist → syntax gates → apply → policy suites → attribution commit. Any failure reverts. Push is never automatic.

Maintenance

Command	Purpose	Notes
`scripts/reset.sh`	Delete the data root	Triple-safety-checked (path, symlink, ownership marker)
`scripts/test-config.sh`	Config selftests (no Docker)	24 cases
`scripts/test-task.sh`	Task selftests + live cases	58 cases
`scripts/test-release.sh`	Release selftests	14 cases
`scripts/test-conductor.sh`	Auto-apply selftests (sandboxed)	17 cases
`scripts/gitea-api.sh <METHOD> <path> [body]`	Gitea API helper	Token never on argv/stdout

Exit-code convention

0 success · 1 operation failed · 2 invalid data/configuration · 3 configuration missing for a read operation · 4 usage/file/environment problem. Scripts print diagnostics on stderr; model responses (and only model responses) on stdout.

4.0 KiB Raw Blame History Unescape Escape