Add artifact vault contents
This commit is contained in:
239
projects/dotfiles/026-pi-subagents-dotfiles-deployment-task.md
Normal file
239
projects/dotfiles/026-pi-subagents-dotfiles-deployment-task.md
Normal file
@@ -0,0 +1,239 @@
|
||||
---
|
||||
status: done
|
||||
claimed-by: "019fba91-eabf-76ae-b086-a37ac061d6e8"
|
||||
claimed-at: "2026-07-31T21:17:55-04:00"
|
||||
completed-at: "2026-07-31T21:18:12-04:00"
|
||||
parent: "[[002-pi-subagents-map]]"
|
||||
blocked-by: []
|
||||
tags:
|
||||
- ticket/task/afk
|
||||
---
|
||||
|
||||
# Dotfiles deployment seam
|
||||
|
||||
## Question
|
||||
|
||||
Define the dotfiles deployment seam for the new Pi subagent extension, including development placement, flake-managed promotion, configuration files, and verification commands needed before implementation starts.
|
||||
|
||||
## Result
|
||||
|
||||
The extension should be developed as a Pi extension under `modules/agents/pi/extensions/subagents/` and deployed by the existing Home Manager file link from `modules/agents/pi/pi.nix` to `~/.pi/agent/extensions`.
|
||||
Finished work must be promoted through the dotfiles module before it counts as deployed.
|
||||
Direct files under `~/.pi/agent/extensions` are acceptable only for throwaway development or local experiments.
|
||||
This matches the repository gotcha that flake-managed Pi extension, prompt, and skill directories may be written directly for experiments but durable deployment must go through the dotfiles module.
|
||||
Source: `/home/alexion/wrk/dotfiles/AGENTS.md`.
|
||||
|
||||
No install step should be part of the implementation plan without explicit user consent.
|
||||
The durable path should avoid `pi install`, npm package installation, or git package installation for version one.
|
||||
If runtime dependencies become unavoidable, the implementation spec must pause for consent and then model the dependency declaratively in Nix rather than asking Pi to install it interactively.
|
||||
Source: user constraint and Pi package security docs in `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/packages.md`.
|
||||
|
||||
## Current Pi deployment shape
|
||||
|
||||
`modules/agents/pi/pi.nix` enables `programs.pi-coding-agent` through Home Manager.
|
||||
It writes Pi settings with `defaultProvider`, `defaultModel`, `defaultThinkingLevel`, theme, and telemetry choices.
|
||||
It force-manages `~/.pi/agent/settings.json` but intentionally leaves login credential state unmanaged.
|
||||
Source: `modules/agents/pi/pi.nix`.
|
||||
|
||||
The same module recursively links `modules/agents/pi/extensions` to `~/.pi/agent/extensions`.
|
||||
It also recursively links `modules/agents/pi/prompts` to `~/.pi/agent/prompts`.
|
||||
Source: `modules/agents/pi/pi.nix`.
|
||||
|
||||
The current `modules/agents/pi/extensions` directory contains only `.gitkeep`.
|
||||
That means a new extension can be added there without colliding with existing Pi extension code.
|
||||
Source: `find modules/agents/pi -maxdepth 3 -type f` during this task.
|
||||
|
||||
Pi's extension docs say global extensions are auto-discovered from `~/.pi/agent/extensions/*.ts` and `~/.pi/agent/extensions/*/index.ts`.
|
||||
Project-local extensions are auto-discovered from `.pi/extensions/*.ts` and `.pi/extensions/*/index.ts` after project trust.
|
||||
Source: `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md`.
|
||||
|
||||
Pi can hot-reload auto-discovered extension locations with `/reload`.
|
||||
Source: `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md`.
|
||||
|
||||
## Proposed repository layout
|
||||
|
||||
Use this layout for version one:
|
||||
|
||||
```text
|
||||
modules/agents/pi/extensions/subagents/
|
||||
├── index.ts
|
||||
├── agents.ts
|
||||
├── config.ts
|
||||
├── runner.ts
|
||||
├── supervisor.ts
|
||||
├── status.ts
|
||||
├── types.ts
|
||||
└── ui.ts
|
||||
```
|
||||
|
||||
`index.ts` should be the extension entry point and should export the default Pi extension factory.
|
||||
`agents.ts` should load and validate named agent definitions.
|
||||
`config.ts` should resolve extension settings and default policy.
|
||||
`runner.ts` should implement the subprocess RPC `ChildRunner`.
|
||||
`supervisor.ts` should own child records, lifecycle, cancellation, timers, and concurrency.
|
||||
`status.ts` should define parent-session entries and renderable status data.
|
||||
`types.ts` should hold shared TypeScript types.
|
||||
`ui.ts` should isolate optional TUI/RPC status and confirmation helpers.
|
||||
|
||||
Keep filenames lowercase.
|
||||
This follows the user's global filename preference and the repository convention.
|
||||
Source: `/home/alexion/.pi/agent/AGENTS.md` and `/home/alexion/wrk/dotfiles/AGENTS.md`.
|
||||
|
||||
Do not add a `package.json` unless implementation discovers an unavoidable external runtime dependency.
|
||||
Pi extensions can import Pi-provided packages such as `@earendil-works/pi-coding-agent`, `@earendil-works/pi-ai`, `@earendil-works/pi-tui`, and `typebox` directly.
|
||||
Source: `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md`.
|
||||
|
||||
## Agent definition deployment seam
|
||||
|
||||
The extension should load user-level agent definitions from `~/.pi/agent/agents/` and project-level definitions from `.pi/agents/` after trust.
|
||||
Because the current dotfiles module does not link `modules/agents/pi/agents`, add this managed directory when real agent definitions are committed.
|
||||
The module should link it recursively to `~/.pi/agent/agents` in the same style as extensions and prompts.
|
||||
|
||||
Proposed durable layout:
|
||||
|
||||
```text
|
||||
modules/agents/pi/agents/
|
||||
└── .gitkeep
|
||||
```
|
||||
|
||||
Proposed Nix addition when needed:
|
||||
|
||||
```nix
|
||||
"${piDir}/agents" = {
|
||||
source = ./agents;
|
||||
recursive = true;
|
||||
};
|
||||
```
|
||||
|
||||
The initial extension should not ship opinionated agent definition files.
|
||||
The directory can contain `.gitkeep` only until the user intentionally adds named agents.
|
||||
This satisfies the constraint that named agents, prompts, and policy belong in Pi config rather than the neutral extension.
|
||||
|
||||
## Settings seam
|
||||
|
||||
Do not add extension-specific settings to `programs.pi-coding-agent.settings` until the implementation schema is finalized.
|
||||
When settings are needed, keep them under a clearly namespaced key such as `subagents` only if Pi preserves unknown settings for extension consumption.
|
||||
If Pi's typed settings reject unknown keys, store extension config in a separate user-level file such as `~/.pi/agent/subagents.json` and manage it through Home Manager `home.file`.
|
||||
The implementation spec must verify Pi's settings parser behavior before choosing this.
|
||||
|
||||
Recommended initial defaults should live in extension code and be neutral:
|
||||
|
||||
- Runtime: `subprocess-rpc`.
|
||||
- Max concurrent children: `2` or `3`.
|
||||
- Default context: unresolved by [[022-pi-subagents-context-modes-grill]].
|
||||
- Project agents: disabled until project trust is confirmed.
|
||||
- Project extension inheritance: disabled.
|
||||
- Nested children: disabled.
|
||||
- Tool policy: minimal and explicit.
|
||||
|
||||
Do not encode opinionated subagent types in settings.
|
||||
Do not add Herdr settings to the Pi extension seam.
|
||||
Herdr remains an optional later adapter and should not shape the core deployment.
|
||||
|
||||
## Development workflow
|
||||
|
||||
For quick experiments, it is acceptable to copy or create a throwaway extension directly under `~/.pi/agent/extensions/subagents/`.
|
||||
That is not durable and may be overwritten or hidden by Home Manager activation.
|
||||
Source: `/home/alexion/wrk/dotfiles/AGENTS.md` gotcha about flake-managed Pi directories.
|
||||
|
||||
For implementation work that should persist, edit `modules/agents/pi/extensions/subagents/` in the repository.
|
||||
Then reload Pi or rebuild Home Manager depending on whether the current session sees the repository path through the existing symlink.
|
||||
Because `modules/agents/pi/pi.nix` recursively links the entire `extensions` directory, editing the source tree should normally be enough for `/reload` in the running Pi session to see the change.
|
||||
A rebuild is required to verify clean-machine deployment.
|
||||
|
||||
Use `pi -e ./path.ts` only for quick tests of an isolated file.
|
||||
The Pi docs identify `-e` as a quick-test path and say auto-discovered global or project locations are the right placement for `/reload`.
|
||||
Source: `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md`.
|
||||
|
||||
## Verification commands
|
||||
|
||||
Use these checks before implementation starts:
|
||||
|
||||
```bash
|
||||
nix eval .#nixosConfigurations.neogaia.config.modules.agents.pi.enable
|
||||
```
|
||||
|
||||
Expected result: `true`.
|
||||
This verifies the Pi module is enabled for the current host.
|
||||
|
||||
```bash
|
||||
nix eval .#nixosConfigurations.neogaia.config.home-manager.users.alexion.home.file.'"/home/alexion/.pi/agent/extensions"'.source
|
||||
```
|
||||
|
||||
Expected result: a Nix store path sourced from `modules/agents/pi/extensions` after evaluation.
|
||||
This verifies the deployment link remains declared.
|
||||
|
||||
```bash
|
||||
nix eval .#nixosConfigurations.neogaia.config.home-manager.users.alexion.home.file.'"/home/alexion/.pi/agent/prompts"'.source
|
||||
```
|
||||
|
||||
Expected result: a Nix store path sourced from `modules/agents/pi/prompts`.
|
||||
This is a control check matching the existing prompt link.
|
||||
|
||||
After adding `modules/agents/pi/agents`, add and run this check:
|
||||
|
||||
```bash
|
||||
nix eval .#nixosConfigurations.neogaia.config.home-manager.users.alexion.home.file.'"/home/alexion/.pi/agent/agents"'.source
|
||||
```
|
||||
|
||||
Expected result: a Nix store path sourced from `modules/agents/pi/agents`.
|
||||
|
||||
Use the repository's primary verification seam before merging implementation:
|
||||
|
||||
```bash
|
||||
nix flake check
|
||||
```
|
||||
|
||||
The project gotcha says `nix flake check` builds `checks.x86_64-linux.<host>` and is the primary build/verify seam for any host.
|
||||
Source: `/home/alexion/wrk/dotfiles/AGENTS.md`.
|
||||
|
||||
For cheap targeted evaluation during implementation, use `nix eval .#nixosConfigurations.neogaia.config...` rather than committing speculative host enablement.
|
||||
Source: `/home/alexion/wrk/dotfiles/AGENTS.md`.
|
||||
|
||||
## Runtime verification after implementation
|
||||
|
||||
Use these manual checks after the extension exists:
|
||||
|
||||
```bash
|
||||
pi --mode rpc --no-session
|
||||
```
|
||||
|
||||
Then send a minimal JSONL prompt and confirm the process speaks RPC.
|
||||
This verifies the child runtime target independently of the extension.
|
||||
Source: Pi RPC docs in `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/rpc.md`.
|
||||
|
||||
Inside Pi, run `/reload` after editing the managed extension source and confirm the extension reloads without restarting Pi.
|
||||
This verifies the global extension discovery path.
|
||||
Source: Pi extension docs in `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md`.
|
||||
|
||||
After adding a status renderer, spawn a trivial read-only child and verify these properties:
|
||||
|
||||
- Parent transcript receives a compact status entry.
|
||||
- Child transcript or session remains separate.
|
||||
- Cancelling the parent tool call cancels the child.
|
||||
- The child exits or is killed on timeout.
|
||||
- No project-local agent definition loads before project trust.
|
||||
- No Herdr-specific behavior is required.
|
||||
|
||||
## Files to change during implementation
|
||||
|
||||
Expected durable changes:
|
||||
|
||||
- `modules/agents/pi/extensions/subagents/index.ts`.
|
||||
- `modules/agents/pi/extensions/subagents/*.ts` helper files.
|
||||
- `modules/agents/pi/agents/.gitkeep` if the managed user-agent directory is introduced.
|
||||
- `modules/agents/pi/pi.nix` only if the agents directory or extension config file is linked.
|
||||
|
||||
Avoid these changes unless explicitly justified:
|
||||
|
||||
- Do not edit `~/.pi/agent` directly for durable deployment.
|
||||
- Do not modify generated Home Manager output.
|
||||
- Do not install Pi packages with `pi install`.
|
||||
- Do not add Herdr-specific config to the Pi module for version one.
|
||||
- Do not add named opinionated subagents to the neutral extension.
|
||||
|
||||
## Open implementation questions
|
||||
|
||||
The implementation spec still needs decisions from [[021-pi-subagents-config-boundary-grill]] and [[022-pi-subagents-context-modes-grill]].
|
||||
The status UI details still depend on [[023-pi-subagents-status-ui-prototype]].
|
||||
This deployment seam is therefore ready for implementation planning but not by itself sufficient to start coding the extension.
|
||||
Reference in New Issue
Block a user