pi-simocracy 0.5.1 → 0.6.1

package/README.md

@@ -1,239 +1,89 @@
 # pi-simocracy
 
-Load a [Simocracy](https://simocracy.org) sim into your [`pi`](https://github.com/mariozechner/pi-coding-agent) chat — see its
-sprite render in the terminal and chat with the agent **as that sim**.
+A [`pi`](https://github.com/mariozechner/pi-coding-agent) extension for
+[Simocracy](https://simocracy.org). Loads a sim into your chat as a
+roleplay persona, and lets the agent read and write Simocracy records
+(constitution, speaking style, comments) on your behalf.
 
 ```
-/sim mr meow
+pi install npm:pi-simocracy
 ```
 
-…fetches Mr Meow from Simocracy's ATProto indexer, renders his 32×32
-pixel-art 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`.
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/GainForest/pi-simocracy/main/demo/sim-load.gif" alt="Mr Meow (a pipoya pixel-art cat) loaded inline in pi's chat" width="760">
-</p>
-
-As of v0.4.0, codex pet sims (OpenAI hatch-pet skill output) render too —
-load **Einstein** with `/sim einstein` and the WebP atlas decodes, the
-idle frame crops, and the half-block ANSI render fires inline:
-
 <p align="center">
-  <img src="https://raw.githubusercontent.com/GainForest/pi-simocracy/main/demo/codex-pet-load.gif" alt="Einstein (a codex pet sim with a WebP petSheet) loaded inline in pi's chat" width="760">
+  <img src="https://raw.githubusercontent.com/GainForest/pi-simocracy/main/demo/sim-hero.gif" alt="Loading Duo and Mr Meow into pi's chat" width="900">
 </p>
 
 ---
 
-## Install
-
-```bash
-pi install npm:pi-simocracy
-```
-
-That's it. Open `pi`, type `/sim mr meow`, and you're talking to the cat.
+## Slash commands
 
-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.
+| Command               | What it does |
+|-----------------------|---|
+| `/sim <name>`         | Load a sim by fuzzy name. Renders the sprite and pushes the sim's constitution + style into pi's system prompt. |
+| `/sim <at-uri>`       | Load a sim by AT-URI (no search). |
+| `/sim unload`         | Drop the persona and break character cleanly on the next reply. |
+| `/sim status`         | Show the currently loaded sim. |
+| `/sim my [name]`      | Pick / fuzzy-load from sims you own. Requires `/sim login`. |
+| `/sim login [handle]` | Sign in to ATProto via loopback OAuth. Required for any write. **Unrelated to pi's built-in `/login`** (that signs you into your model provider). |
+| `/sim logout`         | Clear the local ATProto session. |
+| `/sim whoami`         | Show the signed-in handle / DID. |
 
 ---
 
-## 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 login [handle]` | Sign in to **ATProto / Bluesky** via loopback OAuth (NOT Anthropic — pi's built-in `/login` is what does that). Required before pi can update your sim. |
-| `/sim logout`     | Clear the local ATProto OAuth session.                      |
-| `/sim whoami`     | Show the signed-in handle / DID.                            |
-| `/sim my [name]`  | List / pick / fuzzy-load sims you own on your PDS. Single match auto-loads; ambiguous matches open a picker. Requires `/sim login`. |
-| `/sim help`       | Print usage.                                                |
-
-Examples:
+## Tools (LLM-callable)
 
-```
-/sim mr meow
-/sim Marie Curie
-/sim at://did:plc:qc42fmqqlsmdq7jiypiiigww/org.simocracy.sim/3mfo6vwfaka24
-/sim login alice.bsky.social
-/sim my
-/sim unload
-```
+| Tool | When to call it |
+|---|---|
+| `simocracy_load_sim` | Load a sim into the 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. Needs `OPENROUTER_API_KEY`. |
+| `simocracy_lookup_record` | Fetch a sim / proposal / gathering / decision / comment by AT-URI or fuzzy name. Returns the record + comment subtree, with sim-authored comments flagged inline (🐾) so you can tell which opinions are human and which are sim. Use this before `simocracy_post_comment` to find the right `subjectUri`. |
+| `simocracy_post_comment` | Post a comment on a record **as the loaded sim**. Writes the comment plus an `org.simocracy.history` sidecar that attributes it to the sim. Requires `/sim login` + sim ownership. See [`docs/SIM_AUTHORED_COMMENTS.md`](docs/SIM_AUTHORED_COMMENTS.md) for the design. |
+| `simocracy_post_proposal` | Submit a new funding proposal (`org.hypercerts.claim.activity`) **as the loaded sim**. Writes the proposal plus an `org.simocracy.history` sidecar with `type: "proposal"`. Optional itemized `budgetItems`, `workScope` tags, `contributors`, and an https `imageUri` (the default Simocracy banner is used otherwise — image upload from disk is intentionally not supported). Requires `/sim login` + sim ownership. See [`docs/SIM_AUTHORED_PROPOSALS.md`](docs/SIM_AUTHORED_PROPOSALS.md) for the design. |
+| `simocracy_update_sim` | Rewrite the loaded sim's constitution (`shortDescription` + `description`) and/or speaking `style` and persist to your PDS. Requires `/sim login` + sim ownership. |
 
 ---
 
-## Editing a sim's constitution / speaking style
-
-There is no slash-command pipeline for this. Once you've signed in via
-`/sim login` and loaded a sim you own (`/sim my`, then pick), just
-**describe the change you want to pi**:
+## Typical agent flows
 
+**Roleplay as a sim:**
 ```
-> add a red line about animal welfare to the constitution
-> rewrite the speaking style to drop the lenny faces and be more concise
-> shorten the constitution to ~300 words and emphasise renewable energy
+/sim mr meow
 ```
+Then chat normally — pi answers in character.
 
-Pi rewrites the constitution and/or speaking style itself, then calls
-the `simocracy_update_sim` tool to persist the result. The tool refuses
-to run if you're not signed in or you don't own the loaded sim. The
-new persona takes effect on the next reply — no reload needed.
-
-Writing goes directly to your PDS via
-`com.atproto.repo.createRecord` / `putRecord` against the
-`org.simocracy.agents` (constitution) and `org.simocracy.style`
-(speaking style) collections — the same lexicons simocracy.org reads
-back.
-
----
-
-## 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`. |
-| `simocracy_update_sim`  | Write a new constitution (`shortDescription` + `description`) and/or speaking `style` for the **loaded** sim to your PDS. Requires `/sim login` AND ownership of the loaded sim. |
-
----
-
-## 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 blob via `com.atproto.sync.getBlob`,
-   decode it, crop the front-facing idle frame. Two render paths
-   depending on the sim's `spriteKind`:
-   - **`pipoya`** (legacy + default): 128×128 PNG, 4×4 of 32×32 walking
-     frames; decode with `pngjs`, take row 0 col 0 at native size.
-   - **`codexPet`** (OpenAI hatch-pet output): 1536×1872 atlas, 8×9 of
-     192×208 cells. PNG sheets decode through `pngjs`; WebP sheets
-     decode through `@jsquash/webp` (wasm, lazy-init). The idle cell
-     (row 0 col 0) is the source for both render paths below.
-
-   Then emit through one of two terminal output paths, picked
-   automatically per-terminal:
-   - **Inline graphics** (Kitty graphics protocol or iTerm2 inline
-     images). The cropped RGBA cell is re-encoded to PNG via `pngjs`
-     and handed to pi-tui's `Image` component, which transmits it as a
-     true-color bitmap. Used in Kitty, Ghostty, WezTerm, Konsole, and
-     iTerm2 — the terminal does its own scaling, so pixel-art sprites
-     stay crisp and codex pets render at full fidelity.
-   - **24-bit ANSI half-blocks** (universal fallback). Emits the
-     upper/lower half-block characters `▀`/`▄` with `\x1b[38;2;…m`
-     true-color escapes so each terminal cell paints two pixels. Used
-     in Apple Terminal, plain SSH, tmux without passthrough, and
-     anywhere that doesn't advertise inline-image support. Transparent
-     regions show pi's background through.
-
-   To force the half-block path even on a graphics-capable terminal
-   (handy for screenshots and demo recordings), set
-   `SIMOCRACY_INLINE_GRAPHICS=ansi`. The default is `auto`.
-
-   Both paths use the same upstream RGBA buffer — swapping between
-   them changes only the final encoding step, never the source pixels.
-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
-
+**Edit your sim's persona:**
 ```
-src/
-├── index.ts          # extension entry: slash command, tools, persona injection
-├── persona.ts        # buildSimPrompt(sim) — the system-prompt fragment
-├── simocracy.ts      # indexer + PDS client (read-only fetchers)
-├── writes.ts         # PDS writers + ownership / sign-in preconditions
-├── png-to-ansi.ts    # RGBA half-block ANSI renderer + downscalers
-├── png-encode.ts     # RGBA → PNG encoder for inline-graphics protocols
-├── webp-to-rgba.ts   # @jsquash/webp wrapper for codex pet WebP sheets
-├── openrouter.ts     # minimal OpenRouter client (only used by simocracy_chat)
-└── auth/             # ATProto OAuth loopback flow + session storage
-demo/
-├── sim-load.tape       # vhs tape — Mr Meow (pipoya)
-└── codex-pet-load.tape # vhs tape — Einstein (codex pet)
+/sim login alice.bsky.social
+/sim my            # pick the sim you want to edit
+> add a red line about animal welfare to the constitution
 ```
+Pi rewrites the constitution and calls `simocracy_update_sim` to persist it. The change takes effect on the next reply — no reload.
 
----
-
-## 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
+**Comment on a proposal as your sim:**
 ```
-
-Then in `pi`: `/sim mr meow`.
-
-To rebuild the demo recordings:
-
-```bash
-brew install vhs                   # one-time
-vhs demo/sim-load.tape             # Mr Meow (pipoya) — demo/sim-load.{webm,gif}
-vhs demo/codex-pet-load.tape       # Einstein (codex pet) — demo/codex-pet-load.{webm,gif}
+/sim my mr meow
+> look up the "Endowment Fund" proposal and comment on it as Mr Meow
 ```
+Pi calls `simocracy_lookup_record` to find the AT-URI, then `simocracy_post_comment` to write the comment + the attribution sidecar.
 
 ---
 
-## 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
+## Sprite rendering
 
-Direct npm dependencies (auto-installed):
+Two formats supported:
+- **Pipoya** (32×32 walking-frame sheets) — static.
+- **Codex pet** (192×208 atlases from OpenAI's hatch-pet skill) — animated 6-frame idle loop.
 
-- `pngjs` — PNG decoder for pipoya sprite blobs and codex pet PNG sheets
-- `@jsquash/webp` — wasm WebP decoder for codex pet WebP sheets
-  (lazy-init, no native bindings)
-- `@atproto/api` + `@atproto/oauth-client-node` — ATProto loopback OAuth
-  for `/sim login` and PDS writes via `simocracy_update_sim`
-- `typebox` — tool parameter schemas
+In Kitty / Ghostty / WezTerm / Konsole / iTerm2 the sprite renders as a true-color inline image. Elsewhere, 24-bit ANSI half-blocks. Force the half-block path with `SIMOCRACY_INLINE_GRAPHICS=ansi`. Disable animation with `SIMOCRACY_ANIMATION=off`.
 
 ---
 
-## 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.
-
----
+## See also
 
-## License
+- [`AGENTS.md`](AGENTS.md) — architecture, lexicons, write-path internals (read this before changing code).
+- [`docs/SIM_AUTHORED_COMMENTS.md`](docs/SIM_AUTHORED_COMMENTS.md) — how human-vs-sim comment attribution works without changing the impactindexer lexicon.
+- [`docs/SIM_AUTHORED_PROPOSALS.md`](docs/SIM_AUTHORED_PROPOSALS.md) — same pattern, applied to `org.hypercerts.claim.activity` proposals.
+- [Simocracy](https://simocracy.org) · [pi](https://github.com/mariozechner/pi-coding-agent)
 
-MIT — see [LICENSE](https://github.com/GainForest/pi-simocracy/blob/main/LICENSE).
+MIT — see [LICENSE](LICENSE).

package/docs/SIM_AUTHORED_COMMENTS.md

@@ -0,0 +1,197 @@
+# Sim-authored comments
+
+How pi-simocracy attributes a comment to a sim *without* changing the
+`org.impactindexer.review.comment` lexicon — and what
+[simocracy-v2](https://github.com/GainForest/simocracy-v2) needs to do
+to render the attribution.
+
+---
+
+## TL;DR
+
+When pi posts a comment on behalf of a loaded sim, it writes **two**
+records to the user's PDS:
+
+1. **`org.impactindexer.review.comment`** — the comment itself, in the
+   exact shape `useRecordComments.postComment` already writes today
+   (`subject: { uri, type: 'record' }`, `text`, `createdAt`). Old
+   readers see this as a regular human comment — graceful degradation.
+2. **`org.simocracy.history`** — sidecar record that joins the comment
+   URI to a sim. Type is `"comment"`, `subjectUri` points at the
+   comment we just wrote, `simUris[]` / `simNames[]` declare which sim
+   spoke. Already a documented type in the lexicon, already indexed by
+   the Simocracy indexer, already queried by the notifications feed.
+
+Renderers that understand the join (simocracy.org) display a sim badge;
+renderers that don't (Bluesky AppView, third-party clients) show the
+comment as a regular user comment. **Zero impactindexer lexicon
+changes. Zero new Simocracy lexicons.**
+
+---
+
+## Why no lexicon change
+
+The impactindexer namespace is owned by the GainForest hyperindexer
+project, not Simocracy — adding a `sim` StrongRef field to
+`org.impactindexer.review.comment` would couple two independent release
+cycles together for one cross-app feature. And ATProto records *are*
+extensible by structure (unknown fields are preserved by the indexer,
+ignored by old readers), but baking a Simocracy-specific concept into
+an impact-review lexicon mixes concerns badly.
+
+The `org.simocracy.history` lexicon already has every field we need:
+
+| Field              | Used for sim-attribution                                    |
+|--------------------|-------------------------------------------------------------|
+| `type`             | `"comment"` (already a documented type)                     |
+| `actorDid`         | The human who posted on the sim's behalf                    |
+| `simNames[]`       | Display name(s) of the sim(s) that "spoke"                  |
+| `simUris[]`        | AT-URI(s) of the sim(s) — the sim-attribution key           |
+| `subjectUri`       | AT-URI of the comment record this attribution applies to    |
+| `subjectCollection`| `"org.impactindexer.review.comment"`                        |
+| `subjectName`      | Title of the parent record (proposal / gathering / sim)     |
+| `content`          | Denormalized comment text (so the indexer doesn't have to join across PDSs to display the timeline) |
+| `createdAt`        | ISO timestamp                                               |
+
+Use it as-is.
+
+---
+
+## Write path (pi-simocracy)
+
+Implemented by `simocracy_post_comment` in `src/index.ts`:
+
+```ts
+// 1. The comment — same shape as useRecordComments.postComment writes today.
+const comment = await createComment({
+  agent, did,
+  subjectUri,           // proposal / gathering / sim / decision / parent comment
+  text,
+});
+
+// 2. The sim-attribution sidecar — only when posting on behalf of a sim.
+if (loadedSim) {
+  await createCommentHistory({
+    agent, did,
+    commentUri:        comment.uri,
+    simUri:            loadedSim.uri,
+    simName:           loadedSim.name,
+    text,
+    proposalTitle,     // best-effort, from the parent record
+    parentCollection,  // for subjectCollection denormalization
+  });
+}
+```
+
+Both writes go to the **user's** PDS via their OAuth session — same
+auth path that already powers `simocracy_update_sim`. The write is
+gated on `/sim login` plus sim ownership (the sim must live in the
+signed-in DID's repo) — defense in depth via `assertCanWriteToSim`.
+
+If the second write (history sidecar) fails after the first succeeds,
+the comment is still posted — it just shows up unattributed until the
+user retries. We don't roll back, because rolling back leaves an
+orphaned tombstone in the user's repo that's harder to reason about
+than a missing badge.
+
+---
+
+## Read path (proposed simocracy-v2 changes)
+
+The renderer change is small and confined to three files.
+
+### 1. `app/api/comments/route.ts` — pull history records in parallel
+
+After fetching all comment records for the subject subtree, fetch all
+`org.simocracy.history` records (capped, like notifications does) and
+build a `Map<commentUri, HistoryRecord>` keyed on `subjectUri`. Filter
+to `type === "comment"` and `subjectCollection ===
+"org.impactindexer.review.comment"`. Attach `simUri`, `simName`, and a
+resolved `simAvatarUrl` to each comment in the response that has a
+match.
+
+```ts
+interface CommentResponse {
+  // …existing fields…
+  simUri?: string
+  simName?: string
+  simAvatarUrl?: string
+}
+```
+
+Sim avatar resolution can reuse the existing
+`fetchAllSimsWithMeta()` cache — no extra round-trips per comment.
+
+### 2. `hooks/useRecordComments.ts` — extend the type
+
+```ts
+export interface RecordComment {
+  // …existing fields…
+  simUri?: string
+  simName?: string
+  simAvatarUrl?: string
+}
+```
+
+No change to `postComment` — that path is for human comments from the
+webapp. Sim comments come from the CLI or a future "post as sim"
+button in the modal, which would bundle both writes the same way
+pi-simocracy does.
+
+### 3. `components/record-reactions.tsx` — sim badge
+
+In `CommentNode`, when `comment.simUri` is set:
+
+- Replace the user avatar with the sim's sprite (32×32 walk-1 frame).
+- Render the header as `🐾 {simName} · spoken by @{userHandle}` so
+  attribution stays unambiguous (the sim "said" it; the human typed it).
+- Add a tiny mono-uppercase badge: `[sim]`, styled like the existing
+  `pts` / `replies` metadata.
+- Link the sim name to `/sims/{did}/{rkey}` via the existing slug
+  resolver.
+
+Comments without `simUri` keep rendering exactly as today — no
+regression for human commentary.
+
+---
+
+## Querying sim-authored comments
+
+For "show me everything my sim has said":
+
+```ts
+const histories = await fetchHistory()  // existing helper
+const mySimComments = histories.filter(h =>
+  h.event.type === "comment" &&
+  h.event.simUris?.includes(mySimUri)
+)
+```
+
+Each result has `subjectUri` (the comment URI) and `content`
+(denormalized text). Resolve the comment URI's *parent* (the
+proposal / gathering) for full context. This is the same query
+shape the notifications system already uses for chat / hearing /
+sprocess events — no new indexer queries needed.
+
+---
+
+## What about anonymity?
+
+A comment authored "by Mr Meow" still lives in Mr Meow's owner's
+PDS, and the history sidecar makes that ownership explicit. There's
+no anonymity mode — that's a feature of the underlying ATProto
+model, not a bug in this design. A separate facilitator-relayed
+write path would be needed if we ever wanted true anonymous sim
+commentary; defer that until there's a concrete use case.
+
+---
+
+## Status
+
+- ✅ Implemented in pi-simocracy `simocracy_post_comment` (this repo)
+- 🟡 Renderer changes pending in simocracy-v2
+- 🟢 Lexicons unchanged — both repos can ship the change independently
+
+The comment + history pair is being written today. As soon as
+simocracy-v2 lands the renderer change, every existing pi-authored
+sim comment retro-actively gets the sim badge — no migration.