scriptoriumadmin/openpetswithchatandmcp
1
0
Fork 0
Code Issues Pull requests 6 Projects Releases Packages Wiki Activity Actions
openpetswithchatandmcp/packages/pi/codemap.md
OpenPets Dev 6ab3bb64d8 feat(rebrand): rename OpenPets to FamiliarOS and pets to familiars 
- Rename all user-facing and technical identifiers from OpenPets/Pet to FamiliarOS/Familiar.
- Rename packages from @open-pets/* to @familiaros/*; rename install-pet/pet-format packages.
- Rename plugin IDs and directories from openpets.* to familiaros.*.
- Rename IPC namespace from openpets:* to familiaros:* and state filenames from openpets-* to familiaros-* with legacy migration.
- Rename source files (pet-window, built-in-pet, default-pet-controller, etc.) to familiar equivalents.
- Update locales (en, es-419, ja, ko, pt-BR, zh-Hans, zh-Hant) and tray/pet context menu strings.
- Add Familiar naming feature: preference, settings input, tray menu display.
- Update assets and packaging config; all desktop tests pass.
2026-06-17 01:42:08 +00:00

2.7 KiB
Raw Permalink Blame History

packages/pi/

Publishable npm package for the FamiliarOS Pi coding-agent integration.

Responsibility

  • Exposes @familiaros/pi as a Pi package with a Pi extension resource.
  • Maps Pi session/tool activity to safe FamiliarOS reactions through @familiaros/client.
  • Registers a user slash command namespace, /familiaros, for status, test, react, and say commands.
  • Keeps MVP behavior default-familiar-only and non-blocking; no Pi model-callable tools are registered.

Design/Patterns

  • Package structure: Standard npm package with main/types pointing to dist/index.js, Pi extension declared in pi.extensions array.
  • Dual exports: Main package exports (index.ts) and dedicated extension entry (extension.ts) for Pi loader consumption.
  • Peer dependency: Declares optional peer dependency on @earendil-works/pi-coding-agent for type safety without hard coupling.
  • Fire-and-forget scheduling: All automatic event handlers use non-blocking scheduling with swallowed IPC failures to prevent Pi execution disruption.
  • Privacy-first: Prompt text, assistant text, tool output, command output, file paths, URLs, and secrets are never forwarded to FamiliarOS.

Flow

Pi extension loader
  -> packages/pi/src/extension.ts
  -> packages/pi/src/runtime.ts
  -> @familiaros/client
  -> FamiliarOS desktop local IPC

Automatic event flow:

  1. Pi emits lifecycle events (session_start, agent_start, turn_start, etc.)
  2. extension.ts receives event via api.on() and wraps in PiEventEnvelope
  3. runtime.ts classifies event to determine appropriate reaction
  4. Reaction dispatched to FamiliarOS client via scheduled non-blocking call
  5. IPC failures logged (if debug enabled) but never thrown to Pi

Command flow:

  1. User types /familiaros <command> in Pi
  2. registerCommand() handler invoked with args string
  3. parseFamiliarOSCommand() validates and structures command
  4. executeCommand() performs synchronous FamiliarOS client calls
  5. UI notifications sent via ctx.ui.notify()

Integration

  • Upstream: Consumes @familiaros/agent-events for speech validation and @familiaros/client for IPC.
  • Downstream: Pi coding agent loads extension via pi.extensions manifest entry.
  • Desktop: Communicates with FamiliarOS desktop app through local socket IPC (via @familiaros/client).
  • Commands: /familiaros status, /familiaros test, /familiaros react <reaction>, /familiaros say <message>.

Safety notes

  • Automatic events use reactions and fixed message pools only.
  • Prompt text, assistant text, tool output, command output, file paths, URLs, and secrets are not forwarded.
  • FamiliarOS IPC failures are swallowed by automatic event handlers so Pi execution continues.