ollie/doc/IDEAS_CONTROLLER.md

# IDEAS: Fit-for-Purpose Session Controller

Ollie's 9P session filesystem exposes enough observable state that an external
controller process can enforce production-grade loop discipline without touching
the agent loop, the model, or any prompt. The controller is a first-class citizen
of the design — it reads structured synthetic files and actuates via `ctl` writes.

## Background

Production agent systems avoid "smart shell script with amnesia" behavior by
applying explicit control policies:

- A **planner/executor split** where one component sets the next bounded action
  and another performs it.
- **Per-step budgets**: max tool calls before replanning, max context tokens
  before compaction, max output bytes admitted back into context, max turns
  without net state change.
- **Structured tool results**: the model sees a normalized observation record
  (status, key findings, changed files, exit condition) instead of raw terminal
  output.

Ollie's system prompt enforces the planner/executor split at the prompt layer
(mandatory `PLAN:` checklist, persisted to `s/$SID/plan`). The per-step budgets
and output normalization are not enforced mechanically — they are the gap that
an external controller closes.

## Observable Surfaces

All paths are relative to `$OLLIE/s/$SID/`.

| Path | Mode | Signal class | Description |
|---|---|---|---|
| `state` | read | state | `idle` / `thinking` / `calling:<tool>` |
| `statewait` | blocking read | state | Blocks until state changes — the event pump |
| `ctxsz` | read | budget | Current tokens / window ceiling as `N/M` |
| `ctxszwait` | blocking read | budget | Blocks until context size changes — fires after every tool call |
| `usage` | read | budget | Token usage counters (input / output / total) |
| `plan` | r/w | stall | Markdown checklist; `[x]` count delta = net progress signal |
| `ctl` | write | actuator | `stop` / `kill` / `compact` / `clear` — controller's actuator |
| `prompt` | write | actuator | Inject a prompt into the session |
| `fifo.in` | write | actuator | Queue a prompt to execute after the current turn |
| `chat` | read | stall | Full chat history — tail from `offset` to measure response size |
| `offset` | read | stall | Byte offset of last user prompt |

**Key principle**: use the `*wait` blocking-read variants, not polling. A
controller that polls `state` every second wastes cycles and can miss fast
transitions. Block on `statewait`; wake only when state actually changes.

## Signal Taxonomy

### State signals
Derived from `statewait`. Fires on every `idle → thinking → calling:tool → idle`
transition. Gives turn boundaries without polling.

### Context budget
Derived from `ctxszwait` and `usage`. Fires after each tool call, not just at
idle. Enforce a ceiling as a fraction of the window before the model starts
silently degrading from context loss.

### Output byte budget
Computed from `offset` + `chat`. After each turn transitions to idle, measure
`wc -c` on the chat file from the saved offset. A large delta with no
corresponding `plan` checkbox change is raw terminal sludge.

### Stall detection
Computed from the `[x]` line count in `plan` across consecutive idle events.
Count idle turns where the completed-task count didn't change. That's the
no-progress counter.

## Controller Types

Each controller is a small independent process. They compose via process
supervision — no shared framework, no IPC, just the filesystem.

### budget-ctl
Watches `ctxszwait`. When context crosses a threshold, writes `compact` to `ctl`.
When a step ceiling is crossed (counted as `calling:*` → `idle` transitions),
writes a queued replan prompt to `fifo.in`.

- **Watches**: `ctxszwait`, `usage`
- **Actuates**: `ctl ← compact`, `fifo.in ← replan prompt`
- **Implementation**: ~30 lines of `sh` + `awk`

### stall-ctl
Blocks on `statewait` to get idle events. Reads the plan file on each idle,
diffs the `[x]` count. After N idle turns with no delta, writes `stop` and logs
the stall.

- **Watches**: `statewait`, `plan`
- **Actuates**: `ctl ← stop`
- **Implementation**: ~40 lines of `sh`

### output-ctl
After each idle, computes the chat delta from `offset`. If the raw response
exceeds `MAX_BYTES`, injects a normalization prompt:

> Compress your last tool output into a structured observation: status, key
> findings, changed files, next action.

- **Watches**: `statewait`, `offset`, `chat`
- **Actuates**: `prompt ← normalize instruction`
- **Implementation**: ~50 lines of `sh`

### turn-auditor
Accumulates tool-call events from state transitions (`calling:<tool>` → `idle`).
Counts parallel vs sequential calls, flags turns where the agent re-read a file
it already read, emits a structured turn trace for post-hoc review. Observes
only — does not actuate.

- **Watches**: `statewait` (all states)
- **Actuates**: write to log file
- **Implementation**: Go or Python; passive observer

## Controller Loop Design

The controller state machine per session:

```
WATCHING  → block on statewait
          → wake on "idle"
IDLE_FIRED → read ctxsz, plan; compute chat delta
EVALUATING → check all policies: budget, stall, output size
ACTING    → write to ctl, prompt, or fifo.in (at most one action per idle)
WATCHING  → block on statewait again
```

For multi-signal controllers, fan out checks in parallel after each idle event,
then apply a priority ordering before actuating (budget > stall > output) to
avoid conflicting writes to `ctl`.

## Reference Sketches

### stall-ctl

```sh
#!/bin/sh
# stall-ctl: kill session after N idle turns with no plan progress
# Usage: stall-ctl --sid SID [--no-progress-turns N]
set -e
SID=""  MAX_STALL=3
while [ $# -gt 0 ]; do
  case $1 in
    --sid)               SID=$2;         shift 2 ;;
    --no-progress-turns) MAX_STALL=$2;   shift 2 ;;
    *) shift ;;
  esac
done
[ -z "$SID" ] && { echo "stall-ctl: --sid required" >&2; exit 1; }

CTL="$OLLIE/s/$SID"
stall_count=0
prev_checked=-1

while true; do
  # Block until state changes
  new_state=$(cat "$CTL/statewait")
  [ "$new_state" != "idle" ] && continue

  # Count completed tasks in the plan checklist
  checked=$(grep -c '^- \[x\]' "$CTL/plan" 2>/dev/null || echo 0)

  if [ "$prev_checked" -ge 0 ] && [ "$checked" -eq "$prev_checked" ]; then
    stall_count=$((stall_count + 1))
    if [ "$stall_count" -ge "$MAX_STALL" ]; then
      echo "stall-ctl: $SID stalled for $stall_count turns, stopping"
      echo "stop" > "$CTL/ctl"
      exit 0
    fi
  else
    stall_count=0
  fi
  prev_checked=$checked
done
```

### budget-ctl

```sh
#!/bin/sh
# budget-ctl: compact when context exceeds pct of window; replan after steps-max
# Usage: budget-ctl --sid SID [--ctx-pct N] [--steps-max N] [--replan-prompt FILE]
set -e
SID=""  CTX_PCT=75  STEPS_MAX=0  REPLAN_PROMPT=""
while [ $# -gt 0 ]; do
  case $1 in
    --sid)            SID=$2;             shift 2 ;;
    --ctx-pct)        CTX_PCT=$2;         shift 2 ;;
    --steps-max)      STEPS_MAX=$2;       shift 2 ;;
    --replan-prompt)  REPLAN_PROMPT=$2;   shift 2 ;;
    *) shift ;;
  esac
done
[ -z "$SID" ] && { echo "budget-ctl: --sid required" >&2; exit 1; }

CTL="$OLLIE/s/$SID"
step=0

while true; do
  # Wake on any ctx change (fires after every tool call, not just idle)
  raw=$(cat "$CTL/ctxszwait")         # e.g. "12847/65536"
  used=$(echo "$raw" | cut -d/ -f1)
  total=$(echo "$raw" | cut -d/ -f2)
  pct=$(awk "BEGIN{print int($used*100/$total)}")

  if [ "$pct" -ge "$CTX_PCT" ]; then
    echo "budget-ctl: ctx $pct% >= threshold, compacting"
    echo "compact" > "$CTL/ctl"
  fi

  # Count steps: calling:* → idle counts as one step
  state=$(cat "$CTL/state")
  case $state in idle) step=$((step+1)) ;; esac
  if [ $STEPS_MAX -gt 0 ] && [ $step -ge $STEPS_MAX ]; then
    echo "budget-ctl: step limit reached, injecting replan"
    cat "$REPLAN_PROMPT" > "$CTL/prompt"
    step=0
  fi
done
```

### output-ctl

```sh
#!/bin/sh
# output-ctl: inject summarize prompt when turn output exceeds MAX_BYTES
# Usage: output-ctl --sid SID [--max-bytes N]
set -e
SID=""  MAX_BYTES=4096
while [ $# -gt 0 ]; do
  case $1 in
    --sid)       SID=$2;        shift 2 ;;
    --max-bytes) MAX_BYTES=$2;  shift 2 ;;
    *) shift ;;
  esac
done
[ -z "$SID" ] && { echo "output-ctl: --sid required" >&2; exit 1; }

CTL="$OLLIE/s/$SID"
prev_offset=0

while true; do
  new_state=$(cat "$CTL/statewait")
  [ "$new_state" != "idle" ] && continue

  cur_offset=$(cat "$CTL/offset")
  chat_size=$(wc -c < "$CTL/chat")
  delta=$((chat_size - prev_offset))

  if [ "$delta" -gt "$MAX_BYTES" ]; then
    echo "output-ctl: response ${delta}B > ${MAX_BYTES}B, injecting normalize"
    printf 'Compress your last tool output into a structured observation: '\
'status, key findings, changed files, next action.' > "$CTL/prompt"
  fi

  prev_offset=$cur_offset
done
```

## Composition

All three controllers watch the same session directory as independent processes.
They share no state. Compose them per task type in a `mkfile` recipe:

```sh
# Start a coding session with full controller suite
SID=$(ollie session new cwd=$PWD agent=coding)
CTL="$OLLIE/s/$SID"

budget-ctl  --sid "$SID" --ctx-pct 75 --steps-max 12 \
            --replan-prompt "$OLLIE/p/replan.md" &
stall-ctl   --sid "$SID" --no-progress-turns 3 &
output-ctl  --sid "$SID" --max-bytes 4096 &

echo "$TASK" > "$CTL/prompt"
wait
```

Each controller process exits when it writes `kill`/`stop` to `ctl` or when the
session dies. No daemon, no framework, no shared memory.

## Gap Closure

| Control gap | Closed by | Signal used |
|---|---|---|
| Max tool calls before replan | `budget-ctl` step counter | `statewait` → count `calling:*` → `idle` |
| Max context before compact | `budget-ctl` ctx ceiling | `ctxszwait` → threshold → `compact` |
| Max output bytes in context | `output-ctl` | `offset` + `chat` delta |
| Stall detection | `stall-ctl` | `plan` checkbox delta across idle events |
| Structured tool results | `output-ctl` normalize prompt | Reactive: normalizes after the fact |
| Hard mid-turn enforcement | Not closeable externally | Controller acts at turn boundaries only |

## Limitations

The controller acts at turn boundaries — it sees output after it is already in
context. If a tool produces 100KB of stdout, `output-ctl` can inject a
normalization prompt on the next turn, but the current context window already
contains the raw output. Fully preventive output filtering would require a proxy
at the tool execution layer, not the session filesystem layer.

The planner/executor discipline (mandatory `PLAN:` before tool calls) remains
prompt-layer only. The controller can stop a session after a bad turn but cannot
prevent a bad action mid-turn.