pi-sage 0.2.0

package/docs/coding-standards.md

@@ -0,0 +1,116 @@
+# Coding Standards for Sage
+
+## 1) Purpose
+
+This document defines the engineering standards for building and evolving Sage.
+
+Sage is a **high-reasoning advisory subagent**, not an execution agent. Code should optimize for safety, determinism, observability, and maintainability.
+
+---
+
+## 2) Scope
+
+These standards apply to all Sage-related code, including:
+- extension runtime code (`.pi/extensions/sage/*`)
+- settings and policy layers
+- subprocess runner logic
+- prompt/system-guidance injection
+- tests and supporting tooling
+
+---
+
+## 3) Non-Negotiable Product Constraints
+
+Every implementation must preserve these behaviors:
+
+1. **Interactive-primary-only invocation**
+   - Sage can only be invoked from top-level interactive primary sessions.
+2. **No recursion**
+   - Sage subagents cannot invoke `sage_consult`.
+3. **Single-shot interaction**
+   - One request -> one Sage response; no multi-turn Sage loops.
+4. **Advisory-only execution model**
+   - Sage provides analysis/recommendations, not direct implementation actions.
+5. **Deny-by-default policy**
+   - Unknown/missing caller context must block invocation.
+
+---
+
+## 4) Architecture and Design Principles
+
+1. **Policy-first execution**
+   - Evaluate hard gates (caller context, safety) before soft budget checks.
+2. **Fail safe, not permissive**
+   - On ambiguity, block with structured reason codes.
+3. **Small composable modules**
+   - Separate `policy`, `tool-policy`, `runner`, `settings`, and `types`.
+4. **Pure functions for critical policy logic**
+   - Keep eligibility and guardrail checks side-effect-free for easy testing.
+5. **No hidden behavior**
+   - Important policy decisions must be visible in structured metadata.
+
+---
+
+## 5) TypeScript Standards
+
+1. Use strict typing and explicit interfaces for all policy and result contracts.
+2. Avoid `any`; if unavoidable, isolate and document with rationale.
+3. Prefer discriminated unions for block codes and policy outcomes.
+4. Use exhaustive `switch` handling for enums/unions.
+5. Keep function signatures narrow and intention-revealing.
+6. Export reusable types from a single `types.ts` module.
+
+---
+
+## 6) Error and Result Handling
+
+1. Return structured block/failure outcomes with stable `blockCode` values.
+2. Never crash the primary flow due to Sage failure.
+3. Use consistent result shapes for successful and blocked paths.
+4. Include user-facing, concise explanations for blocked invocations.
+5. Preserve diagnostic detail in `details` for debugging and telemetry.
+
+---
+
+## 7) Security and Access Controls
+
+1. Enforce advisory tool policy by default (`read-only-lite`: `ls,glob,grep,read`).
+2. Disallow mutating/execution/network/orchestration tools in Sage.
+3. Restrict filesystem reads to workspace/project roots.
+4. Apply sensitive-path denylist by default (`.env*`, `*.pem`, `*.key`, etc.).
+5. Enforce per-call volume limits (tool calls/files/bytes/result caps).
+
+---
+
+## 8) Observability Standards
+
+Each Sage call should emit enough metadata to explain behavior:
+- invocation mode (`autonomous` vs `user-requested`)
+- caller-context allow/block decision
+- block reason and stable block code when denied
+- model, reasoning level, latency
+- token usage/cost (when available)
+- tool profile and tool usage counters
+
+Observability must support both operator trust and debugging efficiency.
+
+---
+
+## 9) Documentation and Change Discipline
+
+1. Keep implementation aligned with `docs/SAGE_SPEC.md` (locked baseline).
+2. Update spec/docs in the same PR when behavior changes.
+3. Document policy changes as explicit decisions (not implicit code drift).
+4. Add short rationale comments for non-obvious guardrails.
+
+---
+
+## 10) Code Review Checklist (Required)
+
+- [ ] Interactive-only caller gate remains non-bypassable.
+- [ ] No recursion paths exist (`sage_consult` unavailable to Sage subprocess).
+- [ ] Single-shot behavior preserved.
+- [ ] Tool policy remains advisory/read-only by default.
+- [ ] Blocked and success paths return consistent structured metadata.
+- [ ] New behavior has unit/integration coverage.
+- [ ] Docs/spec updated if behavior changed.

package/docs/installation-requirements.md

@@ -0,0 +1,70 @@
+# Installation Requirements (End Users)
+
+This extension is designed for Pi and is installed as a Pi package.
+
+## Required
+
+1. **Pi CLI installed and on PATH**
+   - `pi --version` should work from the shell.
+2. **Pi 0.64.0+**
+3. **Model/provider auth configured in Pi**
+   - e.g., Anthropic/OpenAI/Gemini keys or OAuth login.
+4. **Interactive session usage**
+   - Sage is intentionally restricted to interactive top-level primary sessions.
+
+## Optional (profile-dependent)
+
+- **git CLI**
+  - Needed only when using the `git-review-readonly` tool profile.
+
+## Install commands
+
+### Global
+
+```bash
+pi install npm:pi-sage
+```
+
+### Project-local
+
+```bash
+pi install -l npm:pi-sage
+```
+
+After install, run `/reload` in Pi.
+
+## File locations by install scope
+
+### Global install
+
+- Package reference is stored in: `~/.pi/agent/settings.json`
+- Package files are installed with `npm install -g` in npm global node_modules
+  - Windows typical: `%APPDATA%/npm/node_modules/pi-sage/`
+  - macOS/Linux typical: `<npm-global-prefix>/lib/node_modules/pi-sage/`
+
+Find exact global path with:
+
+```bash
+npm root -g
+```
+
+### Project-local install
+
+- Package reference is stored in: `.pi/settings.json`
+- Package files are installed under project-local Pi storage: `.pi/npm/`
+
+## Settings precedence
+
+Sage settings resolve in this order:
+
+1. `.pi/sage-settings.json` (project)
+2. `~/.pi/agent/sage-settings.json` (global)
+3. defaults
+
+This enables a global default configuration with per-project overrides.
+
+## Troubleshooting
+
+- If Sage cannot start, verify `pi` is executable in the runtime environment.
+- If no Sage model is found, verify provider auth and model availability.
+- If consultations block on limits, adjust cap settings in `/sage-settings`.

package/docs/interactive-e2e-harness.md

@@ -0,0 +1,46 @@
+# Interactive E2E Harness Plan (Sage)
+
+## Purpose
+
+Sage is intentionally restricted to interactive top-level primary sessions.
+Because of this, E2E validation must run through an interactive Pi session path, not RPC-only execution.
+
+## Harness Strategy
+
+Use `tmux` to drive a real interactive Pi session:
+
+1. Start a dedicated tmux session for E2E.
+2. Launch `pi` in interactive mode in the project root.
+3. Send commands/prompts via `tmux send-keys`.
+4. Capture output via `tmux capture-pane` and/or parse session JSONL artifacts.
+5. Assert expected behavior in Node `node:test` suites.
+
+## Core Flows to Validate
+
+1. `/reload` picks up extension changes in-session.
+2. Eligible caller path can invoke Sage.
+3. Explicit "second opinion" request invokes Sage in eligible interactive context.
+4. Ineligible contexts are blocked with structured metadata and no subprocess launch.
+
+## Suggested Script Structure
+
+- `scripts/e2e/start-interactive-session.sh`
+- `scripts/e2e/send-input.sh`
+- `scripts/e2e/capture-output.sh`
+- `scripts/e2e/stop-interactive-session.sh`
+
+## Assertion Sources
+
+Prefer deterministic artifacts over rendered text where possible:
+- session entries / tool result details
+- structured `policy` block metadata
+- explicit block codes
+
+Use pane text capture as supplemental debugging evidence.
+
+## Reliability Notes
+
+- Add bounded waits and retry windows for async turn completion.
+- Ensure each test uses an isolated session directory.
+- Clean up tmux sessions even on failure.
+- Keep E2E cases focused and few; rely on unit/integration for matrix depth.

package/docs/testing-standards.md

@@ -0,0 +1,175 @@
+# Testing Standards for Sage
+
+## 1) Purpose
+
+This document defines the required testing methodology for Sage development.
+
+Primary goals:
+- prevent policy regressions
+- detect safety/security drift early
+- keep iteration fast while maintaining high confidence
+
+---
+
+## 2) Testing Philosophy
+
+Sage testing follows a layered strategy:
+1. **Static quality gates** (lint, type checks)
+2. **Fast deterministic unit tests**
+3. **Integration tests for policy + runtime boundaries**
+4. **Interactive E2E tests for real behavior validation**
+
+No single layer is sufficient on its own.
+
+### Test runner standard (mandatory)
+
+- Use **Node’s built-in test runner** (`node:test`, executed via `node --test`).
+- TypeScript test files are supported via Node-compatible TS execution (`node --import tsx --test ...` or equivalent Node-native setup).
+- **Vitest is not allowed** for this project.
+
+---
+
+## 3) Mandatory Continuous Test Pipeline
+
+Every active development loop and PR must include:
+
+1. **Lint** (required)
+2. **Typecheck** (required)
+3. **Unit tests** (required)
+4. **Integration tests** (required)
+5. **E2E tests** (required for behavior-impacting changes)
+
+### Required command contract
+
+The project should provide these scripts (or equivalent), backed by Node's built-in test runner:
+
+- `npm run lint`
+- `npm run typecheck`
+- `npm run test:unit` (Node test runner)
+- `npm run test:integration` (Node test runner)
+- `npm run test:e2e` (Node test runner)
+- `npm test` (full suite)
+
+If script names differ, document the mapping in this file.
+
+---
+
+## 4) Test Layers and Expectations
+
+## 4.1 Lint (required)
+
+Lint must run on every change and fail the pipeline on violations.
+
+Minimum expectations:
+- no unused vars/imports
+- no implicit `any` in critical modules
+- no unsafe ignored promise errors
+- no dead/unreachable policy branches
+
+## 4.2 Typecheck (required)
+
+Typecheck should run in strict mode for Sage modules and fail on:
+- type unsoundness in policy/result contracts
+- incomplete union handling for block codes
+- incompatible details/result schema changes
+
+## 4.3 Unit Tests (required)
+
+Unit tests must cover deterministic logic:
+- caller eligibility gate
+- soft/hard gate ordering
+- tool policy resolution
+- path denylist logic
+- volume cap logic
+- block result construction
+
+Target: high branch coverage in policy modules.
+
+## 4.4 Integration Tests (required)
+
+Integration tests must validate end-to-end behavior of `sage_consult` handler logic (without relying solely on mocks):
+- explicit request bypasses soft limits only
+- hard caller gate remains non-bypassable
+- RPC roles are blocked
+- non-interactive/CI contexts are blocked
+- advisory tool profile enforcement
+- structured metadata returned for success and blocked cases
+
+## 4.5 E2E Tests (required for behavior changes)
+
+Because Sage is interactive-only, E2E tests must exercise a real interactive session path.
+
+Required E2E checks:
+- interactive primary can invoke Sage
+- `/reload` workflow preserves extension behavior
+- explicit “second opinion” path triggers Sage in eligible context
+- blocked contexts never spawn Sage subprocess
+
+---
+
+## 5) Sage-Specific Regression Matrix (Must Stay Green)
+
+### Caller-context gating
+- [ ] interactive + primary + non-subagent + non-RPC + non-CI -> allowed
+- [ ] non-interactive -> blocked
+- [ ] CI mode -> blocked
+- [ ] RPC orchestrated role -> blocked
+- [ ] subagent -> blocked
+- [ ] unknown/missing context -> blocked
+
+### Invocation behavior
+- [ ] explicit request bypasses soft limits
+- [ ] explicit request does NOT bypass hard safety limits
+- [ ] explicit request does NOT bypass caller-scope gate
+- [ ] single-shot only
+- [ ] no recursion
+
+### Tool/data policy
+- [ ] default profile is `read-only-lite`
+- [ ] disallowed tools blocked (`edit`, `write`, `bash`, `sage_consult`, etc.)
+- [ ] denylisted paths blocked
+- [ ] volume caps enforced
+
+---
+
+## 6) CI Policy
+
+1. CI must fail fast on lint/typecheck failures.
+2. Unit+integration must run on every PR.
+3. E2E must run for policy/runtime changes (or at minimum before merge to main).
+4. Failing tests block merge unless explicitly waived with documented justification.
+5. CI test jobs must use Node’s built-in test runner (no Vitest jobs).
+
+---
+
+## 7) Flaky Test Policy
+
+1. Flaky tests are treated as defects, not noise.
+2. Quarantine only with an owner + issue + deadline.
+3. No permanent quarantines.
+4. Add deterministic fixtures/timeouts to reduce nondeterminism.
+
+---
+
+## 8) Artifacts and Diagnostics
+
+For failed CI runs, capture:
+- lint output
+- typecheck output
+- failed test logs
+- relevant session/tool metadata for Sage calls
+
+Interactive E2E failures should include terminal/session transcripts sufficient for reproduction.
+
+---
+
+## 9) Definition of Done (Testing)
+
+A Sage change is test-complete only when:
+- [ ] lint passes
+- [ ] typecheck passes
+- [ ] unit tests pass
+- [ ] integration tests pass
+- [ ] required E2E tests pass
+- [ ] new behavior has coverage and assertions
+- [ ] regressions are not introduced in caller/tool policy gates

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "pi-sage",
+  "version": "0.2.0",
+  "private": false,
+  "type": "module",
+  "description": "Interactive-only advisory Sage extension for Pi",
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "sage",
+    "code-review"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HenryLach/sage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/HenryLach/sage/issues"
+  },
+  "homepage": "https://github.com/HenryLach/sage#readme",
+  "license": "MIT",
+  "files": [
+    ".pi/extensions/sage/**",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE",
+    "docs/*.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./.pi/extensions/sage/index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepare": "husky",
+    "lint": "eslint . --ext .ts,.mts,.cts --max-warnings=0",
+    "typecheck": "tsc --noEmit",
+    "test:unit": "node --import tsx --test test/unit/**/*.test.ts",
+    "test:integration": "node --import tsx --test test/integration/**/*.test.ts",
+    "test:e2e": "node --import tsx --test test/e2e/**/*.test.ts",
+    "test": "npm run lint && npm run typecheck && npm run test:unit && npm run test:integration && npm run test:e2e"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.49"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.64.0",
+    "@types/node": "^22.15.3",
+    "@typescript-eslint/eslint-plugin": "^8.30.1",
+    "@typescript-eslint/parser": "^8.30.1",
+    "eslint": "^9.24.0",
+    "husky": "^9.1.7",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.3"
+  }
+}