Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
## Checklist

- [ ] `cargo build --release --workspace` has no warnings and `cargo test --release --workspace` passes
- [ ] No new external crates (the shipped path builds offline)
- [ ] No new external crates (the default build has one, `libm`; the `nostd` build adds `hashbrown` and `portable-atomic`)
- [ ] Any number that moved is updated in the table it lives in (`BENCHMARKS.md`, `USE-CASES.md`, `docs/probbit-ir-json.md`), with machine, load and `N`
- [ ] Fixed-work output (`--sweeps`, `--polish-sweeps`) is still bit-identical across thread counts, or the RNG/move-order change is called out below and in `CHANGELOG.md`
- [ ] A new behaviour or control has a test, and the JSON contract / exit codes are unchanged or documented
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ curl -fsSL https://raw.githubusercontent.com/BitmapAsset/probbit/main/install.sh
export PATH="$HOME/.local/bin:$PATH" # no output
probbit --version # probbit 0.13.0 (or later); exit 0
curl -fsSLO https://raw.githubusercontent.com/BitmapAsset/probbit/main/examples/persona/tutor.yaml # no output; tutor.yaml
probbit persona init tutor.yaml --seed 2 --out tutor.state # wrote tutor.state (Pip 1.1.0, seed 2); exit 0
probbit persona init tutor.yaml --seed 2 --out tutor.state # wrote tutor.state (Pip 1.1.0, seed 2) on stderr; exit 0
echo '{"sentiment":"negative"}' | probbit live tutor.yaml --state tutor.state --strand tutor.strand --clock fixed 2>/dev/null | grep -o '"line":"[^"]*"'
# "line":"Stance: go easy on the jokes; no jokes; gentle; ..."; exit 0
probbit live verify tutor.strand | grep -o '"ok":[a-z]*' # "ok":true; exit 0
Expand Down
17 changes: 17 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,8 @@ All notable changes to this project are documented here. The format follows
Boolean flags; keyword mode remains local. The classifier timeout defaults to 300 ms in both modes.
- The README distinguishes enforced stance habits from model obedience, limits replay claims to measured checks,
and links to the changelog for release notes. Install and quickstart paths stay in place.
- `probbit monitor --help`, the man page and the docs call what the monitor draws "internal state" (was "inner state");
no behaviour or output format changes.

### Fixed

Expand Down Expand Up @@ -64,6 +66,21 @@ All notable changes to this project are documented here. The format follows
- `probbit explain` (new in this release) listed a Boolean sense reading under `flags` only when it was bare
(`"tool_fail": true`); a wrapped reading (`{"v": true, "src": ...}`, docs/persona.md section 2.11) was left out. Both
forms are listed now.
- `install.sh`: with `SHELL` empty, or unset under a shell that leaves it unset (dash; bash and macOS `/bin/sh` set it to
the login shell, so the hint follows that), the PATH hint named only `~/.profile`, which an interactive bash does not
read. It now names `~/.zshrc` on macOS and `~/.bashrc (bash) or ~/.profile` elsewhere; a set `SHELL` is unchanged.
- The last "no external crates" statements are corrected. SECURITY.md, the CLI's crate documentation and the pull
request checklist say that the default build has one third-party crate, `libm` (the checklist adds that `nostd` brings
`hashbrown` and `portable-atomic`); SECURITY.md also says that `probbit monitor` listens on 127.0.0.1 and that
probbit opens no outbound connection. probbit-ir's crate documentation says that its own default build has no
third-party crate.
- README and npm README: the binary is 3 to 6 MB (it said 3 to 4 MB; the 0.14.0 release binaries are 3.7 to 5.0 MB,
the Linux x86_64 ones the largest; an outside from-source build on Linux x86_64 measured 5.2 MB).
- README "60-second tour": the sixty seconds are the demo with a built binary; the first build takes a few minutes and
`cargo test --release --workspace`, the whole test suite, several more. The three `--hard` runs keep their Apple M4
results; on a slower machine raise `--budget-ms` until `partial` and then `diagnostics_passed` appear.
- README, AGENTS.md and npm README: `probbit persona init` prints its "wrote ..." line on stderr; the quick starts say so.
- probbit-persona: a test closure no longer carries an unneeded `mut` (an `unused_mut` warning).

## 0.14.1 - Unreleased

Expand Down
15 changes: 9 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@
curl -fsSL https://raw.githubusercontent.com/BitmapAsset/probbit/main/install.sh | sh
```
Linux and macOS, no sudo, the archive's SHA-256 checked first. Windows, npm and the from-source build: [Install](#install).
One binary of 3 to 4 MB; one third-party crate in the default build (`libm`, for amplitude-register math).
One binary of 3 to 6 MB; one third-party crate in the default build (`libm`, for amplitude-register math).
The `nostd` build adds `hashbrown` and `portable-atomic`. Nothing phones home. Agents: start at
[For AI agents reading this](#for-ai-agents-reading-this), [AGENTS.md](AGENTS.md) and [llms.txt](llms.txt).

Expand Down Expand Up @@ -73,7 +73,7 @@ probbit --version
# 4. Fetch an example persona (a tutor called Pip). No output; tutor.yaml appears.
curl -fsSLO https://raw.githubusercontent.com/BitmapAsset/probbit/main/examples/persona/tutor.yaml

# 5. Make an individual: persona + seed 2. Expect "wrote tutor.state (Pip 1.1.0, seed 2)". Exit 0.
# 5. Make an individual: persona + seed 2. Expect "wrote tutor.state (Pip 1.1.0, seed 2)" on stderr. Exit 0.
probbit persona init tutor.yaml --seed 2 --out tutor.state

# 6. One live event (an upset user), logged to a strand. Expect one line starting
Expand Down Expand Up @@ -224,7 +224,7 @@ One line, no sudo, the archive's SHA-256 checked before anything is installed. T
| npm (Node 18+) | `npm i -g probbit` |
| by hand | archives for Linux x86_64 (glibc or static musl), Linux arm64 (static), macOS (Apple silicon and Intel) and Windows x86_64 on the [Releases page](https://github.com/BitmapAsset/probbit/releases), each with a `.sha256` beside it |

npm may print an `allow-scripts` warning: the package's only install script downloads the prebuilt binary for your platform
npm may print a warning about install scripts: the package's only install script downloads the prebuilt binary for your platform
and checks its SHA-256. If npm blocks the script, the binary is fetched the first time you run `probbit` instead.

The shell installer defaults to `~/.local/bin`, without replacing a system-wide installation. Set
Expand Down Expand Up @@ -254,9 +254,11 @@ gives a command's flags with their defaults, its exit codes and examples. A mist

## 60-second tour

The sixty seconds are the demo with a built binary; the first build takes a few minutes.

```
git clone https://github.com/BitmapAsset/probbit && cd probbit
cargo test --release --workspace # unit, integration, regression and exact-oracle tests
cargo test --release --workspace # the whole test suite (unit, integration, regression and exact-oracle tests): several more minutes
cargo run --release -p probbit-cli -- demo --tasks 12 | cargo run --release -p probbit-cli -- decide --pretty
cargo run --release --example agent_router # the full narrated demo, ~3 s
```
Expand All @@ -275,7 +277,8 @@ $ probbit demo --tasks 300 --hard | probbit decide --budget-ms 200 # "partial
$ probbit demo --tasks 300 --hard | probbit decide --budget-ms 1000 # "diagnostics_passed": 300 released, 0 violations
```
(5 runs each on an Apple M4.) Every escalated task's odds are in the output; the decision is left to you. The budget is
wall-clock, so a slower machine needs a longer one; `--sweeps N --polish-sweeps M` is checked for byte-for-byte replay across the CI matrix, excluding timings
wall-clock: on a slower machine the same commands refuse or escalate more, so raise `--budget-ms` until `partial` and then
`diagnostics_passed` appear; `--sweeps N --polish-sweeps M` is checked for byte-for-byte replay across the CI matrix, excluding timings
and echoed runtime controls ([CONTRIBUTING.md](CONTRIBUTING.md)).

Everything runs with stock stable Rust. The default build uses `libm` for amplitude-register math; `nostd` adds
Expand Down Expand Up @@ -766,7 +769,7 @@ rail, and the header above the face says which agent, on which host, in which la
labels in a sidecar next to each strand (`nova.labels.json`), outside the strand and its digests: `probbit live ... --strand
nova.strand --label agent=Nova --label lane=support` writes them, the OpenClaw plugin writes them per lane, and `probbit monitor
old.strand --label agent=Nova --open` labels a strand recorded before them without rewriting it.
See [the monitor guide](docs/persona.md#58-monitor-watch-an-individuals-inner-state) for the data and replay boundaries.
See [the monitor guide](docs/persona.md#58-monitor-watch-an-individuals-internal-state) for the data and replay boundaries.

**The monitor as a Mac app.** On a Mac the same page opens in its own window: download `probbit-Monitor-<version>-macos.zip`
from the [release page](https://github.com/BitmapAsset/probbit/releases), unzip it, move **probbit Monitor** to Applications,
Expand Down
5 changes: 3 additions & 2 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,9 @@ notes unless you prefer otherwise.
## What counts

probbit is a local command-line processor that reads JSON from standard input and
writes JSON to standard output. It opens no network connections and has no
external crates. Reports in these areas are especially welcome:
writes JSON to standard output. It opens no outbound network connections (only
`probbit monitor` listens, on 127.0.0.1), and its default build has one
third-party crate, `libm`. Reports in these areas are especially welcome:

- **Input handling.** A malformed or hostile problem document must exit 2 with a
message on stderr. A crash (`abort`, stack overflow, panic), a hang, unbounded
Expand Down
2 changes: 1 addition & 1 deletion docs/adapters.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ the receipt per decision and the bounded state the same mechanism drives.
| LangChain / LangGraph | [examples/hosts/langchain/stance_callbacks.py](../examples/hosts/langchain/stance_callbacks.py) | `BaseCallbackHandler.on_tool_end` collects; a Runnable in front of the model prepends the stance `SystemMessage` (`stance_messages` for a LangGraph node) | `--offline` smoke; the LangChain path not run here |
| any Node loop | [examples/node/stance-host.mjs](../examples/node/stance-host.mjs) | `await host.turn(toolTexts)`; `verify()` | `node --test examples/node/stance-host.test.mjs` against the release binary |
| Vercel AI SDK | [examples/hosts/vercel-ai/stance.mjs](../examples/hosts/vercel-ai/stance.mjs) | `prepareStep` rebuilds the step's system message from `host.turn`; `onToolExecutionEnd` collects results | not run here (needs the `ai` package, a provider and a key) |
| MCP hosts (Claude Code, Codex CLI, Cursor, mcporter) | `probbit mcp` | tools `probbit_live_event`, `probbit_live_verify`, `probbit_persona_turn`, ... ([agents.md](agents.md)) | real calls from Claude Code and Codex CLI (agents.md) |
| MCP hosts (Claude Code, Codex CLI, Cursor, mcporter) | `probbit mcp` | tools `probbit_live_event`, `probbit_live_verify`, `probbit_persona_turn`, ... ([agents.md](agents.md)) | real calls from Claude Code; for Codex CLI the entry it writes, no model call (agents.md) |
| OpenClaw | [plugins/openclaw](../plugins/openclaw/README.md) (`probbit-stance`, `openclaw plugins install npm:probbit-stance --accept-capabilities`) | `before_prompt_build`: one event per user message in the listed sessions, the block injected into the turn, the footer line in the chat; `before_tool_call`: shadow gate; `after_tool_call` (with `sensesMode` shadow or feed, since plugin 0.2.0): counts failed tool calls for the `tool_fail` reading | 165 tests against a mocked host built from the 2026.9.7 SDK types and the real binary; a build of this plugin runs live on the author's own agent since 2026-10-06 |

"Not run here" means exactly that: the file is written to the framework's documented contract and compiles, but this
Expand Down
4 changes: 2 additions & 2 deletions docs/monitor-app.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

`probbit monitor STRAND --open` serves the monitor page on 127.0.0.1 and opens it in the browser. **probbit Monitor** is the
same page in its own Mac window: an app you open from Finder, the Dock or Launchpad, with the probbit binary inside it. The
page itself is the one described in [persona.md §5.8](persona.md#58-monitor-watch-an-individuals-inner-state); what it looks
page itself is the one described in [persona.md §5.8](persona.md#58-monitor-watch-an-individuals-internal-state); what it looks
like: [probbit-monitor.png](probbit-monitor.png).

## Get it
Expand Down Expand Up @@ -42,7 +42,7 @@ either kind opens like any app. A copy you build yourself (below) has no quarant
(`probbit monitor --demo week`), no strand needed.
- **Several strands, a folder**: the app passes every file you open, and a folder as `--dir FOLDER`, to its probbit. The
bundled probbit (0.13.0) serves them all on one page, with a rail on the left to switch between strands and each strand's
labels ([persona.md §5.8](persona.md#58-monitor-watch-an-individuals-inner-state)). A probbit that watches one strand at a
labels ([persona.md §5.8](persona.md#58-monitor-watch-an-individuals-internal-state)). A probbit that watches one strand at a
time (0.12.1 and earlier, if you build the app around one) refuses that; the app then shows the first strand you chose
(for a folder, its most recently changed `*.strand` file) and says so under the window title.
- **Integrity** (engine 0.14.0+, a persona with the identity self keys, [persona.md §5.9](persona.md#59-integrity-the-drift-from-the-declared-self-rfc-0014)):
Expand Down
8 changes: 5 additions & 3 deletions docs/persona.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ This document is normative for the file format, the compilation, the stance docu
CLI, `probbit mcp` (tools `probbit_persona_init`, `probbit_persona_turn`), the Python wrapper (`probbit.persona_init`,
`persona_turn`, `persona_replay`) and the browser module (probbit-wasm ops 4 and 5). `probbit live` (section 5.7, live.rs) keeps an
individual running on a clock, with learning (section 2.8) and a replayable log; `probbit monitor` (section 5.8, monitor.rs)
draws its inner state live from that log. The example personas and their goldens are in
draws its internal state live from that log. The example personas and their goldens are in
[examples/persona/](../examples/persona/). An independent reference implementation of this format (Python) gives the same
documents byte for byte on every example turn (section 5.3).

Expand Down Expand Up @@ -1792,7 +1792,9 @@ a line that differs, 5 at a line with a field or line kind this engine does not
a divergence), 2 for a bad flag or an unreadable file. `control` 0 when the line is appended, 2 for a bad field or an invalid
move, 4 when the lock is held or the individual is retired.

### 5.8 Monitor: watch an individual's inner state
<a id="58-monitor-watch-an-individuals-inner-state"></a>

### 5.8 Monitor: watch an individual's internal state

`probbit monitor STRAND` draws an individual's declared state as live terminal bars, or as a compact browser Activity Monitor.
It replays the strand with the rules of `live verify` (the two share one replay), recomputing every stance document from the
Expand Down Expand Up @@ -2074,7 +2076,7 @@ previous event, the restart included). `probbit_live_event` (MCP) and Python's `
| `probbit live PERSONA [--seed N \| --state FILE] [--strand FILE] [--events FILE [--watch]] [--clock real\|fixed]` | a resident individual: JSONL events in, one stance per event out, `elapsed_hours` stamped by the clock, the life logged to a strand (section 5.7); `--state` is rewritten after every event |
| `probbit live PERSONA --demo week [--seed N] [--strand FILE] [--plain]` | one individual's scripted week on the fixed clock: learning to its cap, a quiet night, habits that hold (section 5.7) |
| `probbit live verify STRAND [--from-checkpoint] [--chain] [--actions FILE]` | replay a strand from its header alone: ok, the earliest line that differs (exit 1), or the earliest line with a field or line kind this engine does not know (`unsupported`, exit 5: a newer engine's strand, not a divergence); with `--actions`, also the earliest turn whose host action differs from the level its stance released; with `--chain`, a segment and every previous segment file (exit 6: one is missing) (section 5.7) |
| `probbit monitor STRAND [--follow] [--once] [--plain] [--fps N] [--serve] [--open] [--port N]`, `probbit monitor --demo [...]` | watch an individual's inner state: the strand replayed as live bars in the terminal, or as a page on 127.0.0.1 (section 5.8) |
| `probbit monitor STRAND [--follow] [--once] [--plain] [--fps N] [--serve] [--open] [--port N]`, `probbit monitor --demo [...]` | watch an individual's internal state: the strand replayed as live bars in the terminal, or as a page on 127.0.0.1 (section 5.8) |

A script is a JSON list of per-turn input objects (or `{"turns": [...]}`; a turn may be `{"inputs": {...}, ...}`). Exit codes
(`live`'s are in section 5.7, `monitor`'s in section 5.8):
Expand Down
Binary file modified docs/probbit-flow.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/probbit-flow.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions docs/probbit.1
Original file line number Diff line number Diff line change
Expand Up @@ -455,7 +455,7 @@ probbit check agent.yaml \-\-props rules.yaml \-\-strand day1.strand \-\-strand
.fi
.RE
.SS monitor
an individual's inner state, live: terminal bars or a page on 127.0.0.1
an individual's internal state, live: terminal bars or a page on 127.0.0.1
.PP
.nf
\fBprobbit\fR monitor STRAND [\-\-follow] [\-\-once] [\-\-plain] [\-\-fps N] [\-\-serve]
Expand All @@ -467,7 +467,7 @@ an individual's inner state, live: terminal bars or a page on 127.0.0.1
[\-\-open] [\-\-port N]
.fi
.PP
Watch an individual's inner state (docs/persona.md \[u00A7]5.8): replays the strand (`probbit live \-\-strand` writes it) with the rules of `probbit live verify`, recomputing every stance document from the strand alone, and draws the latest event as horizontal bars: the stance (each trait's levels with their reported odds, the level taken highlighted, the phrase it says), the moods with a sparkline of the last 50 events, the senses (the event's inputs, the history features), the habits in force and the ones that bound, the learned deltas, the drives when the documents carry them, and the stance line.
Watch an individual's internal state (docs/persona.md \[u00A7]5.8): replays the strand (`probbit live \-\-strand` writes it) with the rules of `probbit live verify`, recomputing every stance document from the strand alone, and draws the latest event as horizontal bars: the stance (each trait's levels with their reported odds, the level taken highlighted, the phrase it says), the moods with a sparkline of the last 50 events, the senses (the event's inputs, the history features), the habits in force and the ones that bound, the learned deltas, the drives when the documents carry them, and the stance line.
.PP
It changes no file (\-\-demo: its week goes through a temporary one, removed at once) and sends nothing anywhere.
.PP
Expand Down
Loading
Loading