pi-jarvis: Instructions file for Codex

pi-jarvis Agent Notes

Project Scope

• pi-jarvis is a Pi extension that opens a /jarvis side-conversation overlay.
• Core runtime files: index.ts, side-session.ts, native-mcp.ts, overlay.ts, overlay-layout.ts, draft-editor.ts, transcript-viewport.ts, jarvis-branding.ts, model-picker.ts, jarvis-config.ts, session-ref.ts, memory-{types,config,content,store,service,extension,editor-types,editor,editor-controller}.ts, and archive-{types,config,store,service,extension,import,crypto,sqlite,keychain,unlock,secret-input,vault-files,vault,migration}.ts.
• Current baseline: Pi 1.0.0 (@earendil-works packages), Node.js >=22.19.0. Older Pi hosts are not supported.

Current /jarvis-model and /jarvis-thinking Behavior

• /jarvis requires ctx.mode === "tui"; other modes must not boot or prompt a hidden side session.
• /jarvis-model with no request opens a searchable host-registry model picker in TUI mode; other modes report status.
• /jarvis-model <provider/model> writes a project-scoped override to .pi/jarvis.json.
• /jarvis-model --global <provider/model> writes the default global override to the active Pi agent directory's extensions/pi-jarvis.json (by default ~/.pi/agent/extensions/pi-jarvis.json).
• /jarvis-model [--project|--global] follow-main stores a scoped follow-main override.
• /jarvis-model [--project|--global] clear removes that scope's override so fallback applies.
• /jarvis-thinking [--project|--global] auto|follow-main|off|minimal|low|medium|high|xhigh|max stores a scoped thinking override without changing the main session thinking level.
• /jarvis-thinking [--project|--global] clear removes that scope's thinking override so fallback applies.
• Resolution order is: project config, then global config, then built-in defaults (follow-main for model, auto for thinking). Global writes never override an active project setting.
• Config writes use atomic same-directory replacement. Malformed shared JSON requires manual repair: model/thinking set/clear must never replace/delete it and reset unknown memory privacy controls. Keep I/O errors distinct and parser input snippets out of UI errors. Legacy model/thinking cross-process writes remain unlocked.
• auto thinking follows main only when /jarvis follows the main model; pinned /jarvis models default to thinking off.
• follow-main thinking follows the main thinking level regardless of model selection, except xAI /jarvis models force thinking off.
• /compact, /tree, and /new entered inside /jarvis operate on the isolated /jarvis side-session, not the main Pi session.
• Note main and Redirect stay disabled when the active /jarvis model is incompatible with bridge tools.
• Published packages keep Pi runtime packages as optional peers, not bundled dependencies. Never load the legacy MCP adapter. Version 1.6.0 adds native MCP to Repo tools opt-in alongside read/bash/edit/write.
• Physical models delegate to the host's public registry for auth and dispatch. Virtual/router models explicitly reject; do not access the registry's private backing runtime.
• Side resources/settings honor ctx.isProjectTrusted(). Local tool execution and bridge delivery recheck live permissions. Ordinary overlay close hides presentation without stopping assigned work or clearing its three grants; cancel pending confirmations and refuse new invisible reviews. Grants are in-memory, scoped to the current main/side owner, not saved across restart/reload. Explicit access-off, observed trust denial, side /new, reference/main replacement and teardown revoke them. Archive private-input preparation explicitly revokes transient grants before closing/yielding.
• Use agent_settled, not agent_end, for final idle state. Main context must honor Pi context-edit/compaction projection.
• Runtime disposal must not detach the overlay's bridge subscription. Queue ownership must survive side /new but not main-session replacement; failed/uncertain sends are not auto-retried.