feat(tess): add configurable Pi interaction service (#728)

2026-07-13 02:59:27 +00:00
parent 24b07d0f83
commit e3b5113be2
20 changed files with 550 additions and 7 deletions
--- a/packages/mosaic/framework/fleet/README.md
+++ b/packages/mosaic/framework/fleet/README.md
@@ -15,6 +15,21 @@ default tmux server.

 - `examples/minimal.yaml` starts one local canary slot.
 - `examples/local-canary.yaml` starts a small generic dogfood fleet.
+- `examples/operator-interaction.yaml` is an example Pi operator-interaction
+  service; replace its example agent name before provisioning.
+
+## Operator interaction service
+
+`services/operator-interaction.yaml` pins the Pi runtime, GPT-5.6 Sol model,
+high reasoning, and the `operator-interaction` tool policy. The agent identity
+is provisioning data: choose a roster name, generate its per-agent environment
+file, then start the matching generic systemd instance. The service fails before
+launch if the configured identity does not match the instance or any pinned
+policy field drifts.
+
+The installed `tools/fleet/print-interaction-effective-policy.sh` prints only
+the resolved name, runtime, model, reasoning, and tool policy. It never reads
+or prints credential variables.

 Initialize a roster:

--- a/packages/mosaic/framework/fleet/examples/operator-interaction.yaml
+++ b/packages/mosaic/framework/fleet/examples/operator-interaction.yaml
@@ -0,0 +1,19 @@
+# Example instance only. Replace `Tess` with the chosen provisioned identity.
+version: 1
+transport: tmux
+tmux:
+  socket_name: mosaic-fleet
+  holder_session: _holder
+defaults:
+  working_directory: ~/src
+runtimes:
+  pi:
+    reset_command: /new
+agents:
+  - name: Tess
+    runtime: pi
+    class: operator-interaction
+    model_hint: openai/gpt-5.6-sol
+    reasoning_level: high
+    tool_policy: operator-interaction
+    persistent_persona: true
--- a/packages/mosaic/framework/fleet/roles/operator-interaction.md
+++ b/packages/mosaic/framework/fleet/roles/operator-interaction.md
@@ -0,0 +1,11 @@
+# Operator Interaction — fleet role definition
+
+The **operator-interaction** role is the authorized human interaction plane for
+Mosaic. It presents runtime and fleet state, mediates approved actions, and
+hands coding or general orchestration work to Mos.
+
+## Boundaries
+
+- It does not claim Mos-owned coding or general orchestration work.
+- It exposes only the configured, observable tool policy.
+- It does not receive or surface credentials in its effective policy.
--- a/packages/mosaic/framework/fleet/roster.schema.json
+++ b/packages/mosaic/framework/fleet/roster.schema.json
@@ -105,6 +105,18 @@
          "modelHint": {
            "type": "string"
          },
+          "reasoning_level": {
+            "type": "string"
+          },
+          "reasoningLevel": {
+            "type": "string"
+          },
+          "tool_policy": {
+            "type": "string"
+          },
+          "toolPolicy": {
+            "type": "string"
+          },
          "persistent_persona": {
            "oneOf": [{ "type": "boolean" }, { "type": "string" }]
          },
--- a/packages/mosaic/framework/fleet/services/operator-interaction.yaml
+++ b/packages/mosaic/framework/fleet/services/operator-interaction.yaml
@@ -0,0 +1,5 @@
+# Generic service policy. Provisioning supplies the agent name as data.
+runtime: pi
+model: openai/gpt-5.6-sol
+reasoning: high
+tool_policy: operator-interaction
--- a/packages/mosaic/framework/systemd/user/README.md
+++ b/packages/mosaic/framework/systemd/user/README.md
@@ -12,6 +12,8 @@ exact-match session.

 - `mosaic-tmux-holder.service` — user-mode holder that owns the named tmux server.
 - `mosaic-agent@.service` — user-mode template for one reusable agent session.
+- `mosaic-interaction-agent@.service` — generic Pi operator-interaction template
+  that fails fast when its pinned runtime policy is incomplete or changed.
 - `test-fleet-units.sh` — validates unit syntax and required relationships.

 The agent template calls:
@@ -45,12 +47,22 @@ MOSAIC_AGENT_WORKDIR=$HOME/src/your-project
 ```bash
 mkdir -p ~/.config/systemd/user ~/.config/mosaic/tools/fleet ~/.config/mosaic/fleet/agents
 cp packages/mosaic/framework/systemd/user/mosaic-*.service ~/.config/systemd/user/
-cp packages/mosaic/framework/tools/fleet/start-agent-session.sh ~/.config/mosaic/tools/fleet/
-chmod +x ~/.config/mosaic/tools/fleet/start-agent-session.sh
+cp packages/mosaic/framework/tools/fleet/*.sh ~/.config/mosaic/tools/fleet/
+chmod +x ~/.config/mosaic/tools/fleet/*.sh
 systemctl --user daemon-reload
 systemctl --user start mosaic-tmux-holder.service
 systemctl --user start mosaic-agent@canary.service
 tmux -L mosaic-fleet ls
+
+# For an operator-interaction service, the roster/env identity selects the
+# generic unit instance; no service source is renamed for an instance.
+systemctl --user start mosaic-interaction-agent@<agent-name>.service
+MOSAIC_AGENT_NAME=<agent-name> \
+MOSAIC_AGENT_RUNTIME=pi \
+MOSAIC_AGENT_MODEL=openai/gpt-5.6-sol \
+MOSAIC_AGENT_REASONING=high \
+MOSAIC_AGENT_TOOL_POLICY=operator-interaction \
+  ~/.config/mosaic/tools/fleet/print-interaction-effective-policy.sh
 ```

 Do not use `tmux kill-server` without `-L mosaic-fleet`; this pattern is meant
--- a/packages/mosaic/framework/systemd/user/mosaic-interaction-agent@.service
+++ b/packages/mosaic/framework/systemd/user/mosaic-interaction-agent@.service
@@ -0,0 +1,17 @@
+[Unit]
+Description=Mosaic operator interaction agent %i
+Documentation=https://git.mosaicstack.dev/mosaicstack/stack
+Requires=mosaic-tmux-holder.service
+After=mosaic-tmux-holder.service
+PartOf=mosaic-tmux-holder.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+Environment=MOSAIC_AGENT_NAME=%i
+EnvironmentFile=%h/.config/mosaic/fleet/agents/%i.env
+ExecStart=/bin/bash %h/.config/mosaic/tools/fleet/start-interaction-service.sh %i
+ExecStop=-/bin/bash -lc 'if [ -n "${MOSAIC_TMUX_SOCKET:-}" ]; then tmux -L "$MOSAIC_TMUX_SOCKET" kill-session -t "=%i"; else tmux kill-session -t "=%i"; fi'
+
+[Install]
+WantedBy=default.target
--- a/packages/mosaic/framework/systemd/user/test-fleet-units.sh
+++ b/packages/mosaic/framework/systemd/user/test-fleet-units.sh
@@ -4,6 +4,7 @@ set -euo pipefail
 SCRIPT_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
 HOLDER="$SCRIPT_DIR/mosaic-tmux-holder.service"
 AGENT="$SCRIPT_DIR/mosaic-agent@.service"
+INTERACTION="$SCRIPT_DIR/mosaic-interaction-agent@.service"

 fail() {
  echo "FAIL: $*" >&2
@@ -12,6 +13,7 @@ fail() {

 [ -f "$HOLDER" ] || fail "missing mosaic-tmux-holder.service"
 [ -f "$AGENT" ] || fail "missing mosaic-agent@.service"
+[ -f "$INTERACTION" ] || fail "missing mosaic-interaction-agent@.service"

 grep -qF 'ExecStart=' "$HOLDER" || fail "holder has no ExecStart"
 grep -qF 'tmux -L' "$HOLDER" || fail "holder does not use named tmux socket"
@@ -19,9 +21,12 @@ grep -qF '_holder' "$HOLDER" || fail "holder session is not explicit"
 grep -qF 'Requires=mosaic-tmux-holder.service' "$AGENT" || fail "agent does not require holder"
 grep -qF 'start-agent-session.sh' "$AGENT" || fail "agent unit does not call start-agent-session.sh"
 grep -qF 'kill-session -t "=%i"' "$AGENT" || fail "agent stop does not exact-match its session"
+grep -qF 'Requires=mosaic-tmux-holder.service' "$INTERACTION" || fail "interaction service does not require holder"
+grep -qF 'EnvironmentFile=%h/.config/mosaic/fleet/agents/%i.env' "$INTERACTION" || fail "interaction service does not require per-agent config"
+grep -qF 'start-interaction-service.sh %i' "$INTERACTION" || fail "interaction service does not validate before startup"

 if command -v systemd-analyze >/dev/null 2>&1; then
-  systemd-analyze verify --user "$HOLDER" "$AGENT" >/tmp/mosaic-fleet-systemd-verify.log 2>&1 || {
+  systemd-analyze verify --user "$HOLDER" "$AGENT" "$INTERACTION" >/tmp/mosaic-fleet-systemd-verify.log 2>&1 || {
    cat /tmp/mosaic-fleet-systemd-verify.log >&2
    fail "systemd-analyze verify failed"
  }
--- a/packages/mosaic/framework/tools/fleet/print-interaction-effective-policy.sh
+++ b/packages/mosaic/framework/tools/fleet/print-interaction-effective-policy.sh
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+AGENT_NAME=${MOSAIC_AGENT_NAME:-}
+RUNTIME=${MOSAIC_AGENT_RUNTIME:-}
+MODEL=${MOSAIC_AGENT_MODEL:-}
+REASONING=${MOSAIC_AGENT_REASONING:-}
+TOOL_POLICY=${MOSAIC_AGENT_TOOL_POLICY:-}
+
+[ -n "$AGENT_NAME" ] || { echo 'ERROR: MOSAIC_AGENT_NAME is required' >&2; exit 64; }
+[[ "$AGENT_NAME" =~ ^[A-Za-z0-9_.-]+$ ]] || { echo 'ERROR: invalid agent name' >&2; exit 64; }
+[ "$RUNTIME" = 'pi' ] || { echo 'ERROR: invalid runtime policy' >&2; exit 64; }
+[ "$MODEL" = 'openai/gpt-5.6-sol' ] || { echo 'ERROR: invalid model policy' >&2; exit 64; }
+[ "$REASONING" = 'high' ] || { echo 'ERROR: invalid reasoning policy' >&2; exit 64; }
+[ "$TOOL_POLICY" = 'operator-interaction' ] || { echo 'ERROR: invalid tool policy' >&2; exit 64; }
+
+printf '{"agentName":"%s","runtime":"%s","model":"%s","reasoning":"%s","toolPolicy":"%s"}\n' \
+  "$AGENT_NAME" "$RUNTIME" "$MODEL" "$REASONING" "$TOOL_POLICY"
--- a/packages/mosaic/framework/tools/fleet/start-agent-session.sh
+++ b/packages/mosaic/framework/tools/fleet/start-agent-session.sh
@@ -8,6 +8,7 @@ AGENT_NAME=${1:-${MOSAIC_AGENT_NAME:-}}
 MOSAIC_TMUX_SOCKET=${MOSAIC_TMUX_SOCKET:-}
 MOSAIC_AGENT_RUNTIME=${MOSAIC_AGENT_RUNTIME:-pi}
 MOSAIC_AGENT_MODEL=${MOSAIC_AGENT_MODEL:-}
+MOSAIC_AGENT_REASONING=${MOSAIC_AGENT_REASONING:-}
 MOSAIC_AGENT_WORKDIR=${MOSAIC_AGENT_WORKDIR:-$HOME}
 MOSAIC_AGENT_COMMAND=${MOSAIC_AGENT_COMMAND:-}
 MOSAIC_HEARTBEAT_RUN_DIR=${MOSAIC_HEARTBEAT_RUN_DIR:-${MOSAIC_HOME:-$HOME/.config/mosaic}/fleet/run}
@@ -18,6 +19,14 @@ if [ -z "$AGENT_NAME" ]; then
  exit 64
 fi

+case "$MOSAIC_AGENT_REASONING" in
+  ''|low|medium|high) ;;
+  *)
+    echo "ERROR: MOSAIC_AGENT_REASONING must be low, medium, or high" >&2
+    exit 64
+    ;;
+esac
+
 if ! command -v tmux >/dev/null 2>&1; then
  echo "ERROR: tmux is required" >&2
  exit 69
@@ -41,7 +50,7 @@ fi
 if [ -z "$MOSAIC_AGENT_COMMAND" ]; then
  # Map the roster's per-agent model_hint to `--model` so workers launch on the
  # configured model (e.g. pi on openai-codex/gpt-5.5:high). Omitted when unset.
-  MOSAIC_AGENT_COMMAND="mosaic yolo $MOSAIC_AGENT_RUNTIME${MOSAIC_AGENT_MODEL:+ --model $MOSAIC_AGENT_MODEL}"
+  MOSAIC_AGENT_COMMAND="mosaic yolo $MOSAIC_AGENT_RUNTIME${MOSAIC_AGENT_MODEL:+ --model $MOSAIC_AGENT_MODEL}${MOSAIC_AGENT_REASONING:+ --thinking $MOSAIC_AGENT_REASONING}"
 fi

 # ── Derive a runtime-bin PATH prefix ─────────────────────────────────────────
@@ -124,11 +133,12 @@ AGENT_NAME_Q=$(printf '%q' "$AGENT_NAME")
 # safe single bash token; an empty/unset class %q-quotes to '' and is a harmless
 # no-op downstream (readPersonaContractBlock returns '' for an empty class).
 AGENT_CLASS_Q=$(printf '%q' "${MOSAIC_AGENT_CLASS:-}")
+AGENT_TOOL_POLICY_Q=$(printf '%q' "${MOSAIC_AGENT_TOOL_POLICY:-}")

 if [ -n "$MOSAIC_RUNTIME_BIN_PREFIX" ]; then
-  PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; export MOSAIC_AGENT_CLASS=${AGENT_CLASS_Q}; export PATH=\"${MOSAIC_RUNTIME_BIN_PREFIX}:\${PATH}\"; exec ${MOSAIC_AGENT_COMMAND}"
+  PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; export MOSAIC_AGENT_CLASS=${AGENT_CLASS_Q}; export MOSAIC_AGENT_TOOL_POLICY=${AGENT_TOOL_POLICY_Q}; export PATH=\"${MOSAIC_RUNTIME_BIN_PREFIX}:\${PATH}\"; exec ${MOSAIC_AGENT_COMMAND}"
 else
-  PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; export MOSAIC_AGENT_CLASS=${AGENT_CLASS_Q}; exec ${MOSAIC_AGENT_COMMAND}"
+  PANE_SHELL_SNIPPET="export MOSAIC_AGENT_NAME=${AGENT_NAME_Q}; export MOSAIC_AGENT_CLASS=${AGENT_CLASS_Q}; export MOSAIC_AGENT_TOOL_POLICY=${AGENT_TOOL_POLICY_Q}; exec ${MOSAIC_AGENT_COMMAND}"
 fi

 mkdir -p "$MOSAIC_AGENT_WORKDIR"
--- a/packages/mosaic/framework/tools/fleet/start-interaction-service.sh
+++ b/packages/mosaic/framework/tools/fleet/start-interaction-service.sh
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+AGENT_NAME=${1:-}
+
+fail() {
+  echo "ERROR: $*" >&2
+  exit 64
+}
+
+[ -n "$AGENT_NAME" ] || fail "agent name argument is required"
+[[ "$AGENT_NAME" =~ ^[A-Za-z0-9_.-]+$ ]] || fail "agent name contains unsupported characters"
+[ "${MOSAIC_AGENT_NAME:-}" = "$AGENT_NAME" ] || fail "configured agent name must exactly match the service instance"
+[ "${MOSAIC_AGENT_RUNTIME:-}" = "pi" ] || fail "operator interaction service requires runtime pi"
+[ "${MOSAIC_AGENT_MODEL:-}" = "openai/gpt-5.6-sol" ] || fail "operator interaction service requires the pinned model"
+[ "${MOSAIC_AGENT_REASONING:-}" = "high" ] || fail "operator interaction service requires high reasoning"
+[ "${MOSAIC_AGENT_TOOL_POLICY:-}" = "operator-interaction" ] || fail "operator interaction service requires the operator-interaction tool policy"
+
+exec "$(cd -- "$(dirname -- "$0")" && pwd)/start-agent-session.sh" "$AGENT_NAME"
--- a/packages/mosaic/framework/tools/fleet/test-start-agent-session.sh
+++ b/packages/mosaic/framework/tools/fleet/test-start-agent-session.sh
@@ -105,6 +105,7 @@ MOSAIC_TMUX_SOCKET="$SOCKET3" \
 MOSAIC_AGENT_WORKDIR="$WORKDIR3" \
 MOSAIC_AGENT_RUNTIME="pi" \
 MOSAIC_AGENT_CLASS="code" \
+MOSAIC_AGENT_TOOL_POLICY="operator-interaction" \
 MOSAIC_RUNTIME_BIN="$FAKE_RUNTIME_BIN" \
 MOSAIC_AGENT_COMMAND="mosaic yolo pi --model openai-codex/gpt-5.5:high" \
 MOSAIC_HEARTBEAT_RUN_DIR="$HB_RUN_DIR3" \
@@ -139,6 +140,8 @@ echo "$all_args" | grep -qF "export MOSAIC_AGENT_NAME=" || \
  fail "pane command does not export MOSAIC_AGENT_NAME into the pane"
 echo "$all_args" | grep -qF "export MOSAIC_AGENT_CLASS=code" || \
  fail "pane command does not export MOSAIC_AGENT_CLASS into the pane (persona would silently drop)"
+echo "$all_args" | grep -qF "export MOSAIC_AGENT_TOOL_POLICY=operator-interaction" || \
+  fail "pane command does not export MOSAIC_AGENT_TOOL_POLICY into the pane"

 # ── Test 4: when no extra runtime-bin dirs exist, exec still appears ───────────
 TMUX_ARGS_FILE2=$(mktemp)