@dex-ai/pi-compat 0.1.2

package/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22.x"
+          registry-url: "https://registry.npmjs.org"
+
+      - run: bun install
+
+      - name: Create Release Pull Request or Publish
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          publish: bun run release
+          version: bun run version
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_CONFIG_PROVENANCE: true
+

package/README.md

@@ -0,0 +1,142 @@
+# @dex-ai/pi-compat
+
+Pi extension compatibility layer — load and run [pi-coding-agent](https://github.com/nicobailon/pi-coding-agent) extensions inside Dex.
+
+## What This Does
+
+Pi has a mature extension ecosystem with powerful tools like:
+- **pi-lens** — LSP + AST-grep code intelligence
+- **pi-subagents** — Multi-agent delegation
+- **pi-mcp-adapter** — MCP server integration
+- **pi-intercom** — Inter-session communication
+- **@samfp/pi-memory** — Persistent memory with consolidation
+
+This package lets you use those extensions in Dex without rewriting them. It creates a shim `ExtensionAPI` that captures Pi's imperative registrations (tools, event handlers, skills) and maps them to Dex's declarative Extension interface.
+
+## Usage
+
+```typescript
+import { piCompatExtension } from '@dex-ai/pi-compat';
+import { Agent } from '@dex-ai/sdk';
+
+const agent = await Agent.create({
+  extensions: [
+    // Load pi-lens (globally installed)
+    await piCompatExtension({ packages: ['pi-lens'] }),
+
+    // Load multiple Pi extensions at once
+    await piCompatExtension({
+      packages: ['pi-lens', '@samfp/pi-memory'],
+      flags: { 'lens-lsp': true },
+    }),
+
+    // Load from a path
+    await piCompatExtension({
+      paths: ['~/.pi/agent/extensions/my-extension'],
+    }),
+  ],
+});
+```
+
+## How It Works
+
+```
+┌─────────────────────┐     ┌─────────────────────┐     ┌──────────────────┐
+│   Pi Extension      │     │   pi-compat shim     │     │   Dex Extension  │
+│                     │     │                      │     │                  │
+│ pi.registerTool()   │────▶│ captures → converts  │────▶│ ext.tools[]      │
+│ pi.on("event")      │────▶│ maps event names     │────▶│ ext.on.{event}   │
+│ pi.exec()           │────▶│ child_process.spawn  │     │ (functional)     │
+│ pi.registerFlag()   │────▶│ flag → env/config    │────▶│ ext.config       │
+│ skills/ directory   │────▶│ loads SKILL.md files  │────▶│ ext.skills[]     │
+│                     │     │                      │     │                  │
+│ pi.registerShortcut │────▶│ (no-op)              │     │                  │
+│ ctx.ui.*            │────▶│ (no-op stubs)        │     │                  │
+│ pi.registerProvider │────▶│ (no-op)              │     │                  │
+└─────────────────────┘     └─────────────────────┘     └──────────────────┘
+```
+
+## Architecture Translation
+
+| Pi Concept | Dex Equivalent | Status |
+|---|---|---|
+| `pi.registerTool({ name, parameters: Type.Object(...), execute })` | `ext.tools: [{ name, parameters: z.object(...), execute }]` | ✅ Mapped (TypeBox → Zod) |
+| `pi.on("session_start", handler)` | `ext.on: { 'session-start': handler }` | ✅ Mapped |
+| `pi.on("tool_call", handler)` | `ext.on: { 'tool-start': handler }` | ✅ Mapped |
+| `pi.on("tool_result", handler)` | `ext.on: { 'tool-stop': handler }` | ✅ Mapped |
+| `pi.on("agent_end", handler)` | `ext.on: { 'generate-stop': handler }` | ✅ Mapped |
+| `pi.on("turn_start/end")` | `ext.on: { 'model-start/stop' }` | ✅ Mapped |
+| `pi.exec(cmd, args)` | `child_process.spawn()` | ✅ Functional |
+| `pi.registerFlag(name, opts)` | `opts.flags` on piCompatExtension | ✅ Via options |
+| Skills (`package.json "pi".skills`) | `ext.skills[]` (loaded from SKILL.md) | ✅ Loaded |
+| `pi.registerCommand()` | (captured, not exposed) | ⚠️ Captured only |
+| `pi.registerShortcut()` | — | ❌ No-op |
+| `pi.registerProvider()` | — | ❌ No-op |
+| `pi.sendMessage()` | — | ❌ No-op |
+| `ctx.ui.*` | — | ❌ No-op stubs |
+
+## Event Mapping
+
+| Pi Event | Dex Event | Notes |
+|---|---|---|
+| `session_start` | `session-start` | Fires on agent init |
+| `session_shutdown` | `session-stop` | Fires on agent dispose |
+| `before_agent_start` | `generate-start` | Before each generate() |
+| `agent_end` | `generate-stop` | After each generate() |
+| `turn_start` | `model-start` | Before each LLM call |
+| `turn_end` | `model-stop` | After each LLM call |
+| `tool_call` | `tool-start` | Before tool execution (can block) |
+| `tool_result` | `tool-stop` | After tool execution (can modify) |
+| `context` | `generate-input` | Context injection |
+
+## Prerequisites
+
+Pi extensions must be installed globally (or locally) with their dependencies:
+
+```bash
+# Install pi extensions
+npm install -g pi-lens @samfp/pi-memory pi-subagents
+
+# The pi-coding-agent core package must also be installed
+# (pi extensions peer-depend on it for types)
+npm install -g @earendil-works/pi-coding-agent
+```
+
+## Configuration via Flags
+
+Pi extensions use `registerFlag()` / `getFlag()` for configuration. Pass flag values via the `flags` option:
+
+```typescript
+await piCompatExtension({
+  packages: ['pi-lens'],
+  flags: {
+    'lens-lsp': true,        // Enable LSP features
+    'lens-guard': true,      // Enable git guard
+    'lens-verbose': false,   // Disable verbose logging
+  },
+});
+```
+
+## Limitations
+
+1. **No UI** — Pi's rich TUI features (overlays, widgets, custom footer) are no-ops. Extensions that are purely UI-focused (pi-powerline-footer) won't provide value.
+
+2. **Event fidelity** — Some Pi events have no direct Dex equivalent. Extensions relying heavily on `message_start/update/end`, `before_provider_request`, or `input` events will have those handlers silently ignored.
+
+3. **TypeBox → Zod** — Schema conversion is best-effort. Complex TypeBox features (discriminated unions with `$ref`, conditional schemas) may fall back to `z.any()`.
+
+4. **No message injection** — Pi's `sendMessage()` / `sendUserMessage()` for steering mid-generation isn't mapped. Extensions that inject messages won't function for that capability.
+
+5. **Single provider** — Pi's `registerProvider()` is a no-op. Extensions that add custom providers won't contribute models.
+
+## Development
+
+```bash
+bun install
+bun run typecheck
+bun test
+```
+
+## License
+
+MIT

package/bun.lock

@@ -0,0 +1,38 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@dex-ai/pi-compat",
+      "dependencies": {
+        "jiti": "^2.7.0",
+        "typebox": "^1.1.24",
+        "zod": "^3.24.4",
+      },
+      "devDependencies": {
+        "@dex-ai/sdk": "file:../dex-ai-sdk",
+        "@types/bun": "^1.0.0",
+        "typescript": "^5.6.3",
+      },
+    },
+  },
+  "packages": {
+    "@dex-ai/sdk": ["@dex-ai/sdk@file:../dex-ai-sdk", { "devDependencies": { "@types/bun": "latest", "bun-types": "^1.3.14", "typescript": "^5.6.3" } }],
+
+    "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
+
+    "@types/node": ["@types/node@25.8.0", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-TCFSk8IZh+iLX1xtksoBVtdmgL+1IX0fC9BeU4QqFSuNdN/K+HUlhqOzEmSYYpZUVsLYcPqc9KX+60iDuninSQ=="],
+
+    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
+
+    "jiti": ["jiti@2.7.0", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ=="],
+
+    "typebox": ["typebox@1.1.38", "", {}, "sha512-pZ0aQPmMmXoUvSbeuWf/Hzsc+avNw/Zd6VeE8CFgkVGWyuHPJvqeJJDeJqLve+K70LvjYIoleGcoJHPT17cWoA=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="],
+
+    "zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
+  }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@dex-ai/pi-compat",
+  "version": "0.1.2",
+  "description": "Pi extension compatibility layer — load and run pi-coding-agent extensions inside Dex",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish"
+  },
+  "dependencies": {
+    "jiti": "^2.7.0",
+    "typebox": "^1.1.24",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@dex-ai/sdk": "^0.1.2",
+    "typescript": "^5.6.3",
+    "@types/bun": "^1.0.0",
+    "@changesets/cli": "^2.29.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}