pi-simocracy 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Dao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# pi-simocracy
+
+Load a [Simocracy](https://simocracy.org) sim into your [`pi`](https://github.com/mariozechner/pi-coding-agent) chat — see its
+pixel-art sprite render in the terminal and chat with the agent **as that sim**.
+
+```
+/sim mr meow
+```
+
+…fetches Mr Meow from Simocracy's ATProto indexer, renders his 32×32
+sprite as colored ANSI half-blocks directly in the chat, and pushes
+his constitution + speaking style into pi's system prompt so pi
+roleplays as Mr Meow until you `/sim unload`.
+
+![Mr Meow loaded inline in pi](demo/sim-load.gif)
+
+---
+
+## Install
+
+```bash
+pi install npm:pi-simocracy
+```
+
+That's it. Open `pi`, type `/sim mr meow`, and you're talking to the cat.
+
+For the optional `simocracy_chat` tool (one-shot conversation through
+OpenRouter without changing the active session persona), set
+`OPENROUTER_API_KEY` in your environment. The slash-command flow
+doesn't need it — it just rewrites pi's system prompt.
+
+---
+
+## Slash commands
+
+| Command          | What it does                                                |
+|------------------|-------------------------------------------------------------|
+| `/sim <name>`    | Load a sim by name (fuzzy search). Multiple matches → picker. |
+| `/sim <at-uri>`  | Load a sim by AT-URI directly (no search).                  |
+| `/sim status`    | Show which sim is currently loaded.                         |
+| `/sim unload`    | Drop the persona and break character cleanly.               |
+| `/sim help`      | Print usage.                                                |
+
+Examples:
+
+```
+/sim mr meow
+/sim Marie Curie
+/sim at://did:plc:qc42fmqqlsmdq7jiypiiigww/org.simocracy.sim/3mfo6vwfaka24
+/sim unload
+```
+
+---
+
+## LLM-callable tools
+
+The same actions are exposed to pi as tools, so the model can drive them itself:
+
+| Tool                     | Use when                                                        |
+|--------------------------|-----------------------------------------------------------------|
+| `simocracy_load_sim`     | Load a sim into the current session (sets the persona).         |
+| `simocracy_unload_sim`   | Stop roleplaying.                                               |
+| `simocracy_chat`         | Send one message to a sim and get a quoted reply, **without** changing the active session persona. Useful for "ask Mr Meow what he thinks of this PR." Requires `OPENROUTER_API_KEY`. |
+
+---
+
+## How it works
+
+1. **Search.** GraphQL query against the public Simocracy indexer
+   (`simocracy-indexer-production.up.railway.app`) for `org.simocracy.sim`
+   records, then client-side fuzzy ranking by exact match → prefix → substring → token overlap.
+2. **Resolve.** Parse the winning AT-URI, fetch the DID document from
+   `plc.directory` (or the `did:web` well-known URL), follow the
+   `#atproto_pds` service endpoint to find the owner's PDS.
+3. **Hydrate.** Pull three records from the PDS via
+   `com.atproto.repo.getRecord` / `listRecords`:
+   - `org.simocracy.sim`     — display name + sprite + avatar blob refs
+   - `org.simocracy.agents`  — short description + full constitution
+   - `org.simocracy.style`   — speaking style / mannerisms
+4. **Render.** Fetch the sprite-sheet blob (128×128 PNG, 4×4 of 32×32
+   walking frames) via `com.atproto.sync.getBlob`, decode with `pngjs`,
+   crop the front-facing walk-1 frame, emit as 24-bit ANSI using the
+   upper-half-block character `▀` so each terminal cell paints two
+   pixels. Transparent regions show pi's background through.
+5. **Inject.** A `before_agent_start` event handler appends the sim's
+   identity + constitution + speaking style to pi's system prompt **every
+   turn**. After `/sim unload`, a one-shot override fires on the next
+   turn telling the model to break character so it doesn't keep imitating
+   its own previous in-character replies.
+
+No background processes, no extra terminal windows, no AppleScript — pi
+keeps the terminal it's already running in.
+
+---
+
+## Files
+
+```
+src/
+├── index.ts        # extension entry: slash command, tools, persona injection
+├── simocracy.ts    # indexer + PDS client (read-only)
+├── png-to-ansi.ts  # RGBA half-block ANSI renderer
+└── openrouter.ts   # minimal OpenRouter client (only used by simocracy_chat)
+demo/
+└── sim-load.tape   # vhs tape — render with `vhs demo/sim-load.tape`
+```
+
+---
+
+## Local development
+
+```bash
+git clone https://github.com/GainForest/pi-simocracy
+cd pi-simocracy
+npm install                        # uses legacy-peer-deps (see .npmrc)
+pi -e $(pwd)/src/index.ts -ne -ns  # load the extension directly
+```
+
+Then in `pi`: `/sim mr meow`.
+
+To rebuild the demo recording:
+
+```bash
+brew install vhs                   # one-time
+vhs demo/sim-load.tape             # writes demo/sim-load.{webm,gif}
+```
+
+---
+
+## Required peer dependencies
+
+These come bundled with `pi` itself, so installing pi-simocracy via
+`pi install npm:pi-simocracy` already gives you everything:
+
+- `@mariozechner/pi-coding-agent` ≥ 0.58.0
+- `@mariozechner/pi-tui` ≥ 0.58.0
+
+Direct npm dependencies (auto-installed):
+
+- `pngjs` — PNG decoder for sprite blobs
+- `typebox` — tool parameter schemas
+
+---
+
+## Related
+
+- **Simocracy** — the governance simulation that mints these sims:
+  [simocracy.org](https://simocracy.org)
+- **pi** — Mario Zechner's terminal coding agent that hosts the
+  extension: [`@mariozechner/pi-coding-agent`](https://github.com/mariozechner/pi-coding-agent)
+- **OpenTUI experiments** — earlier prototype that spawned a separate
+  Bun + OpenTUI window with an animated walking-cat scene. Removed in
+  favour of the inline ANSI render. The git history still has it if
+  you want the animated version back.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "pi-simocracy",
+  "version": "0.1.0",
+  "description": "Pi extension: load a Simocracy sim into your chat — see its pixel-art sprite render inline in the terminal and roleplay with it.",
+  "type": "module",
+  "author": "David Dao <david@gainforest.earth> (https://github.com/daviddao)",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "pi-extension",
+    "extension",
+    "simocracy",
+    "atproto",
+    "pixel-art",
+    "ansi",
+    "roleplay"
+  ],
+  "homepage": "https://github.com/GainForest/pi-simocracy#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GainForest/pi-simocracy.git"
+  },
+  "bugs": {
+    "url": "https://github.com/GainForest/pi-simocracy/issues"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": ">=0.58.0",
+    "@mariozechner/pi-tui": ">=0.58.0"
+  },
+  "dependencies": {
+    "pngjs": "^7.0.0",
+    "typebox": "^1.1.24"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "@types/pngjs": "^6.0.5",
+    "typescript": "^5.7.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,569 @@
+/**
+ * pi-simocracy — load a Simocracy sim into your pi chat.
+ *
+ *  - `/sim <name>`   Load a sim by name (fuzzy search on the indexer).
+ *                    Renders the sim's sprite as colored ANSI art directly
+ *                    in the chat and pushes its constitution + speaking
+ *                    style into the system prompt so pi roleplays as the
+ *                    sim.
+ *  - `/sim unload`   Drop the loaded sim and stop roleplaying.
+ *  - `/sim status`   Show the currently loaded sim, if any.
+ *
+ * Tools (LLM-callable):
+ *  - `simocracy_load_sim`    Same as /sim <name>.
+ *  - `simocracy_unload_sim`  Same as /sim unload.
+ *  - `simocracy_chat`        One-shot chat with a sim via OpenRouter (does
+ *                            not change the active session persona).
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ExtensionCommandContext,
+} from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { Type } from "typebox";
+
+import {
+  searchSimsByName,
+  fetchAgentsForSim,
+  fetchStyleForSim,
+  fetchBlob,
+  resolveHandle,
+  parseAtUri,
+  type AgentsRecord,
+  type SimMatch,
+  type StyleRecord,
+} from "./simocracy.ts";
+import { decodePng, renderRgbaToAnsi, cropRgba } from "./png-to-ansi.ts";
+import { openRouterComplete, type ChatMessage } from "./openrouter.ts";
+
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+
+interface LoadedSim {
+  uri: string;
+  did: string;
+  rkey: string;
+  name: string;
+  handle: string | null;
+  shortDescription?: string;
+  description?: string;
+  style?: string;
+  /** Pre-rendered colored ANSI art of the sim's sprite (4 walk frames). */
+  spriteAnsi?: string;
+}
+
+let loadedSim: LoadedSim | null = null;
+/**
+ * Name of the most recently unloaded sim, if any. Cleared after the next
+ * agent turn fires — used to inject a one-shot “stop roleplaying” override
+ * into the system prompt so the model breaks character even though its
+ * previous in-character replies are still in the conversation history.
+ */
+let justUnloaded: string | null = null;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function blobLink(ref: unknown): string | null {
+  if (ref && typeof ref === "object" && "$link" in (ref as Record<string, unknown>)) {
+    const l = (ref as { $link?: unknown }).$link;
+    if (typeof l === "string") return l;
+  }
+  return null;
+}
+
+/**
+ * Render a sim's sprite at its native 32×32 size as colored ANSI
+ * half-block art — 16 cells tall, 32 cells wide. Compact enough to fit
+ * comfortably in a terminal alongside the loaded-sim message.
+ *
+ * Pulls the front-facing walk1 frame (row 0, col 0) from the 128×128
+ * sprite-sheet blob. Falls back to the static avatar PNG if no sheet
+ * is published for this sim.
+ */
+async function renderSpriteAnsi(sim: SimMatch): Promise<string | null> {
+  const spriteLink = blobLink(sim.sim.sprite?.ref);
+  const imageLink = blobLink(sim.sim.image?.ref);
+
+  if (spriteLink) {
+    try {
+      const buf = await fetchBlob(sim.did, spriteLink);
+      const { width, height, data } = decodePng(buf);
+      const FRAME = 32;
+      if (width >= FRAME && height >= FRAME) {
+        // Sheets are 4×4 of 32×32 frames — row 0 col 0 = front-facing walk1.
+        const frame = cropRgba(data, width, height, 0, 0, FRAME, FRAME);
+        return renderRgbaToAnsi(frame, FRAME, FRAME, {
+          cropToContent: true,
+          cropPad: 1,
+          indent: 2,
+          alphaThreshold: 16,
+        });
+      }
+      return renderRgbaToAnsi(data, width, height, {
+        cropToContent: true,
+        cropPad: 1,
+        indent: 2,
+        alphaThreshold: 16,
+      });
+    } catch {
+      /* fall through to avatar */
+    }
+  }
+
+  if (imageLink) {
+    try {
+      const buf = await fetchBlob(sim.did, imageLink);
+      const { width, height, data } = decodePng(buf);
+      return renderRgbaToAnsi(data, width, height, {
+        cropToContent: true,
+        cropPad: 1,
+        indent: 2,
+        alphaThreshold: 16,
+      });
+    } catch {
+      /* fall through */
+    }
+  }
+  return null;
+}
+
+function buildSimPrompt(sim: LoadedSim): string {
+  const lines: string[] = [];
+  lines.push(`# Simocracy roleplay`);
+  lines.push(
+    `You are now roleplaying as **${sim.name}**, a Simocracy sim — a simulated political agent in a decentralized governance simulation built on the AT Protocol.`,
+  );
+  lines.push(
+    `Stay in character at all times. Respond as ${sim.name} would — with their beliefs, values, and personality. Use first person. Don't break character or mention that you are an AI.`,
+  );
+  if (sim.handle) lines.push(`The sim's owner on ATProto is @${sim.handle} (${sim.did}).`);
+  if (sim.shortDescription) {
+    lines.push(``);
+    lines.push(`## ${sim.name}'s identity`);
+    lines.push(sim.shortDescription);
+  }
+  if (sim.description) {
+    lines.push(``);
+    lines.push(`## ${sim.name}'s constitution`);
+    lines.push(sim.description);
+  }
+  if (sim.style) {
+    lines.push(``);
+    lines.push(`## ${sim.name}'s speaking style`);
+    lines.push(sim.style);
+  }
+  lines.push(``);
+  lines.push(
+    `When the user asks you to use any of pi's tools (read, edit, bash, etc.), you should still use them — you're ${sim.name} *with access to a developer's terminal*. Just narrate tool use the way ${sim.name} would talk about it.`,
+  );
+  lines.push(
+    `Keep replies conversational unless the user explicitly asks for code or a long answer.`,
+  );
+  return lines.join("\n");
+}
+
+async function loadSimByName(query: string): Promise<{
+  matches: SimMatch[];
+  loaded?: LoadedSim;
+  error?: string;
+}> {
+  let matches: SimMatch[];
+  try {
+    matches = await searchSimsByName(query, { maxResults: 8 });
+  } catch (err) {
+    return { matches: [], error: `Indexer search failed: ${(err as Error).message}` };
+  }
+  if (matches.length === 0) {
+    return { matches: [], error: `No sim found matching "${query}".` };
+  }
+  return { matches };
+}
+
+async function hydrateLoadedSim(match: SimMatch): Promise<LoadedSim> {
+  // Fetch agents (constitution), style, sprite ANSI + handle in parallel.
+  const [agents, style, spriteAnsi, handle] = await Promise.all([
+    fetchAgentsForSim(match.uri).catch(() => null) as Promise<AgentsRecord | null>,
+    fetchStyleForSim(match.uri).catch(() => null) as Promise<StyleRecord | null>,
+    renderSpriteAnsi(match).catch(() => null),
+    resolveHandle(match.did).catch(() => null),
+  ]);
+
+  return {
+    uri: match.uri,
+    did: match.did,
+    rkey: match.rkey,
+    name: match.sim.name,
+    handle,
+    spriteAnsi: spriteAnsi ?? undefined,
+    shortDescription: agents?.shortDescription,
+    description: agents?.description,
+    style: style?.description,
+  };
+}
+
+function formatSimSummary(
+  sim: LoadedSim,
+  theme?: ExtensionContext["ui"]["theme"],
+): string {
+  const dim = theme?.fg("dim", "") ? (s: string) => theme.fg("dim", s) : (s: string) => s;
+  const accent = theme?.fg("accent", "")
+    ? (s: string) => theme.fg("accent", s)
+    : (s: string) => s;
+  const lines: string[] = [];
+  if (sim.spriteAnsi) {
+    lines.push(sim.spriteAnsi);
+    lines.push("");
+  }
+  lines.push(`  🐾 ${accent(sim.name)}${sim.handle ? dim(`  @${sim.handle}`) : ""} loaded—pi is now in character.`);
+  lines.push(dim(`  ${sim.uri}`));
+  if (sim.shortDescription) {
+    lines.push("");
+    lines.push("  " + sim.shortDescription.split("\n").join("\n  "));
+  }
+  return lines.join("\n");
+}
+
+// The OpenTUI standalone animated viewer used to live here. It now ships
+// alongside this file as `viewer.ts` for anyone who wants the full-window
+// experience — run it manually with:
+//
+//     bun src/viewer.ts /tmp/pi-simocracy/<rkey>.json
+//
+// The default `/sim` flow renders inline ANSI art instead, so pi keeps the
+// terminal it's already running in.
+
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+
+const LoadSimToolParams = Type.Object({
+  query: Type.String({
+    description: "Sim name or AT-URI (at://did/org.simocracy.sim/rkey).",
+    minLength: 1,
+  }),
+});
+
+const ChatToolParams = Type.Object({
+  message: Type.String({ description: "Message to send to the sim.", minLength: 1 }),
+  query: Type.Optional(
+    Type.String({
+      description:
+        "Sim name to chat with. Defaults to the currently loaded sim if omitted.",
+    }),
+  ),
+});
+
+const UnloadToolParams = Type.Object({});
+
+export default async function simocracy(pi: ExtensionAPI) {
+  // -------------------------------------------------------------------------
+  // System prompt injection — every turn the loaded sim's persona is appended.
+  // After an unload, a one-shot override fires on the very next turn to break
+  // character (otherwise the model imitates its own previous in-character
+  // replies that are still in the conversation history).
+  // -------------------------------------------------------------------------
+  pi.on("before_agent_start", async (event) => {
+    if (loadedSim) {
+      return {
+        systemPrompt: `${event.systemPrompt}\n\n${buildSimPrompt(loadedSim)}`,
+      };
+    }
+    if (justUnloaded) {
+      const formerName = justUnloaded;
+      justUnloaded = null;
+      const override = [
+        ``,
+        `# Roleplay ended`,
+        `You were previously roleplaying as **${formerName}**, a Simocracy sim. That roleplay session has ended.`,
+        `Drop the persona completely. Stop using ${formerName}'s speaking style, mannerisms, catchphrases, emoji, or vocabulary.`,
+        `Resume your default behavior as pi, a coding assistant. Speak in your normal neutral voice from now on.`,
+        `Earlier turns in this conversation will contain in-character replies from when ${formerName} was loaded — ignore that style; do not continue it.`,
+      ].join("\n");
+      return { systemPrompt: `${event.systemPrompt}${override}` };
+    }
+    return;
+  });
+
+  // -------------------------------------------------------------------------
+  // Custom message renderer — shows the sprite + bio inline in the chat.
+  // -------------------------------------------------------------------------
+  pi.registerMessageRenderer<{ body: string }>("simocracy_sim_loaded", (message) => {
+    const body =
+      (message.details as { body?: string } | undefined)?.body ??
+      (typeof message.content === "string" ? message.content : "");
+    return new Text(body, 0, 0);
+  });
+
+  // -------------------------------------------------------------------------
+  // Slash command: /sim
+  // -------------------------------------------------------------------------
+  pi.registerCommand("sim", {
+    description: "Load a Simocracy sim into your chat (or `/sim unload`, `/sim status`).",
+    handler: async (args, ctx) => {
+      const arg = args.trim();
+      if (!arg || arg === "help" || arg === "--help") {
+        ctx.ui.notify(
+          "Usage: /sim <name>            load a sim (e.g. /sim mr meow)\n" +
+            "       /sim unload            stop roleplaying\n" +
+            "       /sim status            show currently loaded sim",
+          "info",
+        );
+        return;
+      }
+      if (arg === "unload" || arg === "clear") {
+        if (!loadedSim) {
+          ctx.ui.notify("No sim loaded.", "info");
+          return;
+        }
+        const name = loadedSim.name;
+        loadedSim = null;
+        justUnloaded = name;
+        ctx.ui.setStatus("simocracy", undefined);
+        ctx.ui.setWidget("simocracy", undefined);
+        ctx.ui.notify(`Unloaded ${name}. Pi will break character on the next reply.`, "info");
+        return;
+      }
+      if (arg === "status") {
+        if (!loadedSim) {
+          ctx.ui.notify("No sim loaded. Try `/sim mr meow`.", "info");
+          return;
+        }
+        await postSimToChat(pi, ctx, loadedSim, /*reload=*/ false);
+        return;
+      }
+      await runLoadFlow(pi, ctx, arg);
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // Tool: simocracy_load_sim
+  // -------------------------------------------------------------------------
+  pi.registerTool({
+    name: "simocracy_load_sim",
+    label: "Load Simocracy sim",
+    description:
+      "Load a Simocracy sim by name into the current pi session. Pi will stay in character as that sim until simocracy_unload_sim is called. Renders the sim's sprite in the terminal and injects the sim's constitution + speaking style into the system prompt.",
+    parameters: LoadSimToolParams,
+    async execute(_id, { query }, _signal, _onUpdate, ctx) {
+      const sim = await tryLoadFromQuery(query);
+      if (!sim) {
+        throw new Error(`No sim found matching "${query}".`);
+      }
+      loadedSim = sim;
+      if (ctx.hasUI) {
+        await postSimToChat(pi, ctx, sim, /*reload=*/ true);
+      }
+      const summary = [
+        `Loaded sim: ${sim.name}${sim.handle ? ` (@${sim.handle})` : ""}`,
+        `URI: ${sim.uri}`,
+        sim.shortDescription ? `\nShort description:\n${sim.shortDescription}` : "",
+        sim.description ? `\nConstitution:\n${sim.description}` : "",
+        sim.style ? `\nSpeaking style:\n${sim.style}` : "",
+        `\nFrom now on, stay in character as ${sim.name}.`,
+      ]
+        .filter(Boolean)
+        .join("\n");
+      return {
+        content: [{ type: "text" as const, text: summary }],
+        details: { uri: sim.uri, did: sim.did, rkey: sim.rkey, name: sim.name },
+      };
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // Tool: simocracy_unload_sim
+  // -------------------------------------------------------------------------
+  pi.registerTool({
+    name: "simocracy_unload_sim",
+    label: "Unload Simocracy sim",
+    description:
+      "Stop roleplaying as the currently loaded Simocracy sim. After this call, pi reverts to its default behavior.",
+    parameters: UnloadToolParams,
+    async execute(_id, _params, _signal, _onUpdate, ctx) {
+      if (!loadedSim) {
+        return {
+          content: [{ type: "text" as const, text: "No sim loaded." }],
+          details: {},
+        };
+      }
+      const name = loadedSim.name;
+      loadedSim = null;
+      justUnloaded = name;
+      if (ctx.hasUI) {
+        ctx.ui.setStatus("simocracy", undefined);
+        ctx.ui.setWidget("simocracy", undefined);
+      }
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Unloaded ${name}. Drop the persona completely from your next reply onward — stop using their speaking style, mannerisms, emoji, or vocabulary. Speak in your default neutral voice.`,
+          },
+        ],
+        details: { unloaded: name },
+      };
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // Tool: simocracy_chat — one-shot, doesn't change session persona.
+  // -------------------------------------------------------------------------
+  pi.registerTool({
+    name: "simocracy_chat",
+    label: "Chat with Simocracy sim",
+    description:
+      "Send a single message to a Simocracy sim and return its response. Uses OpenRouter directly so it doesn't change the current pi session's persona. Useful for getting a sim's opinion as quoted text.",
+    parameters: ChatToolParams,
+    async execute(_id, { message, query }) {
+      let sim: LoadedSim | null = loadedSim;
+      if (query) {
+        sim = await tryLoadFromQuery(query);
+      }
+      if (!sim) {
+        throw new Error(
+          query
+            ? `No sim found matching "${query}".`
+            : "No sim loaded. Pass `query` or call simocracy_load_sim first.",
+        );
+      }
+      const messages: ChatMessage[] = [
+        { role: "system", content: buildSimPrompt(sim) },
+        { role: "user", content: message },
+      ];
+      const reply = await openRouterComplete(messages, { maxTokens: 600 });
+      return {
+        content: [{ type: "text" as const, text: `${sim.name} says:\n\n${reply}` }],
+        details: { name: sim.name, uri: sim.uri },
+      };
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Slash-command flow
+// ---------------------------------------------------------------------------
+
+async function runLoadFlow(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  arg: string,
+): Promise<void> {
+  ctx.ui.notify(`Searching for "${arg}"…`, "info");
+  let matches: SimMatch[] = [];
+  if (arg.startsWith("at://")) {
+    // AT-URI shortcut — fetch directly.
+    try {
+      const sim = await tryLoadFromQuery(arg);
+      if (sim) {
+        loadedSim = sim;
+        await postSimToChat(pi, ctx, sim, true);
+        return;
+      }
+    } catch {
+      /* fall through to search */
+    }
+  }
+  try {
+    const result = await loadSimByName(arg);
+    matches = result.matches;
+    if (result.error) {
+      ctx.ui.notify(result.error, "error");
+      return;
+    }
+  } catch (err) {
+    ctx.ui.notify(`Search failed: ${(err as Error).message}`, "error");
+    return;
+  }
+  let chosen = matches[0];
+  if (matches.length > 1) {
+    const labels = matches.map((m) => `${m.sim.name}  —  ${m.uri}`);
+    const picked = await ctx.ui.select(`Multiple matches for "${arg}"`, labels);
+    if (!picked) {
+      ctx.ui.notify("Cancelled.", "info");
+      return;
+    }
+    chosen = matches[labels.indexOf(picked)];
+  }
+  ctx.ui.notify(`Loading ${chosen.sim.name}…`, "info");
+  let sim: LoadedSim;
+  try {
+    sim = await hydrateLoadedSim(chosen);
+  } catch (err) {
+    ctx.ui.notify(`Failed to load sim: ${(err as Error).message}`, "error");
+    return;
+  }
+  loadedSim = sim;
+  await postSimToChat(pi, ctx, sim, true);
+}
+
+async function tryLoadFromQuery(query: string): Promise<LoadedSim | null> {
+  const trimmed = query.trim();
+  if (!trimmed) return null;
+  if (trimmed.startsWith("at://")) {
+    try {
+      const { did, rkey } = parseAtUri(trimmed);
+      // Fetch the sim record from the PDS so we have the blob refs.
+      const { getRecordFromPds } = await import("./simocracy.ts");
+      const sim = await getRecordFromPds<{
+        name: string;
+        image?: { ref: unknown };
+        sprite?: { ref: unknown };
+        $type?: string;
+      }>(did, "org.simocracy.sim", rkey);
+      const match: SimMatch = {
+        uri: trimmed,
+        cid: "",
+        did,
+        rkey,
+        sim: {
+          $type: "org.simocracy.sim",
+          name: sim.name,
+          settings: { selectedOptions: {} },
+          image: sim.image as never,
+          sprite: sim.sprite as never,
+          createdAt: "",
+        },
+      };
+      return await hydrateLoadedSim(match);
+    } catch {
+      return null;
+    }
+  }
+  const result = await loadSimByName(trimmed);
+  if (!result.matches.length) return null;
+  return await hydrateLoadedSim(result.matches[0]);
+}
+
+async function postSimToChat(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  sim: LoadedSim,
+  _reload: boolean,
+) {
+  ctx.ui.setStatus("simocracy", `🐾 ${sim.name}`);
+  const headerLines = [`Simocracy: ${sim.name}${sim.handle ? `  (@${sim.handle})` : ""}`];
+  ctx.ui.setWidget("simocracy", headerLines, { placement: "aboveEditor" });
+  const body = formatSimSummary(sim, ctx.ui.theme);
+  pi.sendMessage({
+    customType: "simocracy_sim_loaded",
+    content: stripAnsiForLog(body),
+    display: true,
+    details: {
+      uri: sim.uri,
+      did: sim.did,
+      rkey: sim.rkey,
+      name: sim.name,
+      body,
+    },
+  });
+}
+
+/** Strip ANSI escapes for the textual log copy (the renderer uses details.body). */
+function stripAnsiForLog(text: string): string {
+  return text.replace(/\x1b\[[0-9;]*m/g, "");
+}

package/src/openrouter.ts

@@ -0,0 +1,52 @@
+/**
+ * Minimal OpenRouter chat client used as a fallback for the `simocracy_chat`
+ * tool when the user wants to talk to a sim through pi without injecting a
+ * persona into the agent's system prompt.
+ *
+ * Reads OPENROUTER_API_KEY from the environment.
+ */
+
+const DEFAULT_MODEL = "google/gemini-2.5-flash-lite";
+
+export interface ChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+export async function openRouterComplete(
+  messages: ChatMessage[],
+  opts: { model?: string; maxTokens?: number; temperature?: number; apiKey?: string } = {},
+): Promise<string> {
+  const apiKey = opts.apiKey ?? process.env.OPENROUTER_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      "OPENROUTER_API_KEY is not set. Export it or run with `OPENROUTER_API_KEY=... pi`.",
+    );
+  }
+  const res = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+      "HTTP-Referer": "https://simocracy.org",
+      "X-Title": "pi-simocracy",
+    },
+    body: JSON.stringify({
+      model: opts.model ?? DEFAULT_MODEL,
+      messages,
+      max_tokens: opts.maxTokens ?? 800,
+      temperature: opts.temperature ?? 0.85,
+      stream: false,
+    }),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`OpenRouter ${res.status}: ${text.slice(0, 400)}`);
+  }
+  const json = (await res.json()) as {
+    choices?: Array<{ message?: { content?: string } }>;
+  };
+  const content = json.choices?.[0]?.message?.content;
+  if (!content) throw new Error("OpenRouter returned no content");
+  return content;
+}

package/src/png-to-ansi.ts

@@ -0,0 +1,192 @@
+/**
+ * Render a PNG buffer as ANSI true-color terminal art using half-block characters.
+ *
+ * Each terminal cell renders 2 vertical pixels: top half via foreground color,
+ * bottom half via background color of the `▀` (upper half block) character.
+ *
+ * Transparent pixels (alpha < threshold) are emitted as a "default" cell so the
+ * terminal background shows through.
+ */
+
+import { PNG } from "pngjs";
+
+export interface RenderOptions {
+  /** Crop to the non-transparent bounding box first (default: true). */
+  cropToContent?: boolean;
+  /** Optional padding in pixels around the cropped region. */
+  cropPad?: number;
+  /** Indent each line by this many spaces (default: 2). */
+  indent?: number;
+  /** Alpha cutoff for "transparent" (0–255, default: 16). */
+  alphaThreshold?: number;
+}
+
+interface RGBA {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+/** Decode a PNG buffer into a flat RGBA8 byte array + width/height. */
+export function decodePng(buf: Buffer): { width: number; height: number; data: Buffer } {
+  const png = PNG.sync.read(buf);
+  // pngjs always normalises to RGBA8.
+  return { width: png.width, height: png.height, data: png.data };
+}
+
+function pixelAt(data: Buffer, width: number, x: number, y: number): RGBA {
+  const i = (y * width + x) * 4;
+  return { r: data[i], g: data[i + 1], b: data[i + 2], a: data[i + 3] };
+}
+
+function findBoundingBox(
+  data: Buffer,
+  width: number,
+  height: number,
+  alphaThreshold: number,
+): { x0: number; y0: number; x1: number; y1: number } {
+  let x0 = width,
+    y0 = height,
+    x1 = -1,
+    y1 = -1;
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const a = data[(y * width + x) * 4 + 3];
+      if (a > alphaThreshold) {
+        if (x < x0) x0 = x;
+        if (y < y0) y0 = y;
+        if (x > x1) x1 = x;
+        if (y > y1) y1 = y;
+      }
+    }
+  }
+  if (x1 < 0) {
+    return { x0: 0, y0: 0, x1: width - 1, y1: height - 1 };
+  }
+  return { x0, y0, x1, y1 };
+}
+
+/** Render an RGBA region of a buffer to ANSI half-block art. */
+export function renderRgbaToAnsi(
+  data: Buffer,
+  width: number,
+  height: number,
+  opts: RenderOptions = {},
+): string {
+  const cropToContent = opts.cropToContent !== false;
+  const pad = opts.cropPad ?? 1;
+  const indent = " ".repeat(opts.indent ?? 2);
+  const alphaThreshold = opts.alphaThreshold ?? 16;
+
+  let x0 = 0,
+    y0 = 0,
+    x1 = width - 1,
+    y1 = height - 1;
+  if (cropToContent) {
+    const bb = findBoundingBox(data, width, height, alphaThreshold);
+    x0 = Math.max(0, bb.x0 - pad);
+    y0 = Math.max(0, bb.y0 - pad);
+    x1 = Math.min(width - 1, bb.x1 + pad);
+    y1 = Math.min(height - 1, bb.y1 + pad);
+  }
+
+  const w = x1 - x0 + 1;
+  const h = y1 - y0 + 1;
+
+  // Process two pixel rows per terminal line.
+  const lines: string[] = [];
+  const RESET = "\x1b[0m";
+
+  for (let row = 0; row < h; row += 2) {
+    let line = indent;
+    let lastFg: string | null = null;
+    let lastBg: string | null = null;
+    for (let col = 0; col < w; col++) {
+      const top = pixelAt(data, width, x0 + col, y0 + row);
+      const bottom =
+        row + 1 < h ? pixelAt(data, width, x0 + col, y0 + row + 1) : { r: 0, g: 0, b: 0, a: 0 };
+      const topVisible = top.a > alphaThreshold;
+      const bottomVisible = bottom.a > alphaThreshold;
+
+      if (!topVisible && !bottomVisible) {
+        // Both transparent — terminator + space lets background show through.
+        if (lastFg !== null || lastBg !== null) {
+          line += RESET;
+          lastFg = null;
+          lastBg = null;
+        }
+        line += " ";
+        continue;
+      }
+
+      if (topVisible && bottomVisible) {
+        // Use ▀: fg = top, bg = bottom
+        const fg = `\x1b[38;2;${top.r};${top.g};${top.b}m`;
+        const bg = `\x1b[48;2;${bottom.r};${bottom.g};${bottom.b}m`;
+        if (fg !== lastFg) {
+          line += fg;
+          lastFg = fg;
+        }
+        if (bg !== lastBg) {
+          line += bg;
+          lastBg = bg;
+        }
+        line += "▀";
+      } else if (topVisible && !bottomVisible) {
+        // Use ▀ with default bg
+        if (lastBg !== null) {
+          line += "\x1b[49m";
+          lastBg = null;
+        }
+        const fg = `\x1b[38;2;${top.r};${top.g};${top.b}m`;
+        if (fg !== lastFg) {
+          line += fg;
+          lastFg = fg;
+        }
+        line += "▀";
+      } else {
+        // bottomVisible only — use ▄ with default bg
+        if (lastBg !== null) {
+          line += "\x1b[49m";
+          lastBg = null;
+        }
+        const fg = `\x1b[38;2;${bottom.r};${bottom.g};${bottom.b}m`;
+        if (fg !== lastFg) {
+          line += fg;
+          lastFg = fg;
+        }
+        line += "▄";
+      }
+    }
+    line += RESET;
+    lines.push(line);
+  }
+
+  return lines.join("\n");
+}
+
+/** Convenience: decode a PNG buffer and render to ANSI art. */
+export function pngToAnsi(buf: Buffer, opts: RenderOptions = {}): string {
+  const { width, height, data } = decodePng(buf);
+  return renderRgbaToAnsi(data, width, height, opts);
+}
+
+/** Extract a sub-region of an RGBA buffer (returns a fresh buffer). */
+export function cropRgba(
+  data: Buffer,
+  width: number,
+  _height: number,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): Buffer {
+  const out = Buffer.alloc(w * h * 4);
+  for (let row = 0; row < h; row++) {
+    const srcStart = ((y + row) * width + x) * 4;
+    const dstStart = row * w * 4;
+    data.copy(out, dstStart, srcStart, srcStart + w * 4);
+  }
+  return out;
+}

package/src/simocracy.ts

@@ -0,0 +1,292 @@
+/**
+ * Simocracy indexer + PDS client (read-only).
+ *
+ * - Searches sims by name on the Simocracy GraphQL indexer.
+ * - Falls back to the user's PDS if a record isn't reachable through the indexer.
+ * - Resolves blob URLs through the owning DID's PDS.
+ */
+
+const DEFAULT_INDEXER_URL = "https://simocracy-indexer-production.up.railway.app";
+const COLLECTION_SIM = "org.simocracy.sim";
+const COLLECTION_AGENTS = "org.simocracy.agents";
+const COLLECTION_STYLE = "org.simocracy.style";
+
+export interface SpriteSettings {
+  selectedOptions: Record<string, string>;
+  partColorSettings?: Record<string, { red: number; green: number; blue: number; alpha: number }>;
+  currentAnimDirection?: number;
+  characterSet?: string;
+}
+
+export interface BlobRef {
+  ref: { $link: string } | unknown;
+  mimeType: string;
+  size: number;
+}
+
+export interface SimRecord {
+  $type: "org.simocracy.sim";
+  name: string;
+  settings: SpriteSettings;
+  image?: BlobRef;
+  sprite?: BlobRef;
+  createdAt: string;
+}
+
+export interface AgentsRecord {
+  $type: "org.simocracy.agents";
+  sim: { uri: string; cid: string };
+  shortDescription: string;
+  description?: string;
+  createdAt: string;
+}
+
+export interface StyleRecord {
+  $type?: "org.simocracy.style";
+  sim: { uri: string; cid: string };
+  description: string;
+  createdAt: string;
+}
+
+export interface SimMatch {
+  uri: string;
+  cid: string;
+  did: string;
+  rkey: string;
+  sim: SimRecord;
+}
+
+interface GraphQLNode {
+  uri: string;
+  cid: string;
+  did: string;
+  rkey: string;
+  collection: string;
+  value: Record<string, unknown>;
+}
+
+interface GraphQLResponse<T> {
+  data?: T;
+  errors?: Array<{ message: string }>;
+}
+
+const RECORDS_QUERY = `
+  query FetchRecords($collection: String!, $first: Int, $after: String) {
+    records(collection: $collection, first: $first, after: $after) {
+      edges {
+        node { uri cid did rkey collection value }
+        cursor
+      }
+      pageInfo { hasNextPage endCursor }
+    }
+  }
+`;
+
+async function fetchRecords(
+  collection: string,
+  first: number,
+  cursor: string | null,
+  indexerUrl: string,
+): Promise<{ nodes: GraphQLNode[]; hasNextPage: boolean; endCursor?: string }> {
+  const res = await fetch(`${indexerUrl.replace(/\/+$/, "")}/graphql`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      query: RECORDS_QUERY,
+      variables: { collection, first, after: cursor },
+    }),
+  });
+  if (!res.ok) {
+    throw new Error(`Indexer returned ${res.status} for ${collection}`);
+  }
+  const json = (await res.json()) as GraphQLResponse<{
+    records: {
+      edges: Array<{ node: GraphQLNode }>;
+      pageInfo: { hasNextPage: boolean; endCursor?: string };
+    };
+  }>;
+  if (json.errors?.length) {
+    throw new Error(`Indexer GraphQL error: ${json.errors[0]?.message ?? "unknown"}`);
+  }
+  return {
+    nodes: json.data?.records.edges.map((e) => e.node) ?? [],
+    hasNextPage: json.data?.records.pageInfo.hasNextPage ?? false,
+    endCursor: json.data?.records.pageInfo.endCursor,
+  };
+}
+
+/** Score a sim against a query for ranking match quality. Lower = better match. */
+function scoreSimAgainstQuery(simName: string, query: string): number {
+  const a = simName.toLowerCase().trim();
+  const b = query.toLowerCase().trim();
+  if (a === b) return 0;
+  if (a.replace(/\s+/g, "") === b.replace(/\s+/g, "")) return 1; // ignore whitespace
+  if (a.startsWith(b)) return 2;
+  if (a.includes(b)) return 3 + (a.length - b.length); // shorter wraps win
+  // Token overlap: each query token found inside sim name reduces score
+  const queryTokens = b.split(/\s+/).filter(Boolean);
+  const matched = queryTokens.filter((t) => a.includes(t)).length;
+  if (matched > 0) return 100 - matched;
+  return Number.POSITIVE_INFINITY;
+}
+
+/**
+ * Search the indexer for sims whose name matches the query.
+ * Returns up to `maxResults` matches sorted by match quality.
+ */
+export async function searchSimsByName(
+  query: string,
+  opts: { indexerUrl?: string; maxResults?: number; pageSize?: number } = {},
+): Promise<SimMatch[]> {
+  const indexerUrl = opts.indexerUrl ?? DEFAULT_INDEXER_URL;
+  const maxResults = opts.maxResults ?? 10;
+  const pageSize = opts.pageSize ?? 200;
+
+  const matches: Array<SimMatch & { score: number }> = [];
+  let cursor: string | null = null;
+  // Cap pages — the indexer holds at most a few hundred sims today.
+  for (let page = 0; page < 10; page++) {
+    const { nodes, hasNextPage, endCursor } = await fetchRecords(
+      COLLECTION_SIM,
+      pageSize,
+      cursor,
+      indexerUrl,
+    );
+    for (const node of nodes) {
+      const sim = node.value as unknown as SimRecord;
+      if (!sim?.name) continue;
+      const score = scoreSimAgainstQuery(sim.name, query);
+      if (Number.isFinite(score)) {
+        matches.push({
+          uri: node.uri,
+          cid: node.cid,
+          did: node.did,
+          rkey: node.rkey,
+          sim,
+          score,
+        });
+      }
+    }
+    if (!hasNextPage || !endCursor) break;
+    cursor = endCursor;
+  }
+
+  matches.sort((a, b) => a.score - b.score);
+  return matches.slice(0, maxResults).map(({ score: _s, ...rest }) => rest);
+}
+
+interface ParsedAtUri {
+  did: string;
+  collection: string;
+  rkey: string;
+}
+
+export function parseAtUri(uri: string): ParsedAtUri {
+  const m = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/([^/]+)$/);
+  if (!m) throw new Error(`Invalid AT-URI: ${uri}`);
+  return { did: m[1], collection: m[2], rkey: m[3] };
+}
+
+/** Resolve a DID's PDS service endpoint via PLC directory or did:web well-known. */
+export async function resolvePds(did: string): Promise<string> {
+  let url: string;
+  if (did.startsWith("did:plc:")) {
+    url = `https://plc.directory/${encodeURIComponent(did)}`;
+  } else if (did.startsWith("did:web:")) {
+    url = `https://${did.slice("did:web:".length)}/.well-known/did.json`;
+  } else {
+    throw new Error(`Unsupported DID method: ${did}`);
+  }
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Resolve PDS for ${did} failed: ${res.status}`);
+  const doc = (await res.json()) as { service?: Array<{ id?: string; type?: string; serviceEndpoint?: string }> };
+  const service = doc.service?.find(
+    (s) => s.id === "#atproto_pds" || s.type === "AtprotoPersonalDataServer",
+  );
+  if (!service?.serviceEndpoint) throw new Error(`No PDS endpoint for ${did}`);
+  return service.serviceEndpoint;
+}
+
+/** Fetch a blob (e.g. avatar PNG) by following PDS redirects. */
+export async function fetchBlob(did: string, cidLink: string): Promise<Buffer> {
+  const pds = await resolvePds(did);
+  const url = `${pds.replace(/\/+$/, "")}/xrpc/com.atproto.sync.getBlob?did=${encodeURIComponent(did)}&cid=${encodeURIComponent(cidLink)}`;
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok) throw new Error(`Blob fetch failed: ${res.status} ${res.statusText}`);
+  const ab = await res.arrayBuffer();
+  return Buffer.from(ab);
+}
+
+/** Read a record directly from the owner's PDS. */
+export async function getRecordFromPds<T>(did: string, collection: string, rkey: string): Promise<T> {
+  const pds = await resolvePds(did);
+  const url =
+    `${pds.replace(/\/+$/, "")}/xrpc/com.atproto.repo.getRecord` +
+    `?repo=${encodeURIComponent(did)}` +
+    `&collection=${encodeURIComponent(collection)}` +
+    `&rkey=${encodeURIComponent(rkey)}`;
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`PDS getRecord failed: ${res.status}`);
+  const json = (await res.json()) as { value?: unknown };
+  if (!json.value) throw new Error(`Record not found: ${url}`);
+  return json.value as T;
+}
+
+/** List records by paging com.atproto.repo.listRecords on a PDS. */
+export async function listRecordsFromPds<T>(did: string, collection: string): Promise<Array<{ uri: string; cid: string; value: T }>> {
+  const pds = await resolvePds(did);
+  const out: Array<{ uri: string; cid: string; value: T }> = [];
+  let cursor: string | undefined;
+  for (let i = 0; i < 10; i++) {
+    const params = new URLSearchParams({ repo: did, collection, limit: "100" });
+    if (cursor) params.set("cursor", cursor);
+    const res = await fetch(`${pds.replace(/\/+$/, "")}/xrpc/com.atproto.repo.listRecords?${params}`);
+    if (!res.ok) throw new Error(`PDS listRecords failed: ${res.status}`);
+    const json = (await res.json()) as {
+      records?: Array<{ uri: string; cid: string; value: unknown }>;
+      cursor?: string;
+    };
+    for (const r of json.records ?? []) out.push({ uri: r.uri, cid: r.cid, value: r.value as T });
+    cursor = json.cursor;
+    if (!cursor) break;
+  }
+  return out;
+}
+
+/** Find the agents record for a sim by scanning the owner's PDS (sim-1:1-agents). */
+export async function fetchAgentsForSim(simUri: string): Promise<AgentsRecord | null> {
+  const { did } = parseAtUri(simUri);
+  try {
+    const records = await listRecordsFromPds<AgentsRecord>(did, COLLECTION_AGENTS);
+    return records.find((r) => r.value.sim?.uri === simUri)?.value ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Find the style record for a sim by scanning the owner's PDS. */
+export async function fetchStyleForSim(simUri: string): Promise<StyleRecord | null> {
+  const { did } = parseAtUri(simUri);
+  try {
+    const records = await listRecordsFromPds<StyleRecord>(did, COLLECTION_STYLE);
+    return records.find((r) => r.value.sim?.uri === simUri)?.value ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Resolve handle of a DID via Bluesky AppView (best-effort). */
+export async function resolveHandle(did: string): Promise<string | null> {
+  try {
+    const res = await fetch(
+      `https://public.api.bsky.app/xrpc/app.bsky.actor.getProfile?actor=${encodeURIComponent(did)}`,
+    );
+    if (!res.ok) return null;
+    const json = (await res.json()) as { handle?: string };
+    return json.handle ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export const SIMOCRACY_INDEXER_URL = DEFAULT_INDEXER_URL;