Skip to content

Commit 542c5b0

Browse files
author
Alex
committed
Merge remote-tracking branch 'upstream/main'
2 parents 478c8c2 + 8326637 commit 542c5b0

120 files changed

Lines changed: 7142 additions & 12173 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.beads/issues.jsonl‎

Lines changed: 1392 additions & 1391 deletions
Large diffs are not rendered by default.

‎.claude/skills/pi-agent-rust/SKILL.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
---
2+
name: pi-agent-rust
3+
description: >-
4+
Speeds up pi_agent_rust development and verification workflows. Use when editing providers,
5+
tools, sessions, extensions, installer/uninstaller logic, or triaging regressions in this repo.
6+
---
7+
8+
<!-- pi_agent_rust installer managed skill -->
9+
10+
# Pi Agent Rust
11+
12+
## Use This Skill When
13+
14+
- You are working inside `pi_agent_rust` and need the fastest path to safe, verified edits.
15+
- You are touching provider/tool/session/extension behavior and need targeted triage.
16+
- You are changing installer/uninstaller/skill install behavior and need deterministic safety checks.
17+
- You need symptom-first debugging playbooks instead of ad-hoc command hunting.
18+
19+
## 60-Second Bootstrap
20+
21+
```bash
22+
export CARGO_TARGET_DIR="/data/tmp/pi_agent_rust/${USER:-agent}"
23+
export TMPDIR="/data/tmp/pi_agent_rust/${USER:-agent}/tmp"
24+
mkdir -p "$TMPDIR"
25+
26+
rch exec -- cargo check --all-targets
27+
rch exec -- cargo clippy --all-targets -- -D warnings
28+
cargo fmt --check
29+
bash tests/installer_regression.sh
30+
```
31+
32+
## Symptom Router
33+
34+
| Symptom | First 3 Commands |
35+
|---|---|
36+
| Provider stream/tool-call regression | `cargo test provider_streaming -- --nocapture` ; `rg -n "stream|tool|delta|event|SSE" src/providers src/sse.rs` ; `cargo test conformance` |
37+
| Session replay/index drift | `cargo test session -- --nocapture` ; `rg -n "Session|save|open|index|jsonl|sqlite" src/session.rs src/session_index.rs` ; `cargo test conformance` |
38+
| Extension policy/runtime failure | `cargo test extension -- --nocapture` ; `rg -n "policy|hostcall|capability|quickjs|deny|allow" src/extensions.rs src/extensions_js.rs` ; `cargo test conformance` |
39+
| Installer/uninstaller/skill issue | `bash tests/installer_regression.sh` ; `rg -n "AGENT_SKILL_STATUS|CHECKSUM_STATUS|SIGSTORE_STATUS|COMPLETIONS_STATUS" install.sh` ; `rg -n "managed skill|expected skill directory|PIAR_AGENT_SKILL" uninstall.sh` |
40+
| Interactive vs RPC divergence | `cargo test e2e_rpc -- --nocapture` ; `rg -n "interactive|rpc|stdin|event|session" src/main.rs src/interactive.rs src/rpc.rs` ; `cargo test conformance` |
41+
42+
For deeper diagnosis, use `references/DEBUGGING-PLAYBOOKS.md`.
43+
44+
## Non-Negotiables
45+
46+
- Read `AGENTS.md` first, then follow it exactly.
47+
- Do not delete files or run destructive git/filesystem commands.
48+
- Keep edits in-place; avoid creating variant files for the same purpose.
49+
- Use `main` semantics in docs/scripts; do not introduce `master`.
50+
- Prefer `rg` for fast text recon and `ast-grep` for structural matching/refactors.
51+
- Prefer `rch exec -- <cargo ...>` for heavy compile/test workloads.
52+
- After substantive edits, run compile/lint/format gates and the smallest relevant regression slice.
53+
54+
## Core Workflow
55+
56+
- [ ] Recon: identify exact change surface and invariants.
57+
- [ ] Implement: minimal, behavior-focused patch with explicit failure semantics.
58+
- [ ] Validate: targeted tests first, broaden only as needed.
59+
- [ ] Verify UX: error/status output is explicit, stable, and non-ambiguous.
60+
- [ ] Sync docs: update `README.md` when flags/behavior/user guidance changed.
61+
62+
## Changed Files -> Required Tests
63+
64+
| Changed Files (examples) | Minimum Required Tests |
65+
|---|---|
66+
| `install.sh`, `uninstall.sh`, `.claude/skills/pi-agent-rust/**` | `bash -n install.sh uninstall.sh tests/installer_regression.sh` ; `shellcheck -x install.sh uninstall.sh tests/installer_regression.sh` ; `bash tests/installer_regression.sh` ; `bash scripts/skill-smoke.sh` |
67+
| `src/providers/**`, `src/provider.rs`, `src/sse.rs` | `cargo test provider_streaming` ; `cargo test conformance` |
68+
| `src/session.rs`, `src/session_index.rs`, `src/session_test.rs` | `cargo test session` ; `cargo test conformance` |
69+
| `src/extensions.rs`, `src/extensions_js.rs` | `cargo test extension` ; `cargo test conformance` |
70+
| `src/tools.rs` | `cargo test tools` ; `cargo test conformance` |
71+
| `src/interactive.rs`, `src/rpc.rs`, `src/main.rs` | `cargo test e2e_rpc` ; `cargo test conformance` |
72+
73+
## Do Not Run Yet
74+
75+
Run these only after targeted repro + focused slice indicates need:
76+
77+
- Broad `cargo test` across entire workspace when a narrower slice already reproduces.
78+
- Heavy multi-surface runs before confirming changed-file impact.
79+
- Repeated full conformance loops while the core failing slice is still unstable.
80+
81+
## High-Value Commands
82+
83+
```bash
84+
# Fast recon
85+
git status --short
86+
rg -n "install|uninstall|skill|checksum|sigstore|completion|provider|session|extension" \
87+
install.sh uninstall.sh README.md tests/installer_regression.sh src/
88+
89+
# Installer + skill safety gates
90+
bash -n install.sh uninstall.sh tests/installer_regression.sh
91+
shellcheck -x install.sh uninstall.sh tests/installer_regression.sh
92+
bash tests/installer_regression.sh
93+
bash scripts/skill-smoke.sh
94+
95+
# Rust gates
96+
rch exec -- cargo check --all-targets
97+
rch exec -- cargo clippy --all-targets -- -D warnings
98+
cargo fmt --check
99+
```
100+
101+
For an expanded command cookbook, see `references/COMMANDS.md`.
102+
For deep incident triage, see `references/DEBUGGING-PLAYBOOKS.md`.
103+
104+
## Critical Files
105+
106+
- `src/main.rs`: CLI entry and mode dispatch.
107+
- `src/agent.rs`: agent loop and tool iteration behavior.
108+
- `src/provider.rs`: provider trait contract.
109+
- `src/providers/`: provider implementations and factory wiring.
110+
- `src/tools.rs`: built-in tools (`read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`).
111+
- `src/session.rs`: JSONL session persistence.
112+
- `src/session_index.rs`: session index and metadata cache.
113+
- `src/extensions.rs` + `src/extensions_js.rs`: extension policy and QuickJS bridge.
114+
- `src/interactive.rs` + `src/rpc.rs`: TUI and RPC/stdin surfaces.
115+
- `install.sh` + `uninstall.sh`: install lifecycle, migration, and skill management.
116+
- `tests/installer_regression.sh`: installer regression harness.
117+
- `scripts/skill-smoke.sh`: skill integrity + inline-sync validation.
118+
119+
## Known Footguns
120+
121+
- Custom artifact install paths without compatible release context can fall back incorrectly if not explicitly guarded.
122+
- Skill status can become misleading on mixed outcomes unless partial/failure branches are explicit.
123+
- Uninstall logic must enforce both marker checks and expected destination path shape.
124+
- Installer progress/status text should stay on stderr when stdout is used for data plumbing.
125+
- Bundled skill and inline fallback can silently drift unless explicitly checked.
126+
127+
## Patch Patterns
128+
129+
### Pattern 1: Mixed Outcome Status Clarity
130+
131+
```bash
132+
# BEFORE: everything collapsed into "skipped custom"
133+
if [ "$skipped_custom" -ge 1 ]; then
134+
AGENT_SKILL_STATUS="skipped (existing custom skill)"
135+
fi
136+
137+
# AFTER: distinguish custom-skip from write failure
138+
if [ "$skipped_custom" -ge 1 ] && [ "$failed_writes" -ge 1 ]; then
139+
AGENT_SKILL_STATUS="partial (custom skill kept; other install failed)"
140+
elif [ "$skipped_custom" -ge 1 ]; then
141+
AGENT_SKILL_STATUS="skipped (existing custom skill)"
142+
fi
143+
```
144+
145+
### Pattern 2: Safe Skill Replacement
146+
147+
```bash
148+
# BEFORE: remove destination before validating copy result
149+
rm -rf "$destination"
150+
cp "$source" "$destination/SKILL.md"
151+
152+
# AFTER: stage then atomically move into place
153+
staged="$(mktemp -d ...)"
154+
cp "$source" "$staged/SKILL.md"
155+
mv "$staged" "$destination"
156+
```
157+
158+
## Failure Triage
159+
160+
- Installer summary/status mismatch:
161+
trace `AGENT_SKILL_STATUS`, `CHECKSUM_STATUS`, and `COMPLETIONS_STATUS` in `install.sh`.
162+
- Install/uninstall safety concern:
163+
verify marker checks and expected destination guards in both scripts.
164+
- Provider/session/extension regressions:
165+
use symptom router, then follow `references/DEBUGGING-PLAYBOOKS.md`.
166+
- Docs drift:
167+
ensure `README.md` flags/examples match current installer behavior.
168+
169+
## Done Criteria
170+
171+
- Changed-file matrix minimum tests passed.
172+
- Compile/lint/format checks passed for touched surfaces.
173+
- Installer/skill changes pass `tests/installer_regression.sh` and `scripts/skill-smoke.sh`.
174+
- Behavior is explicit on failure paths; no silent fallback surprises.
175+
- Skill docs and inline fallback remain aligned and current.

‎.claude/skills/pi-agent-rust/references/COMMANDS.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Command Recipes
2+
3+
## 1) Session Bootstrap
4+
5+
```bash
6+
export CARGO_TARGET_DIR="/data/tmp/pi_agent_rust/${USER:-agent}"
7+
export TMPDIR="/data/tmp/pi_agent_rust/${USER:-agent}/tmp"
8+
mkdir -p "$TMPDIR"
9+
```
10+
11+
## 2) Fast Recon
12+
13+
```bash
14+
git status --short
15+
rg -n "TODO|FIXME|install|uninstall|skill|checksum|sigstore|completion|provider|session|extension" \
16+
install.sh uninstall.sh README.md tests/installer_regression.sh src/
17+
```
18+
19+
## 3) Skill Integrity and Sync Guard
20+
21+
```bash
22+
bash scripts/skill-smoke.sh
23+
```
24+
25+
## 4) Installer and Shell Safety Gates
26+
27+
```bash
28+
bash -n install.sh uninstall.sh tests/installer_regression.sh
29+
shellcheck -x install.sh uninstall.sh tests/installer_regression.sh
30+
bash tests/installer_regression.sh
31+
```
32+
33+
## 5) Rust Quality Gates
34+
35+
```bash
36+
# Preferred in multi-agent environments
37+
rch exec -- cargo check --all-targets
38+
rch exec -- cargo clippy --all-targets -- -D warnings
39+
40+
# Formatting can run locally
41+
cargo fmt --check
42+
```
43+
44+
## 6) Targeted Test Slices
45+
46+
```bash
47+
# Tool behavior
48+
cargo test tools
49+
50+
# Provider streaming/protocol
51+
cargo test provider_streaming
52+
53+
# Session persistence/index
54+
cargo test session
55+
56+
# Extension runtime/policy
57+
cargo test extension
58+
59+
# RPC surface
60+
cargo test e2e_rpc
61+
62+
# Broader safety net after targeted slices
63+
cargo test conformance
64+
```
65+
66+
## 7) Focused Installer Branch Debugging
67+
68+
```bash
69+
# Help/flag visibility
70+
bash install.sh --help
71+
72+
# Explicit custom artifact path (replace values for real run)
73+
bash install.sh --yes --offline --version v0.0.0 \
74+
--artifact-url "file:///tmp/pi-artifact" \
75+
--checksum "<sha256>" \
76+
--no-completions --no-agent-skills
77+
78+
# Uninstall smoke
79+
bash uninstall.sh --yes --no-gum
80+
```
81+
82+
## 8) Status and Safety Tracing
83+
84+
```bash
85+
# Installer status flow
86+
rg -n "AGENT_SKILL_STATUS|CHECKSUM_STATUS|SIGSTORE_STATUS|COMPLETIONS_STATUS" install.sh
87+
88+
# Skill install safety + replacement
89+
rg -n "install_skill_to_destination|is_installer_managed_skill_file|is_expected_skill_destination" install.sh
90+
91+
# Uninstall safety guards
92+
rg -n "remove_installed_skills|is_managed_skill_file|is_expected_skill_directory|PIAR_AGENT_SKILL" uninstall.sh
93+
```
94+
95+
## 9) Docs Drift Checks
96+
97+
```bash
98+
rg -n "no-agent-skills|completions|checksum|sigstore|artifact-url|skill" README.md install.sh uninstall.sh
99+
```
100+
101+
For symptom-driven step-by-step root-cause flows, use `DEBUGGING-PLAYBOOKS.md`.

0 commit comments

Comments
 (0)