Files

T

Kai f25082223e docs: repository README, contributor rules, scenario template and authoring guide

README leads with the finding that motivated the repository -- pi emits the
skills section only when a tool named 'read' is active, so Curator's
--no-tools --skill combination made its policy unreachable -- with the measured
before/after table and instructions to reproduce it at zero token cost.

AGENTS.md sets seven rules for anyone changing this repository. The third is the
one that matters most: verify pi's behaviour with a probe rather than inferring it
from the docs. Three claims in the first draft of these documents were wrong and
were only corrected by running one.

The _template scenario carries the isolation defaults and inline warnings at the
places where mistakes have already cost time: --no-tools disabling the skills
mechanism, cwd anchoring .pi discovery, the read override being mandatory rather
than optional, and allowed-tools frontmatter not being enforced in 0.84.3.

2026-08-26 23:19:19 -07:00

5.0 KiB

Raw Blame History

pi-agent-config

Authoritative configuration for every Pi agent on this host: the user-level Pi runtime, plus one directory per dedicated agent scenario.

The live locations (~/.pi/agent, ~/pi-workspaces/*) are runtime copies. Changes are made here and pushed out with scripts/deploy-*.sh, never the other way round — except for scenarios explicitly marked deploy = "mirror", which record what a running service already does.

Verified against pi 0.84.3. Re-run the probes after every pi update.

Scenarios

Scenario	Purpose	Service	Status
`curator`	Book / film / TV / music curation agent	`curator.service`	target config written, not yet deployed
`memo-inbox`	Routes Telegram/WeChat messages to Calendar, Obsidian todo or journal	`pi-memo-telegram.service`	mirror of live config, zero behaviour change
`pi-grok`	Interactive Grok 4.6 coding agent	none (manual)	registered only

Start here

Document	Contents
`docs/pi-runtime-notes.md`	pi 0.84.3 mechanics that the official docs understate, each verified against source or a live probe
`docs/isolation-baseline.md`	The four isolation layers and the flag set every scenario should use
`docs/personality-layering.md`	How to choose between `SYSTEM.md`, `APPEND_SYSTEM.md`, `AGENTS.md`, `SKILL.md` and the request
`docs/gateway-patterns.md`	Ten patterns for hosting an agent behind a long-running service
`docs/plans/`	Active work plans

The finding that motivated this repository

pi emits the <available_skills> block only when a tool named read is active (dist/core/system-prompt.js:59,113). The Curator service ran with --no-tools --skill … for its entire lifetime, so:

its 64-line media policy never reached the model,
--skill was a no-op,
and both the README and the deployment runbook described a mechanism that was not happening.

Measured effect of fixing the flags and adding .pi/SYSTEM.md:

Configuration	system prompt	active tools	skills visible	coding-assistant persona
`--no-tools` (as found)	1859	none	no	yes
no isolation flags	3413	own + `read`	3 foreign	yes
`+ --no-skills --skill`	2619	own + `read`	1, correct	yes
`+ .pi/SYSTEM.md --approve`	960	own + `read`	1, correct	no

72 % smaller and strictly more capable. Reproduce with docs/evidence/probe-harness/ — it costs zero model tokens, because a single RPC get_state starts the agent, fires session_start and exits without contacting the provider.

Layout

docs/            mechanics, baselines, plans, reproducible evidence
runtime/agent/   ~/.pi/agent — settings, models.json.template, extensions, prompts
shared/          cross-scenario code
  lib/py/pi_rpc.py            long-lived RPC client with rotation and budgets
  extensions/pi-guard-base.ts path containment, restricted read, capability guard
scenarios/<name>/
  profile.toml   single source of truth for the launch contract
  workspace/     what gets installed into the live workspace
  eval/          recorded golden transcripts
scripts/         diff, deploy, backup, restore, secret guard
secrets/         host-local, untracked

Usage

# What differs between this repository and the host?
scripts/pi-diff.sh
scripts/pi-diff.sh curator

# Push configuration out (dry run first; neither restarts a service)
scripts/deploy-runtime.sh
scripts/deploy-runtime.sh --apply
scripts/deploy-scenario.sh curator --apply

# Back up the live installation (archives land outside this repository)
scripts/pi-backup.sh
scripts/pi-restore.sh --from <backup dir>

# Verify the mechanics still hold after a pi upgrade
docs/evidence/probe-harness/collect-evidence.sh
shared/extensions/tests/run-guard-checks.sh
python3 shared/lib/py/tests/test_pi_rpc_smoke.py

Secrets

Nothing real ever enters this repository. models.json, auth.json, trust.json and every *.env are ignored; secrets/ accepts only .gitkeep, README.md, *.example and *.template.

scripts/verify-no-secrets.sh enforces this as a pre-commit hook. Install it in a fresh clone:

ln -sf ../../scripts/verify-no-secrets.sh .git/hooks/pre-commit
scripts/verify-no-secrets.sh --all

Backups contain plaintext credentials and are written outside the work tree; pi-backup.sh refuses any destination that resolves inside it.

First-time setup on a new host

git clone gitea-45:kai/pi-agent-config.git && cd pi-agent-config
ln -sf ../../scripts/verify-no-secrets.sh .git/hooks/pre-commit

cp secrets/zenmux.env.example secrets/zenmux.env
chmod 600 secrets/zenmux.env && $EDITOR secrets/zenmux.env

npm install -g @earendil-works/pi-coding-agent@0.84.3
scripts/deploy-runtime.sh --apply
scripts/deploy-scenario.sh <scenario> --apply

5.0 KiB Raw Blame History