pi-simocracy 0.6.1 → 0.6.2

package/README.md

@@ -69,6 +69,17 @@ Pi calls `simocracy_lookup_record` to find the AT-URI, then `simocracy_post_comm
 
 ---
 
+## Loaded-sim system prompt
+
+When a sim is loaded, pi injects the sim's identity, constitution, and speaking style into the system prompt every turn. On top of that, the persona prompt appends a **Simocracy navigation cheat-sheet** fetched live from [`simocracy.org/skill.md`](https://www.simocracy.org/skill.md) at sim-load time — that's where the URL patterns (`/sims/<did>/<rkey>`, `/profile/<handle>`, …), indexer endpoints, and recommended tool-routing live. simocracy.org is the single source of truth; this extension keeps no baked-in fallback. If the fetch fails (offline, simocracy.org down, route not yet deployed) the section is simply omitted — the sim still loads, it just lacks the navigation guidance until the URL becomes reachable.
+
+Override or disable:
+
+- `SIMOCRACY_SKILL_URL=…` — point at a staging URL (the route is also viewable in a browser).
+- `SIMOCRACY_SKILL_MD_DISABLED=1` — skip the fetch entirely (useful on metered connections / offline).
+
+---
+
 ## Sprite rendering
 
 Two formats supported:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-simocracy",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "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)",

package/src/index.ts

@@ -95,6 +95,7 @@ import {
   fetchAgentsForSim,
   fetchStyleForSim,
   fetchBlob,
+  fetchSkillMd,
   resolveHandle,
   parseAtUri,
   type AgentsRecord,
@@ -533,12 +534,14 @@ async function loadSimByName(query: string): Promise<{
 }
 
 async function hydrateLoadedSim(match: SimMatch): Promise<LoadedSim> {
-  // Fetch agents (constitution), style, sprite ANSI + handle in parallel.
-  const [agents, style, sprite, handle] = await Promise.all([
+  // Fetch agents (constitution), style, sprite ANSI, handle, and the
+  // simocracy.org navigation cheat-sheet in parallel.
+  const [agents, style, sprite, handle, skill] = await Promise.all([
     fetchAgentsForSim(match.uri).catch(() => null) as Promise<AgentsRecord | null>,
     fetchStyleForSim(match.uri).catch(() => null) as Promise<StyleRecord | null>,
     renderSprite(match).catch(() => null),
     resolveHandle(match.did).catch(() => null),
+    fetchSkillMd(),
   ]);
 
   return {
@@ -566,6 +569,8 @@ async function hydrateLoadedSim(match: SimMatch): Promise<LoadedSim> {
     shortDescription: agents?.shortDescription,
     description: agents?.description,
     style: style?.description,
+    skillMd: skill.text,
+    skillMdError: skill.text ? undefined : skill.error,
   };
 }
 

package/src/persona.ts

@@ -7,6 +7,8 @@
  * normal `/sim` chat and with the `simocracy_chat` tool.
  */
 
+import { getSimocracySkillUrl } from "./simocracy.ts";
+
 export interface LoadedSim {
   uri: string;
   did: string;
@@ -55,6 +57,16 @@ export interface LoadedSim {
     /** Native PNG height in pixels. */
     heightPx: number;
   };
+  /** Fetched contents of `https://www.simocracy.org/skill.md` at
+   *  sim-load time, when the fetch succeeded. Appended verbatim to
+   *  the persona prompt by `buildSimPrompt`. Kept on the sim so a
+   *  re-render or a future `simocracy_chat` call uses the same
+   *  content the original load used. */
+  skillMd?: string;
+  /** Reason the skill.md fetch did not run / failed, when relevant.
+   *  Stored only for diagnostics — never injected into the persona
+   *  prompt. Surface optionally via `/sim status`. */
+  skillMdError?: string;
 }
 
 /**
@@ -86,6 +98,20 @@ export function buildSimPrompt(sim: LoadedSim): string {
     lines.push(`## ${sim.name}'s speaking style`);
     lines.push(sim.style);
   }
+  if (sim.skillMd) {
+    lines.push(``);
+    lines.push(`## Simocracy navigation cheat-sheet`);
+    lines.push(
+      `Your specific simocracy.org page: https://www.simocracy.org/sims/${sim.did}/${sim.rkey}` +
+        (sim.handle ? `\nThe owner's profile: https://www.simocracy.org/profile/${sim.handle}` : ""),
+    );
+    lines.push(``);
+    lines.push(
+      `The block below is fetched from ${getSimocracySkillUrl()} on every sim-load and is the canonical reference for URL patterns, indexer endpoints, and common navigation workflows. Treat it as authoritative; when the user asks about you, your gatherings, your proposals, or what other sims have been saying, follow this guide.`,
+    );
+    lines.push(``);
+    lines.push(sim.skillMd);
+  }
   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.`,

package/src/simocracy.ts

@@ -345,3 +345,48 @@ export async function resolveHandle(did: string): Promise<string | null> {
 }
 
 export const SIMOCRACY_INDEXER_URL = DEFAULT_INDEXER_URL;
+
+const SIMOCRACY_SKILL_URL =
+  process.env.SIMOCRACY_SKILL_URL ?? "https://www.simocracy.org/skill.md";
+
+const SKILL_MD_FETCH_TIMEOUT_MS = 4000;
+const SKILL_MD_MAX_BYTES = 64 * 1024;
+
+/**
+ * Fetch the navigation cheat-sheet served at `simocracy.org/skill.md`.
+ * Never throws — returns either `{ text }` on success or `{ error }` on
+ * failure / disablement so the caller can record the diagnostic and
+ * fall through to the pre-change behaviour (no navigation guidance).
+ */
+export async function fetchSkillMd(): Promise<{ text?: string; error?: string }> {
+  if (process.env.SIMOCRACY_SKILL_MD_DISABLED === "1") {
+    return { error: "disabled by SIMOCRACY_SKILL_MD_DISABLED=1" };
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), SKILL_MD_FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(SIMOCRACY_SKILL_URL, {
+      signal: controller.signal,
+      headers: { Accept: "text/markdown, text/plain;q=0.5" },
+    });
+    if (!res.ok) {
+      return { error: `${res.status} ${res.statusText}` };
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    const trimmed =
+      buf.byteLength > SKILL_MD_MAX_BYTES
+        ? buf.slice(0, SKILL_MD_MAX_BYTES).toString("utf8") +
+          `\n\n<!-- truncated at ${SKILL_MD_MAX_BYTES} bytes -->`
+        : buf.toString("utf8");
+    return { text: trimmed };
+  } catch (err) {
+    return { error: (err as Error).message };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Exported for the persona prompt to mention the URL by name. */
+export function getSimocracySkillUrl(): string {
+  return SIMOCRACY_SKILL_URL;
+}