aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authoruser <user@clank>2026-08-17 13:08:06 +0200
committeruser <user@clank>2026-08-17 13:08:06 +0200
commit244068e86c03b6c1bf457fac7e576bf5f68a43b7 (patch)
treec294bf9fdd75d6fb487cc3d820ec955d0f799146
parentsl0ppty: workspaces, and layouts that write themselves (diff)
downloadslosh-244068e86c03b6c1bf457fac7e576bf5f68a43b7.tar.gz
slosh-244068e86c03b6c1bf457fac7e576bf5f68a43b7.tar.xz
slosh-244068e86c03b6c1bf457fac7e576bf5f68a43b7.zip
sl0ppty: a skill for driving it, and the two variables that made one possible
`.agents/skills/driving-sl0ppty/SKILL.md`. The convention is `.agents/skills/<name>/SKILL.md` with YAML frontmatter -- already in this tree under `vendor/libghostty-vt`, so it is not an invention -- and it means an agent working in a checkout picks the skill up without being told, while a directory per skill leaves room for adjuncts later. `contrib/README.md` and `docs/scripting.md` say where it is and how to use it elsewhere: copy or symlink the directory into wherever your agent keeps skills. **Writing it turned up the reason there was no skill worth writing.** A pane is told `SL0PPTY=1` and nothing else, so a program inside one knows it is in a session and cannot find out *which* -- `ls` lists them all and none of them is labelled "the one you are in". So the whole most valuable case, an agent driving the session it is running in, was guesswork. The server now sets `SL0PPTY_SESSION` and `SL0PPTY_BIN` in its own environment, which every pane inherits through fork: one place, no signatures threaded, and unset under `--script`, which has no socket to name. `SL0PPTY_BIN` is read from `/proc/self/exe` rather than `argv[0]`, and exists because the failure it prevents is the one I hit writing the examples -- a session started from a build tree, and `sl0ppty` not on the pane's `PATH`, so the skill's own commands did not run. What the skill actually teaches, none of which `docs/scripting.md` says because a reference is not allowed to have opinions: - Work belongs in a pane that was **given** a command, not typed into somebody's shell. Then `alive` and `exit_code` off `panes` are how you wait, and the output survives the program (D14) so it is still there to read. - There is **no wait primitive over the socket**: `settle` is headless-only, and `deadline` is about repaints and says nothing about program output. Poll. - `purpose` is the handle. Titles change underneath you; a declared purpose cannot be relabelled by the program in the pane, which is what makes it safe to address. - `snapshot` is the whole composited session, and only what is on screen. Cut a pane out with its `content_*` rect; do not expect scrollback. - **The echoed command line matches your own marker.** `echo DONE` puts `DONE` on screen twice. Count, or use a marker you did not send. - Write `\e`, never `\033`: the unescaper takes `\0` first, so `\033` arrives as NUL followed by `33` and nothing complains. That bug was live in this repo's own test suite until last week. - A program in a pane can draw its own status and real buttons with OSC 5577 and read the click off its stdin, which is how it asks a question instead of printing a prompt and hoping. - Close what you made; do not `quit` a session you did not start. `tests/test_skill.py` is the part that keeps it true. A skill is documentation an agent acts on without a human reading it first, so a stale one is worse than a missing one: a wrong verb is a failed tool call somebody else has to debug. Every verb the file names is sent to a live session and must not answer `unknown cmd`; every `panes` field its central recipe polls must exist; the environment it promises is read out of a real pane; the recipe itself is run end to end and must report exit status 3 with its output still on screen. It also greps the file for paths out of a home directory, because "plug and play" is a property somebody has to keep. That test found `close-pane` in the draft, which is the *keybinding* action name -- the verb is `close`. Exactly the class of error the test exists for, found before anybody's agent ran it. Verified: 1795 checks, all green, 43 of them in `tests/test_skill.py`. Then the skill's recipe run verbatim against a real session -- tagged pane, polled to `alive:false`, `exit status: 3`, `compiling`/`built`/`exited: status 3` still readable -- and from inside a pane, `session=agentdemo bin=/…/sl0ppty` and a `building 3/7` status drawn in its own frame.
-rw-r--r--.agents/skills/driving-sl0ppty/SKILL.md273
-rw-r--r--contrib/README.md12
-rw-r--r--docs/scripting.md18
-rw-r--r--src/server.c19
-rwxr-xr-xtests/test_skill.py162
5 files changed, 484 insertions, 0 deletions
diff --git a/.agents/skills/driving-sl0ppty/SKILL.md b/.agents/skills/driving-sl0ppty/SKILL.md
new file mode 100644
index 0000000..150c3e8
--- /dev/null
+++ b/.agents/skills/driving-sl0ppty/SKILL.md
@@ -0,0 +1,273 @@
+---
+name: driving-sl0ppty
+description: >-
+ Drive a sl0ppty terminal multiplexer: run a long-lived command somewhere its
+ output can be watched, read a pane's screen, arrange panes and tabs, find a
+ pane by purpose, open a project workspace, and report progress or ask a
+ question from inside a pane. Activates when `SL0PPTY` is set in the
+ environment, when a task needs a dev server, log tailer or build left running
+ while other work continues, or when the user mentions sl0ppty, panes, tabs or
+ workspaces.
+---
+
+# Driving sl0ppty
+
+sl0ppty is a terminal multiplexer whose control socket does everything the
+keyboard does. One JSON object per line in, one JSON object out. A detached
+session answers exactly as an attached one does, so nothing here needs a
+terminal, a tty, or anybody watching.
+
+Two things make it worth driving rather than shelling out:
+
+- **A pane outlives the command that ran in it.** Output stays readable after the
+ program exits, with its exit status, so a build you started five minutes ago is
+ still there to read.
+- **Panes and tabs carry a `purpose`** — a stable label you choose. It is how you
+ find things again. Titles change under you; purposes do not.
+
+## Is there a session, and which one?
+
+Every pane gets these:
+
+| variable | means |
+|---|---|
+| `SL0PPTY=1` | this process is running inside a sl0ppty pane |
+| `SL0PPTY_SESSION` | the name of the session it is in |
+| `SL0PPTY_BIN` | the binary that started it |
+
+Use `$SL0PPTY_BIN`, not `sl0ppty`: a session may have been started from a build
+tree, and `sl0ppty` is then not on your `PATH`. `SL0PPTY_SESSION` is unset under
+`--script`, which has no socket.
+
+From *outside* a pane, list sessions:
+
+```bash
+sl0ppty ls
+# main running
+# work stale
+```
+
+`stale` is a socket whose server is gone. Addressing a session that does not
+exist prints `sl0ppty: no session named X` and exits 1 — so a failed call is
+distinguishable from a call that answered `{"ok":false}`.
+
+## The one interface
+
+```bash
+SL=${SL0PPTY_BIN:-sl0ppty}
+S="$SL -s ${SL0PPTY_SESSION:-main} cmd"
+
+$S '{"cmd":"panes"}'
+$S '{"cmd":"new-tab","name":"build"}'
+```
+
+Every verb has a bare-verb alias for the same code — `$S panes`, `$S tabs`,
+`$S alive` — which is convenient at a shell and gives you no arguments. Use JSON
+when you need to pass anything.
+
+**Panes and tabs are addressed by `id`, never by index.** A tab whose last pane
+closes is removed and every index after it shifts. `id` survives that. Where a
+verb takes an `id`, `0` means "the focused pane, and the tab you are looking at".
+
+## Running work so you can read the result
+
+This is the pattern to reach for. Do **not** type a command into somebody's shell
+and then screen-scrape for it.
+
+Make a pane that *was given a command*, and tag it:
+
+```bash
+$S '{"cmd":"apply-layout","kdl":"layout { tab name=\"build\" { pane purpose=\"task:build\" command=\"make -j8\" } }"}'
+```
+
+Then poll `panes`, matching on your purpose, until it is no longer alive:
+
+```bash
+while :; do
+ read -r alive code <<<"$($S '{"cmd":"panes"}' \
+ | jq -r '.panes[] | select(.purpose=="task:build") | "\(.alive) \(.exit_code)"')"
+ [ "$alive" = "false" ] && break
+ sleep 1
+done
+echo "exit status: $code"
+```
+
+`exit_code` is `-1` while it runs, and the real status once it stops
+(`exit_signal` is set instead when it was killed). The pane keeps everything it
+printed, so read the output whenever you like — see below. A command pane also
+offers `{"cmd":"rerun","id":N}`, which runs the same command again in the same
+pane, keeping the previous run above it.
+
+**There is no wait primitive over the socket.** `settle` exists only in the
+headless driver. `deadline` reports when the *display* wants its next frame and
+says nothing about program output — do not use it to wait for work. Poll, with a
+sleep you would be happy to explain.
+
+## Reading a pane
+
+```bash
+$S '{"cmd":"snapshot","format":"text"}' # the composited screen as text
+$S '{"cmd":"snapshot"}' # ...or JSON: rows, styles, cursor
+```
+
+`snapshot` is the **whole session's** composited screen — every visible pane, as
+laid out, borders and all. To read one pane, take its rect from `panes`
+(`content_x`, `content_y`, `content_w`, `content_h`) and cut that window out of
+the text.
+
+Two traps:
+
+- **Only what is on screen is in a snapshot.** Scrollback is not. If you need a
+ program's whole output, redirect it to a file and read the file; a snapshot is
+ for seeing what a human would see.
+- **The echoed command line matches your own marker.** Typing `echo DONE` into a
+ shell puts the string `DONE` on screen twice: once as the command, once as its
+ output. Count occurrences, or use a marker that cannot appear in what you sent.
+
+## Typing into a pane
+
+```bash
+$S '{"cmd":"send","data":"ls -la\r"}' # as if typed: decoded, then re-encoded
+$S '{"cmd":"raw","data":"ls -la\r"}' # straight into the focused pane's pty
+```
+
+`send` goes through the input decoder, so it can carry key chords: `\x01` is the
+leader (`C-a` by default), so `{"cmd":"send","data":"\\x01\\\\"}` splits the pane.
+`raw` bypasses the decoder, which is what you want for plain text.
+
+The unescaper understands `\e \n \r \t \\ \0 \xHH`. **Write `\e`, never `\033`** —
+`\0` is consumed first, so `\033` arrives as a NUL followed by `33`. That is a
+silent failure: the bytes go somewhere, nothing happens, and nothing complains.
+
+## Finding things
+
+`purpose` is the handle. Set one when you create a pane, in a layout or over the
+socket:
+
+```bash
+$S '{"cmd":"set-purpose","id":0,"purpose":"agent:main"}' # 0 = focused pane
+$S '{"cmd":"set-purpose","target":"tab","id":0,"purpose":"notes"}'
+```
+
+`panes` and `tabs` report purposes, so finding your own work is a filter and never
+a guess:
+
+```bash
+$S '{"cmd":"panes"}' | jq '.panes[] | select(.purpose|startswith("task:"))'
+```
+
+A purpose set over the socket or by a layout is **declared**, which locks it: a
+program running in that pane cannot relabel it. That protects your handle from
+whatever a program decides to print — and it means an attempt to overwrite
+somebody else's declared purpose is refused rather than silently winning. Do not
+take a purpose that is already there; add your own namespace (`task:`, `agent:`,
+`svc:`).
+
+Setting a purpose to `""` clears it *and* unlocks it, handing the label back.
+
+## Projects and workspaces
+
+If the user has `project_roots` configured, whole projects are addressable by
+name. This is the shortest path from "work on X" to "the panes for X exist":
+
+```bash
+$S '{"cmd":"workspaces"}' # what exists, and what is open
+$S '{"cmd":"open-workspace","name":"api"}'
+# {"ok":true,"tab":3,"purpose":"project:api.a1b2c3d4","created":true,...}
+```
+
+Opening is **idempotent**: ask twice and the second answers `created:false` and
+focuses the tab that is already there. So you can call it without checking first,
+which is the call you would otherwise get wrong after a reconnect.
+
+The project's own layout file decided what its panes are and how they are tagged,
+so the useful next step is to read them:
+
+```bash
+$S '{"cmd":"panes"}' | jq --argjson t 3 '.panes[] | select(.tab_id==$t) | {id,purpose,suspended}'
+# {"id":7,"purpose":"agent:main","suspended":false}
+# {"id":8,"purpose":"service:web","suspended":true}
+$S '{"cmd":"rerun","id":8}' # start the dev server the project declared
+```
+
+A `suspended` pane is laid out and has run nothing — that is how a project keeps
+twelve checkouts from being twelve running dev servers. `rerun` starts it.
+
+`{"cmd":"open-workspace","name":"api","suspended":true}` opens everything asleep.
+`{"cmd":"save-workspace"}` writes the current tab back out as that project's
+layout, recording each pane's directory, command and purpose.
+
+## Reporting from inside a pane
+
+If you are the program *in* a pane, you can draw in your own frame with an escape
+sequence. No socket, no config, nothing to set up:
+
+```bash
+printf '\e]5577;1;status;building 3/7\e\\'
+printf '\e]5577;1;buttons;approve:Approve;cancel:Cancel\e\\'
+printf '\e]5577;1;purpose;task:build\e\\'
+printf '\e]5577;1;clear\e\\'
+```
+
+The status shows in the pane's frame. The buttons are real click targets, and a
+click arrives **on your stdin** as:
+
+```
+\e]5577;1;click;approve\e\\
+```
+
+which is how you ask a question in place instead of printing a prompt and hoping
+somebody is looking. Button ids are `[A-Za-z0-9_-]`, 1 to 32 characters.
+
+Two rules:
+
+- **A purpose you set this way is in-band, and loses to a declared one.** If the
+ pane was tagged by a layout or an operator, your `purpose` is refused. Read
+ `panes` if you need to know what you are called.
+- **Never treat a reply as a request.** Everything the session sends back ends in
+ `-reply` (`hello-reply`, `shader-reply`). If you echo what you are sent — a
+ REPL, `cat`, a shell with echo on — do not answer it.
+
+## Leave the session as you found it
+
+- Close what you made: `{"cmd":"close","id":N}` for a pane,
+ `{"cmd":"close-tab","id":N}` for a tab, and
+ `{"cmd":"close-workspace","name":"api"}` for a workspace. (`close-pane` is the
+ *keybinding* action name, not a socket verb.)
+- Do not `{"cmd":"quit"}` a session you did not start. It ends every pane in it,
+ including the user's.
+- A session you started for your own work is yours to quit: `sl0ppty -s mine cmd quit`.
+
+## Verbs
+
+| verb | takes |
+|---|---|
+| `panes` `tabs` | —. ids, rects, titles, purposes, `alive`, `exit_code`, `tab_id` |
+| `snapshot` | `format:"text"` for text, omitted for JSON |
+| `send` `raw` | `data` |
+| `split` | `dir:"cols"\|"rows"`, `id` |
+| `focus` `close` `rerun` `clear-shaders` | `id`, or `0` for the focused pane |
+| `new-tab` `select-tab` `close-tab` `move-tab` `set-name` | `id` or `index` |
+| `move-pane` | `id`, `tab` (`0` for a tab of its own), `dir` |
+| `set-purpose` | `target:"pane"\|"tab"`, `id`, `purpose` |
+| `apply-layout` | `path` or `kdl`, `replace` |
+| `dump-layout` | `tab`, `relative_to`, `suspend` |
+| `workspaces` `open-workspace` `close-workspace` `save-workspace` | see above |
+| `resize` | `cols` `rows` |
+| `notify` | `text` — a line in the session's status area |
+| `reload` `edit-config` | — |
+| `alive` `deadline` `clipboard` `graphics` | — |
+| `quit` | — |
+
+## Testing a script without a session
+
+```bash
+printf '%s\n' '{"cmd":"split","dir":"cols"}' '{"cmd":"snapshot","format":"text"}' \
+ | sl0ppty --script --cols 80 --rows 24 -- /bin/sh
+```
+
+`--script` is the whole program without a terminal: verbs on stdin, answers on
+stdout, one line per answering command. `settle <ms>` works here and pumps every
+pane until none has produced output for that long, which is how the test suite
+avoids sleeping. A multi-line answer (`snapshot text`, `dump-layout`,
+`workspaces`) is followed by a blank line; a one-line answer is not.
diff --git a/contrib/README.md b/contrib/README.md
index 69e5c3a..f6c45c3 100644
--- a/contrib/README.md
+++ b/contrib/README.md
@@ -154,3 +154,15 @@ The C unit tests link the same instrumented objects, so `input.c`, `kdl.c`,
`shader.c` and `expr.c` get credit for the tests that actually exercise them —
without that they read as half-tested, which is a lie about where the tests
are rather than about the code.
+
+## the agent skill
+
+`.agents/skills/driving-sl0ppty/SKILL.md` is the control socket written as
+instructions rather than as a reference: which environment variables tell a
+program in a pane which session it is in, why work belongs in a pane that was
+*given* a command instead of typed into a shell, and that `purpose` is the handle
+to find things by. It follows the `.agents/skills/<name>/SKILL.md` convention, so
+an agent working in a checkout of this repo picks it up on its own; to use it
+anywhere else, copy or symlink that directory into wherever your agent keeps
+skills. It carries no paths from the machine it was written on, and
+`tests/test_skill.py` keeps every verb it names honest.
diff --git a/docs/scripting.md b/docs/scripting.md
index 3dddc9b..89dd835 100644
--- a/docs/scripting.md
+++ b/docs/scripting.md
@@ -119,6 +119,24 @@ it is sent (`cat`, a shell with echo on, a REPL waiting for a line) would
otherwise be answered into a loop, which is exactly what `hello` used to do:
4 MB of hellos in a second and a half.
+## Driving it from an agent
+
+Everything above is what an agent needs, and none of it says which parts matter.
+`.agents/skills/driving-sl0ppty/SKILL.md` is the same socket written as
+instructions: how a program in a pane finds out which session it is in
+(`SL0PPTY_SESSION`, `SL0PPTY_BIN`), why work belongs in a pane that *was given a
+command* rather than typed into somebody's shell, that `alive` and `exit_code` are
+how you wait rather than reading the screen for a marker your own echo matches, and
+that `purpose` is the handle to find things by because titles change underneath
+you.
+
+It follows the `.agents/skills/<name>/SKILL.md` convention, so an agent working in
+a checkout picks it up without being told. To use it elsewhere, copy or symlink the
+directory into wherever your agent looks for skills. `tests/test_skill.py` checks
+every verb, variable and `panes` field it names against the program, because a
+stale skill is worse than a missing one: an agent acts on it without a human
+reading it first.
+
## Headless
`sl0ppty --script` is the whole program without a terminal: commands on stdin,
diff --git a/src/server.c b/src/server.c
index 59b3c9c..f552f30 100644
--- a/src/server.c
+++ b/src/server.c
@@ -247,6 +247,25 @@ int server_run(const char *name, const char *const argv[], uint16_t cols,
return 1;
}
+ /* Every pane inherits this process's environment, so setting it here is how a
+ * program *inside* a pane learns which session it is in -- and therefore which
+ * socket to talk to. `SL0PPTY=1` (pty.c) says "you are in a pane"; this says
+ * which one of possibly several sessions, which is the part a program cannot
+ * work out for itself: `ls` lists them all and none of them is labelled "the
+ * one you are in". Deliberately unset under `--script`, which has no socket. */
+ setenv("SL0PPTY_SESSION", name, 1);
+ /* ...and which binary to talk to it with. A program in a pane that finds
+ * `sl0ppty` missing from its PATH -- a session started from a build tree, an
+ * agent with a trimmed environment -- can otherwise see the session it is in
+ * and have no way to reach it. Read from /proc rather than argv[0], which is
+ * whatever the caller felt like passing. */
+ char self[512];
+ ssize_t sn = readlink("/proc/self/exe", self, sizeof self - 1);
+ if (sn > 0) {
+ self[sn] = 0;
+ setenv("SL0PPTY_BIN", self, 1);
+ }
+
struct sigaction sa = {.sa_handler = on_sig};
sigaction(SIGTERM, &sa, NULL);
sigaction(SIGINT, &sa, NULL);
diff --git a/tests/test_skill.py b/tests/test_skill.py
new file mode 100755
index 0000000..5bf348b
--- /dev/null
+++ b/tests/test_skill.py
@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""`.agents/skills/driving-sl0ppty/SKILL.md`: the agent-facing interface, checked.
+
+A skill is documentation an agent acts on without a human reading it first, which
+makes a stale one worse than a missing one: a wrong verb becomes a failed tool call
+somebody has to debug, and a verb we removed becomes an agent that cannot do the
+thing it was told it could. So every verb, every environment variable and every
+`panes` field the skill names is checked against the program here.
+
+It is deliberately not checked for prose. It is checked for claims that can rot.
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from harness import BIN, Session, check, report
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+SKILL = os.path.join(ROOT, ".agents", "skills", "driving-sl0ppty", "SKILL.md")
+SH = ["/bin/sh", "-c", "read x"]
+
+
+def text():
+ with open(SKILL) as f:
+ return f.read()
+
+
+def test_the_skill_is_where_agents_look_for_it():
+ check("it exists", os.path.exists(SKILL), SKILL)
+ body = text()
+ check("it opens with YAML frontmatter", body.startswith("---\n"), body[:40])
+ fm = body.split("---")[1]
+ check("naming itself for its directory", "name: driving-sl0ppty" in fm, fm)
+ check("and saying when it applies", "description:" in fm, fm)
+ # The description is what a harness matches on, so it has to mention the
+ # things a user would say.
+ for word in ("sl0ppty", "pane", "workspace", "SL0PPTY"):
+ check("the description mentions " + word, word in fm, fm)
+
+
+def test_every_verb_it_names_is_a_verb_the_program_has():
+ """The check that matters: a skill naming a verb we do not have is a tool call
+ that fails in front of somebody."""
+ body = text()
+ named = set(re.findall(r'\{"cmd":"([a-z-]+)"', body))
+ named |= set(re.findall(r'^\| `([a-z-]+)`(?: `([a-z-]+)`)*', body, re.M))
+ # the verb table lists several per row, backticked
+ for row in re.findall(r"^\| ((?:`[a-z-]+` ?)+)\|", body, re.M):
+ named |= set(re.findall(r"`([a-z-]+)`", row))
+ named = {v for v in named if isinstance(v, str) and v}
+ check("the skill names a useful number of verbs", len(named) > 20, str(named))
+
+ with Session(SH, cols=80, rows=12) as s:
+ unknown = []
+ for verb in sorted(named):
+ if verb == "quit": # would end the session under test
+ continue
+ r = s.api(verb)
+ if r.get("ok") is False and "unknown cmd" in r.get("error", ""):
+ unknown.append(verb)
+ check("every verb it names exists", not unknown,
+ "unknown: " + str(unknown))
+
+
+def test_the_environment_it_promises_is_the_environment_panes_get():
+ body = text()
+ for var in ("SL0PPTY", "SL0PPTY_SESSION", "SL0PPTY_BIN"):
+ check("the skill documents " + var, var in body, "missing " + var)
+
+ # SL0PPTY is set by pty.c for every pane, in every mode.
+ with Session(["/bin/sh", "-c", 'echo "V=[$SL0PPTY]"; read x']) as s:
+ s.settle(120)
+ check("a pane really is told it is in one",
+ "V=[1]" in s.snapshot().screen(), s.snapshot().screen())
+
+ # The other two are set by the server, which --script is not. The skill says
+ # so; this is that sentence being true.
+ with Session(["/bin/sh", "-c", 'echo "S=[$SL0PPTY_SESSION]"; read x']) as s:
+ s.settle(120)
+ check("and that --script has no session to name",
+ "S=[]" in s.snapshot().screen(), s.snapshot().screen())
+ flat = " ".join(body.split()) # the file is wrapped; the claim is not
+ check("which the skill says out loud",
+ "unset under `--script`" in flat, "not documented")
+
+
+def test_the_panes_fields_it_tells_agents_to_poll_are_real():
+ """The skill's central recipe polls `alive` and `exit_code` off `panes` and
+ filters on `purpose`. If any of those three moved, the recipe is a hang."""
+ body = text()
+ with Session(SH, cols=80, rows=12) as s:
+ pane = s.panes()[0]
+ for field in ("id", "purpose", "alive", "exit_code", "tab_id",
+ "content_x", "content_y", "content_w", "content_h"):
+ check("panes reports " + field, field in pane, str(pane))
+ check("and the skill names it", field in body, "missing " + field)
+
+
+def test_the_recipe_in_the_skill_actually_works():
+ """Run the skill's own worked example: a tagged command pane, polled to
+ completion, exit status read off `panes`. Copied from the file rather than
+ paraphrased, so a change to the file is a change to what is tested."""
+ with Session(SH, cols=90, rows=14) as s:
+ s.api("apply-layout", kdl='layout { tab name="build" '
+ '{ pane purpose="task:build" command="sh -c \'echo built; exit 3\'" } }')
+ target = None
+ for _ in range(200):
+ s.settle(30)
+ got = [p for p in s.panes() if p["purpose"] == "task:build"]
+ if got and not got[0]["alive"]:
+ target = got[0]
+ break
+ check("the tagged pane is findable by purpose", target is not None,
+ str(s.panes()))
+ check("it reports the real exit status once it stops",
+ target and target["exit_code"] == 3, str(target))
+ check("and its output is still readable afterwards",
+ "built" in s.snapshot().screen(), s.snapshot().screen())
+
+
+def test_it_is_free_of_this_machine():
+ """"Plug and play" is a property somebody has to keep. A path out of the
+ author's home directory in a skill is a path an end user cannot use."""
+ body = text()
+ bad = []
+ for pat in (r"/home/[a-z]", r"/Users/[a-z]", r"/tmp/[a-z0-9]",
+ r"\bclank\b", re.escape(os.path.expanduser("~"))):
+ bad += [m.group(0) for m in re.finditer(pat, body)]
+ check("no path from the machine it was written on", not bad, str(set(bad)))
+ check("it reaches the binary through the environment",
+ "SL0PPTY_BIN" in body and "not on your `PATH`" in body, "no PATH note")
+
+
+def test_settle_is_not_promised_over_the_socket():
+ """The skill tells agents to poll, because the thing that would save them from
+ polling is headless-only. If that ever changes, the skill is understating what
+ the program can do -- which is the good direction, but it should not be
+ accidental."""
+ with Session(SH, cols=80, rows=10) as s:
+ r = s.api("settle", ms=10)
+ check("settle is not a socket verb", r.get("ok") is False, str(r))
+ check("and the skill says there is no wait primitive",
+ "no wait primitive" in text(), "not documented")
+
+
+def test_the_skill_is_reachable_from_the_docs_people_read():
+ """An agent finds it by convention. A human has to be told it is there."""
+ for path, what in ((os.path.join(ROOT, "contrib", "README.md"), "contrib"),
+ (os.path.join(ROOT, "docs", "scripting.md"), "scripting")):
+ with open(path) as f:
+ body = f.read()
+ check("%s points at the skill" % what, "driving-sl0ppty" in body, path)
+
+
+if __name__ == "__main__":
+ for name, fn in sorted(list(globals().items())):
+ if name.startswith("test_"):
+ fn()
+ sys.exit(report())