88 lines
4.0 KiB
Markdown
88 lines
4.0 KiB
Markdown
# Pi User Authentication and Startup Error Handling Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Make Dockerized Pi consume the configured user auth store, expose four approved models, fail session startup cleanly, and remove three incomplete attempts.
|
|
|
|
**Architecture:** Compose mounts only the host Pi `auth.json` into the container while repository-owned Pi settings define the model policy. The backend validates the persisted model before creating a session and converts post-persistence runtime-construction errors into a failed session plus a sanitized 503.
|
|
|
|
**Tech Stack:** Docker Compose, Pi 0.80.3, Fastify/TypeScript, Vitest, shell deployment-contract tests.
|
|
|
|
## Global Constraints
|
|
|
|
- Never copy or log provider keys.
|
|
- Mount the auth file read-only.
|
|
- Enabled model order is ZAI, DeepSeek Flash, DeepSeek Pro, local Qwen.
|
|
- UI error strings remain English.
|
|
- Preserve the question in the frontend retry composer.
|
|
- Delete only the three explicitly approved incomplete session IDs.
|
|
|
|
---
|
|
|
|
### Task 1: Container Pi auth and model policy
|
|
|
|
**Files:**
|
|
- Modify: `compose.yaml`
|
|
- Modify: `.env.example`
|
|
- Modify: `deploy/pi/settings.json`
|
|
- Modify: `docker/core.Dockerfile`
|
|
- Test: `scripts/test-default-compose.sh`
|
|
- Test: `scripts/test-container-deployment.sh`
|
|
|
|
**Interfaces:**
|
|
- Consumes: `PI_AUTH_FILE`, an absolute readable host path.
|
|
- Produces: `/home/thoth/.pi/agent/auth.json` read-only and a four-entry `enabledModels` policy.
|
|
|
|
- [ ] Add failing deployment-contract assertions for the auth mount, four enabled models, and Pi 0.80.3.
|
|
- [ ] Run the focused shell tests and confirm the expected failures.
|
|
- [ ] Add the configurable auth mount, model policy, environment documentation, and Pi version alignment.
|
|
- [ ] Re-run the focused shell tests and confirm they pass.
|
|
|
|
### Task 2: Pre-persistence model availability guard
|
|
|
|
**Files:**
|
|
- Modify: `backend/src/app.ts`
|
|
- Modify: `backend/src/routes/sessions.ts`
|
|
- Test: `backend/test/routes-sessions.test.ts`
|
|
|
|
**Interfaces:**
|
|
- Consumes: the existing `ListModelsFn` used by model/settings routes.
|
|
- Produces: a sanitized 503 before `sessionNew` when saved settings are unavailable.
|
|
|
|
- [ ] Add a failing route test proving an unavailable model returns 503 and never calls `sessionNew`.
|
|
- [ ] Run the single Vitest test and confirm the expected failure.
|
|
- [ ] Inject the model-list dependency into session routes and implement the minimal guard.
|
|
- [ ] Re-run the focused test and confirm it passes.
|
|
|
|
### Task 3: Post-persistence runtime-construction failure
|
|
|
|
**Files:**
|
|
- Modify: `backend/src/routes/sessions.ts`
|
|
- Test: `backend/test/routes-sessions.test.ts`
|
|
|
|
**Interfaces:**
|
|
- Consumes: `ThtRunner.failSession(id, workspace)` and `PiProcessManager.createFor`.
|
|
- Produces: failed persisted state plus sanitized 503 when runtime construction throws.
|
|
|
|
- [ ] Add a failing route test for a throwing `createFor` after `sessionNew`.
|
|
- [ ] Run the single test and confirm it fails because the route currently returns 500 and leaves the session open.
|
|
- [ ] Catch runtime construction/binding failures, persist `failed`, and return the startup error.
|
|
- [ ] Re-run the focused test and confirm it passes.
|
|
|
|
### Task 4: Cleanup and full verification
|
|
|
|
**Files:**
|
|
- Modify: external PSD session store only through `tht session delete`.
|
|
|
|
**Interfaces:**
|
|
- Consumes: the three approved session IDs.
|
|
- Produces: no corresponding directories or API rows.
|
|
|
|
- [ ] Run backend Vitest and TypeScript typecheck.
|
|
- [ ] Run deployment-contract tests and render Compose with the real auth path.
|
|
- [ ] Rebuild/recreate the core container and verify health.
|
|
- [ ] Verify `/models` returns all four enabled models in order.
|
|
- [ ] Start a uniquely named DeepSeek smoke and observe the first reviewer gate; clean up only the smoke.
|
|
- [ ] Delete the three approved incomplete sessions and verify they are absent.
|
|
- [ ] Run `git diff --check` and inspect the final diff for secret leakage.
|