looop 0.16.0

A tiny, portable, Kubernetes-shaped control loop for your work
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

//! `looop --help` / `looop help` — emits the FULL design manual (mechanism +
//! intent), not just a subcommand list. The static narrative lives in
//! `manual.txt` and is embedded at compile time; the Usage / Paths sections are
//! rendered here with live config/data paths (mirroring the bash heredoc).

use crate::paths::Paths;

/// The mechanism + intent narrative (THE IDEA, THREE NOUNS, ONE BEAT, RULES,
/// CODE/CONFIG/DATA, BOOTSTRAP, DEPENDENCIES), embedded from manual.txt.
const MANUAL: &str = include_str!("manual.txt");

pub fn print(paths: &Paths) {
    print!("{MANUAL}");
    println!(
        r#"
Usage:
  HUMAN (that's nearly all you run — the rest you do through your agent):
  looop up [--json]              start the pulse (sensing loop, detached).
                                --json makes the pulse log NDJSON. Then start your
                                agent yourself and tell it to observe looop.
  looop down                     stop the pulse and all workers
  looop cost [today|all|--json]  report LLM spend (agents self-report via `_ cost`)
  looop config zsh|bash          print shell integration (completions)
  looop version | help           print version / show this help

  ROOT AGENT (the pi/claude session YOU run — see the CONTRACT above):
  looop _ state [--json] | _ wait [--json]             read state (blocking with --wait)
  looop _ answer <ask_id> "<text>"           resolve a worker's pending ask
  looop _ goal write <id> [body|stdin] | _ goal archive <id>
  looop _ sensor write <name> [script|stdin]
  looop _ playbook write [body|stdin]
  looop _ run <cmd…> [--reason T]            ONE reversible shell command
  looop _ worker start <id> <prompt…> | _ worker kill <id>
  looop _ notify <message…>                  surface a notice to the human

  WORKER self-callbacks (auto-injected CONTRACT — not for humans):
  looop _ ask <id> --prompt "…" [--ref P] [--options a,b]   ask + block for answer
  looop _ kill <id> | _ claim <name> | _ unclaim <name> | _ cost <…>

Paths (override via env LOOOP_CONFIG / LOOOP_DATA_DIR):
  config    {config}
  data      {data}
  sessions  {fleet}

looop is a single self-contained binary: session management (babysit) is linked
as a LIBRARY and driven entirely in-process — no `babysit` executable required.
You run your own agent and tell it to observe looop (loop on `looop _ wait
--json`); it decides and drives looop through the `_ …` verbs. Worker self-control
verbs (ask / kill / claim / unclaim / cost) are auto-injected callbacks.

The root agent launches each worker in the data dir; a worker that touches code
provisions its OWN sandbox (box if available, else git worktree). looop itself
has no notion of repos. Change judgment with `looop _ playbook write` / `_ goal
write` — it takes effect next beat. (looop does not version the data dir; `git
init` it yourself for history.)"#,
        config = paths.config.display(),
        data = paths.data_dir.display(),
        fleet = paths.data_dir.join("sessions").display(),
    );
}