@pi-unipi/unipi 0.1.1

package/packages/btw/skills/btw/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: btw
+description: Helps you use the /btw side-conversation workflow effectively. Use when you want to think in parallel, ask side questions without interrupting ongoing work, or inject a side thread back into the main agent.
+---
+
+# BTW
+
+Use this skill when the user wants to work in parallel with the main agent instead of derailing the current turn.
+
+## When to use BTW
+
+Prefer the BTW workflow when the user wants to:
+
+- ask a side question while the main agent keeps working
+- brainstorm or compare options without interrupting the current run
+- prepare a plan or summary before handing it back to the main agent
+- keep exploratory discussion out of the main transcript/context
+
+## Commands
+
+Use these commands in your guidance to the user:
+
+```text
+/btw <question>
+/btw --save <question>
+/btw:new [question]
+/btw:tangent <question>
+/btw:tangent --save <question>
+/btw:clear
+/btw:inject [instructions]
+/btw:summarize [instructions]
+```
+
+## How to guide the user
+
+### For a quick side question
+
+Recommend:
+
+```text
+/btw <question>
+```
+
+Use this when the user wants an immediate aside and does not need a visible saved note.
+
+### For a saved one-off note
+
+Recommend:
+
+```text
+/btw --save <question>
+```
+
+Use this when the user wants the exchange to appear as a visible BTW note in the session transcript.
+
+### For a fresh side thread
+
+Recommend:
+
+```text
+/btw:new
+```
+
+or
+
+```text
+/btw:new <question>
+```
+
+Use this when the previous BTW discussion is no longer relevant, but you still want the new side thread to inherit the current main-session context.
+
+### For a contextless tangent thread
+
+Recommend:
+
+```text
+/btw:tangent <question>
+```
+
+or
+
+```text
+/btw:tangent --save <question>
+```
+
+Use this when the user wants a side conversation that does not include the current main-session context.
+
+### To hand the full thread back to the main agent
+
+Recommend:
+
+```text
+/btw:inject <instructions>
+```
+
+Use this when the exact discussion matters and the user wants the main agent to act on it.
+
+### To hand back a condensed version
+
+Recommend:
+
+```text
+/btw:summarize <instructions>
+```
+
+Use this when the thread is long and only the distilled outcome should go back into the main agent.
+
+## Recommendation rules
+
+- Prefer `/btw` over normal chat when the user explicitly wants a side conversation.
+- Prefer `/btw:tangent` when the user wants that side conversation to be contextless.
+- Prefer `/btw:summarize` over `/btw:inject` for long exploratory threads.
+- Prefer `/btw:inject` when precise wording, detailed tradeoffs, or a full plan matters.
+- Suggest `/btw:new` before starting a totally unrelated side topic when main-session context is still useful.
+- Suggest `/btw:clear` when the widget/thread should be dismissed.
+
+## Response style
+
+When helping the user use BTW:
+
+- give the exact slash command to run
+- explain briefly why that command fits
+- keep the guidance short and operational
+
+## Examples
+
+### Example: brainstorm while coding continues
+
+```text
+/btw what are the risks of switching this to optimistic updates?
+```
+
+### Example: create a clean new thread
+
+```text
+/btw:new sketch a safer migration plan
+```
+
+### Example: start a contextless tangent
+
+```text
+/btw:tangent think through this from first principles without using the current chat context
+```
+
+### Example: send the result back
+
+```text
+/btw:summarize implement the recommended migration plan
+```

package/packages/core/README.md

@@ -0,0 +1,74 @@
+# @pi-unipi/core
+
+Shared utilities, event types, and constants for the [Unipi](https://github.com/Neuron-Mr-White/unipi) extension suite.
+
+## Install
+
+```bash
+pi install npm:@pi-unipi/core
+```
+
+Or as part of the full suite:
+```bash
+pi install npm:unipi
+```
+
+## Usage
+
+```typescript
+import { UNIPI_EVENTS, MODULES, sanitize, emitEvent } from "@pi-unipi/core";
+
+// Emit module ready event
+emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
+  name: MODULES.WORKFLOW,
+  version: "1.0.0",
+  commands: ["brainstorm", "plan"],
+  tools: [],
+});
+
+// Use shared utilities
+const safeName = sanitize("my/feature: branch");
+```
+
+## Exports
+
+### Constants
+- `UNIPI_PREFIX` — Command prefix (`unipi:`)
+- `MODULES` — All module names
+- `WORKFLOW_COMMANDS` — Workflow command names
+- `RALPH_COMMANDS` — Ralph command names
+- `RALPH_TOOLS` — Ralph tool names
+- `RALPH_DEFAULTS` — Default ralph settings
+- `RALPH_DIR` — Ralph state directory
+- `RALPH_COMPLETE_MARKER` — Loop completion marker
+
+### Events
+- `UNIPI_EVENTS` — Event names
+- `UnipiModuleEvent` — Module ready/gone payload
+- `UnipiWorkflowEvent` — Workflow start/end payload
+- `UnipiRalphLoopEvent` — Ralph loop start/end payload
+- `UnipiRalphIterationEvent` — Ralph iteration payload
+- `UnipiStatusRequestEvent` / `UnipiStatusResponseEvent` — Status payloads
+
+### Utilities
+- `sanitize(name)` — Sanitize string for filenames
+- `ensureDir(path)` — Create parent directories
+- `tryDelete(path)` — Safe file deletion
+- `tryRead(path)` — Safe file read
+- `safeMtimeMs(path)` — File modification time
+- `tryRemoveDir(path)` — Safe directory removal
+- `resolvePath(cwd, path)` — Resolve relative/absolute paths
+- `fileExists(path)` — Check file existence
+- `writeFile(path, content)` — Write file with dir creation
+- `readJson<T>(path)` — Read JSON file
+- `writeJson(path, data)` — Write JSON file
+- `randomId(length)` — Generate random ID
+- `now()` — ISO timestamp
+- `parseArgs(str)` — Parse quoted arguments
+- `getPackageVersion(dir)` — Read package version
+- `isModuleAvailable(cwd, name)` — Check if npm module exists
+- `emitEvent(pi, name, payload)` — Safe event emission
+
+## License
+
+MIT

package/packages/core/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @unipi/core — Shared utilities for Unipi extension suite
+ *
+ * Re-exports all constants, events, and utilities.
+ */
+
+export * from "./constants.js";
+export * from "./events.js";
+export * from "./sandbox.js";
+export * from "./utils.js";

package/packages/info-screen/README.md

@@ -0,0 +1,115 @@
+# @pi-unipi/info-screen
+
+Dashboard and module registry for [Unipi](https://github.com/Neuron-Mr-White/unipi). Shows a configurable info overlay on boot with tabbed groups from all registered modules.
+
+## Install
+
+```bash
+pi install npm:@pi-unipi/info-screen
+```
+
+Or as part of the full suite:
+```bash
+pi install npm:unipi
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/unipi:info` | Show info screen dashboard |
+| `/unipi:info-settings` | Configure info display (groups, stats, visibility) |
+
+## Features
+
+- **Module discovery** — listens for `MODULE_READY` events, tracks all registered modules
+- **Tabbed groups** — each module registers info groups with custom data providers
+- **Configurable** — per-group and per-stat visibility via settings
+- **Boot overlay** — shows dashboard on session start (configurable)
+- **Styled dialog chrome** — uses pi-tui theme API for consistent borders, scrollable content, and navigation hints (matching the overlay style used by @pi-unipi/btw)
+- **Core groups** — modules, tools, load time, session info out of the box
+
+## Registering a Group
+
+Other modules register info groups via the global registry:
+
+```typescript
+import { infoRegistry } from "@pi-unipi/info-screen";
+
+infoRegistry.registerGroup({
+  id: "my-module",
+  name: "My Module",
+  icon: "📦",
+  priority: 60,
+  config: {
+    showByDefault: true,
+    stats: [
+      { id: "status", label: "Status", show: true },
+      { id: "count", label: "Count", show: true },
+    ],
+  },
+  dataProvider: async () => ({
+    status: { value: "running" },
+    count: { value: "42", detail: "items processed" },
+  }),
+});
+```
+
+## API
+
+### `infoRegistry`
+
+Singleton registry instance. Also available globally via `globalThis.__unipi_info_registry`.
+
+| Method | Description |
+|--------|-------------|
+| `registerGroup(group)` | Register an info group |
+| `unregisterGroup(id)` | Remove a group |
+| `getGroups()` | Get visible groups (sorted by priority) |
+| `getAllGroups()` | Get all groups (including hidden) |
+| `getGroupData(id)` | Get data for a group (cached) |
+| `updateGroupData(id, data)` | Manually update group data |
+| `getVisibleStats(id)` | Get enabled stats for a group |
+| `invalidateCache(id)` | Invalidate cached data |
+
+### Load Tracking
+
+```typescript
+import { startLoadTracking, recordLoadTime, finishLoadTracking, recordModuleStart } from "@pi-unipi/info-screen";
+
+// Track module load times
+startLoadTracking();
+recordModuleStart("@pi-unipi/memory");
+// ... module loads ...
+recordLoadTime("@pi-unipi/memory", "module", 150);
+finishLoadTracking();
+```
+
+## Settings
+
+Configure in pi `settings.json`:
+
+```json
+{
+  "unipi": {
+    "infoScreen": {
+      "showOnBoot": true,
+      "bootTimeoutMs": 8000,
+      "groups": {
+        "modules": { "show": true },
+        "ralph": { "show": true },
+        "memory": { "show": false }
+      },
+      "groupOrder": ["modules", "ralph", "subagents"]
+    }
+  }
+}
+```
+
+## Dependencies
+
+- `@pi-unipi/core` — shared constants and events
+
+## License
+
+MIT

package/packages/info-screen/index.ts

@@ -0,0 +1,165 @@
+/**
+ * @pi-unipi/info-screen — Extension entry
+ *
+ * Cache-first reactive dashboard.
+ * Opens immediately with cached data, updates in background.
+ *
+ * Usage:
+ *   /unipi:info          - Show info dashboard
+ *   /unipi:info-settings - Configure info display
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { UNIPI_EVENTS, MODULES, UNIPI_PREFIX, emitEvent, getPackageVersion } from "@pi-unipi/core";
+import { infoRegistry } from "./registry.js";
+import { registerCoreGroups, trackModule, trackTool, setPiApi, registerSkillDir, startLoadTracking, recordLoadTime, finishLoadTracking, recordModuleStart } from "./core-groups.js";
+
+/** Re-export for external use */
+export { infoRegistry, registerSkillDir, startLoadTracking, recordLoadTime, finishLoadTracking, recordModuleStart };
+import { getInfoSettings } from "./config.js";
+import { InfoOverlay } from "./tui/info-overlay.js";
+import { SettingsOverlay } from "./settings/settings-tui.js";
+
+/** Package version */
+const VERSION = getPackageVersion(new URL(".", import.meta.url).pathname);
+
+export default function (pi: ExtensionAPI) {
+  setPiApi(pi);
+
+  // Register core groups immediately (synchronous)
+  registerCoreGroups();
+
+  // Start load tracking
+  startLoadTracking();
+
+  // Listen for module announcements — track and trigger reactive updates
+  pi.events.on(UNIPI_EVENTS.MODULE_READY, (event: any) => {
+    if (event.name && event.name !== MODULES.INFO_SCREEN) {
+      trackModule(event.name, event.version || "unknown");
+      recordLoadTime(event.name, "module", event.loadTimeMs);
+
+      // Invalidate overview so next fetch picks up new module list
+      infoRegistry.invalidateCache("overview");
+
+      // Trigger background refresh of overview — subscribers will re-render
+      infoRegistry.getGroupData("overview");
+
+      if (event.tools && Array.isArray(event.tools)) {
+        for (const tool of event.tools) {
+          trackTool(tool, event.name);
+        }
+        // Refresh tools group too
+        infoRegistry.invalidateCache("tools");
+        infoRegistry.getGroupData("tools");
+      }
+    }
+  });
+
+  pi.events.on(UNIPI_EVENTS.INFO_GROUP_REGISTERED, (_event: any) => {
+    // Group already registered via globalThis in registerGroup()
+  });
+
+  // Track built-in tools
+  const trackedBuiltinTools = new Set<string>();
+  pi.on("tool_call", async (event, _ctx) => {
+    const toolName = event.toolName;
+    if (!trackedBuiltinTools.has(toolName)) {
+      trackedBuiltinTools.add(toolName);
+      trackTool(toolName, "builtin");
+    }
+    return undefined;
+  });
+
+  /**
+   * Show the info overlay immediately.
+   * Cache-first: opens with whatever data is cached (even empty).
+   * Background: each group fetches independently, overlay re-renders reactively.
+   */
+  function showOverlay(ctx: any): void {
+    ctx.ui.custom(
+      (tui: any, theme: any, _keybindings: any, done: () => void) => {
+        const overlay = new InfoOverlay();
+        overlay.setTheme(theme);
+        overlay.onClose = () => {
+          overlay.destroy();
+          done();
+        };
+        overlay.requestRender = () => tui.requestRender();
+        return {
+          render: (w: number) => overlay.render(w),
+          invalidate: () => overlay.invalidate(),
+          handleInput: (data: string) => {
+            overlay.handleInput(data);
+            tui.requestRender();
+          },
+        };
+      },
+      {
+        overlay: true,
+        overlayOptions: {
+          width: "80%",
+          minWidth: 60,
+          anchor: "center",
+          margin: 2,
+        },
+      }
+    );
+  }
+
+  // Session lifecycle — show immediately on boot, no blocking wait
+  pi.on("session_start", async (event, ctx) => {
+    const settings = getInfoSettings();
+
+    if (settings.showOnBoot && event.reason === "startup") {
+      // Open immediately — cache-first, no waiting
+      showOverlay(ctx);
+    }
+
+    finishLoadTracking();
+
+    emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
+      name: MODULES.INFO_SCREEN,
+      version: VERSION,
+      commands: ["unipi:info", "unipi:info-settings"],
+      tools: [],
+    });
+  });
+
+  // /unipi:info — open immediately
+  pi.registerCommand(`${UNIPI_PREFIX}info`, {
+    description: "Show info screen dashboard",
+    handler: async (_args, ctx) => {
+      showOverlay(ctx);
+    },
+  });
+
+  // /unipi:info-settings
+  pi.registerCommand(`${UNIPI_PREFIX}info-settings`, {
+    description: "Configure info screen display",
+    handler: async (_args, ctx) => {
+      ctx.ui.custom(
+        (tui: any, _theme: any, _keybindings: any, done: any) => {
+          const overlay = new SettingsOverlay();
+          overlay.onClose = () => done(undefined);
+          return {
+            render: (w: number) => overlay.render(w),
+            invalidate: () => overlay.invalidate(),
+            handleInput: (data: string) => {
+              overlay.handleInput?.(data);
+              tui.requestRender();
+            },
+          };
+        },
+        {
+          overlay: true,
+          overlayOptions: {
+            width: "60%",
+            minWidth: 50,
+            anchor: "center",
+            margin: 2,
+          },
+        }
+      );
+    },
+  });
+}

package/packages/memory/README.md

@@ -0,0 +1,94 @@
+# @pi-unipi/memory
+
+Persistent cross-session memory with vector search for Pi coding agent.
+
+## Features
+
+- **Two-tier storage:** SQLite + sqlite-vec for vector search, markdown files for human-readable memory
+- **Project-scoped + global memory:** Each project gets its own DB, global memories accessible cross-project
+- **Hybrid search:** Vector similarity + fuzzy text matching for best recall
+- **Session injection:** Agent sees memory titles at session start
+- **Auto-consolidation:** Memories extracted during compaction
+- **Update-first:** Prevents memory duplication
+
+## Installation
+
+```bash
+# All-in-one (includes memory)
+pi install npm:unipi
+
+# Standalone
+pi install npm:@pi-unipi/memory
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `memory_store` | Store/update memory (project scope) |
+| `memory_search` | Search memories (project scope) |
+| `memory_delete` | Delete memory by ID or title |
+| `memory_list` | List all project memories |
+| `global_memory_store` | Store/update memory (global scope) |
+| `global_memory_search` | Search global memories |
+| `global_memory_list` | List all global memories |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/unipi:memory-process <text>` | Analyze text and store extracted memories |
+| `/unipi:memory-search <term>` | Search project memories |
+| `/unipi:memory-consolidate` | Consolidate session into memory |
+| `/unipi:memory-forget <title>` | Delete a memory by title |
+| `/unipi:global-memory-process <text>` | Analyze text and store to global |
+| `/unipi:global-memory-search <term>` | Search global memories |
+| `/unipi:global-memory-list` | List all global memories |
+
+## Memory File Format
+
+Memories are stored as markdown with YAML frontmatter:
+
+```markdown
+---
+title: auth_jwt_prefer_refresh_tokens
+tags: [auth, jwt, preferences]
+project: my-app
+created: 2026-04-26T10:00:00Z
+updated: 2026-04-26T15:30:00Z
+type: preference
+---
+
+# Auth: Prefer Refresh Tokens
+
+User prefers short-lived access tokens (15min) with long-lived refresh tokens (30d).
+Always implement token rotation on refresh.
+```
+
+## Naming Convention
+
+**Format:** `<most_important>_<less_important>_<lesser>`
+
+Examples:
+- `auth_jwt_prefer_refresh_tokens`
+- `db_postgres_use_connection_pooling`
+- `style_typescript_strict_mode_always`
+
+## Storage Layout
+
+```
+~/.unipi/memory/
+├── global/
+│   ├── memory.db              # Global vector DB
+│   └── *.md                   # Global memory files
+└── <project_name>/
+    ├── memory.db              # Project vector DB
+    └── *.md                   # Project memory files
+```
+
+## Dependencies
+
+- `better-sqlite3` - SQLite database
+- `sqlite-vec` - Vector search extension
+- `js-yaml` - YAML frontmatter parsing
+- `@pi-unipi/core` - Shared utilities