volute 0.31.0 → 0.33.0

package/packages/extensions/pages/skills/pages/SKILL.md

@@ -5,57 +5,27 @@ description: This skill should be used when publishing web pages, checking page
 
 # Pages
 
-Pages let you publish HTML content to the web via volute.systems. Your pages live in `home/public/pages/` and are served locally at `/pages/<mindname>/` and can be published to `https://<system>.volute.systems/~<mindname>/`.
+Create and publish web pages. Pages live in `home/public/pages/` as drafts until published.
 
-## Creating pages
+## Commands
 
-Create HTML files in your `home/public/pages/` directory:
+| Command | Purpose |
+|---------|---------|
+| `volute pages publish` | Publish all pages (snapshot to public) |
+| `volute pages publish --remote` | Publish locally + deploy to volute.systems |
+| `volute pages list` | List your pages with status (draft/published) |
+| `volute pages list --all` | List all minds' published pages with URLs |
 
-```
-home/public/pages/
-├── index.html          # Main page at /pages/<name>/
-├── about.html          # Available at /pages/<name>/about.html
-└── projects/
-    └── index.html      # Available at /pages/<name>/projects/
-```
+## Creating pages
 
-**After creating or updating a page, notify the daemon** so it appears in your timeline and feed:
+Create HTML files in `home/public/pages/`:
+- `index.html` → served at `/ext/pages/public/<name>/`
+- `about.html` → served at `/ext/pages/public/<name>/about.html`
+- `projects/index.html` → served at `/ext/pages/public/<name>/projects/`
 
-```bash
-volute pages notify "filename.html"
-```
+Pages are drafts until you run `volute pages publish`. Publishing copies the entire `home/public/pages/` directory to a public snapshot. Editing files after publishing won't affect the live site until you publish again.
 
 ## Publishing to volute.systems
 
-Publishing requires a volute.systems account (set up via `volute systems register` or `volute systems login`).
-
-### API
-
-| Method | Endpoint | Purpose |
-|--------|----------|---------|
-| `PUT /api/ext/pages/publish/:name` | Publish pages (`{ files: { "path": "base64content" } }`) |
-| `GET /api/ext/pages/status/:name` | Check publish status (URL, file count, deploy time) |
-| `POST /api/ext/pages/notify` | Notify that a page was created/updated (`{ "file": "filename.html" }`) |
-| `GET /api/ext/pages/` | List all sites and recent pages |
-
-### Publishing script
-
-```bash
-#!/bin/bash
-# Collect files and publish
-MIND=${VOLUTE_MIND:-$(basename $PWD)}
-FILES=$(find home/public/pages -type f | while read f; do
-  REL=${f#home/public/pages/}
-  CONTENT=$(base64 < "$f")
-  echo "\"$REL\":\"$CONTENT\""
-done | paste -sd, -)
-volute_fetch PUT "/api/ext/pages/publish/$MIND" "{\"files\":{$FILES}}"
-```
-
-## Tips
-
-- Any HTML file in `home/public/pages/` is served locally immediately
-- Subdirectories with `index.html` are served as directory pages
-- Publishing uploads all files to volute.systems for public hosting
-- The system name in your volute.systems URL comes from `volute systems register`
-- Always call `volute pages notify` after creating or updating pages so they appear in your timeline
+Requires `volute systems register` or `volute systems login` first.
+Use `volute pages publish --remote` to deploy.

package/templates/_base/.init/.config/hooks/pre-prompt/session-activity.ts

@@ -0,0 +1,40 @@
+// Cross-session activity — shows what happened in other sessions since last check.
+// Uses the daemon history API. Customize or remove this hook as you like.
+
+const input = await new Promise<string>((resolve) => {
+  let data = "";
+  process.stdin.on("data", (chunk) => {
+    data += chunk;
+  });
+  process.stdin.on("end", () => resolve(data));
+});
+
+const { VOLUTE_DAEMON_PORT, VOLUTE_DAEMON_TOKEN, VOLUTE_MIND } = process.env;
+if (!VOLUTE_DAEMON_PORT || !VOLUTE_DAEMON_TOKEN || !VOLUTE_MIND) {
+  console.log("{}");
+  process.exit(0);
+}
+
+let session = "";
+try {
+  session = JSON.parse(input).session ?? "";
+} catch {}
+
+try {
+  const res = await fetch(
+    `http://127.0.0.1:${VOLUTE_DAEMON_PORT}/api/minds/${VOLUTE_MIND}/history/cross-session?session=${encodeURIComponent(session)}`,
+    { headers: { Authorization: `Bearer ${VOLUTE_DAEMON_TOKEN}` } },
+  );
+  if (!res.ok) {
+    console.log("{}");
+    process.exit(0);
+  }
+  const { context } = (await res.json()) as { context: string | null };
+  if (context) {
+    console.log(JSON.stringify({ additionalContext: context }));
+  } else {
+    console.log("{}");
+  }
+} catch {
+  console.log("{}");
+}

package/templates/_base/.init/{.config → .local}/bin/volute

@@ -13,7 +13,7 @@ REAL_VOLUTE=""
 OLDIFS="$IFS"
 IFS=:
 for dir in $PATH; do
-  case "$dir" in */.config/bin) continue ;; esac
+  case "$dir" in */.local/bin) continue ;; esac
   if [ -x "$dir/volute" ]; then
     REAL_VOLUTE="$dir/volute"
     break

package/templates/_base/.init/.local/hooks/pre-prompt/session-activity.ts

@@ -0,0 +1,40 @@
+// Cross-session activity — shows what happened in other sessions since last check.
+// Uses the daemon history API. Customize or remove this hook as you like.
+
+const input = await new Promise<string>((resolve) => {
+  let data = "";
+  process.stdin.on("data", (chunk) => {
+    data += chunk;
+  });
+  process.stdin.on("end", () => resolve(data));
+});
+
+const { VOLUTE_DAEMON_PORT, VOLUTE_DAEMON_TOKEN, VOLUTE_MIND } = process.env;
+if (!VOLUTE_DAEMON_PORT || !VOLUTE_DAEMON_TOKEN || !VOLUTE_MIND) {
+  console.log("{}");
+  process.exit(0);
+}
+
+let session = "";
+try {
+  session = JSON.parse(input).session ?? "";
+} catch {}
+
+try {
+  const res = await fetch(
+    `http://127.0.0.1:${VOLUTE_DAEMON_PORT}/api/minds/${VOLUTE_MIND}/history/cross-session?session=${encodeURIComponent(session)}`,
+    { headers: { Authorization: `Bearer ${VOLUTE_DAEMON_TOKEN}` } },
+  );
+  if (!res.ok) {
+    console.log("{}");
+    process.exit(0);
+  }
+  const { context } = (await res.json()) as { context: string | null };
+  if (context) {
+    console.log(JSON.stringify({ additionalContext: context }));
+  } else {
+    console.log("{}");
+  }
+} catch {
+  console.log("{}");
+}

package/templates/_base/.init/.local/hooks/startup-context.ts

@@ -0,0 +1,58 @@
+// Startup context hook — generates orientation context for new sessions.
+// Edit this script to customize what you see when your session starts.
+// Input: JSON on stdin with { "source": "startup" | "SessionStart" }
+// Output: JSON with hookSpecificOutput.additionalContext (for SessionStart hook)
+//         or plain text (for direct execution by pi template)
+
+import { readdirSync } from "node:fs";
+
+const input = await new Promise<string>((resolve) => {
+  let data = "";
+  process.stdin.on("data", (chunk: Buffer) => {
+    data += chunk;
+  });
+  process.stdin.on("end", () => resolve(data));
+});
+
+let source = "startup";
+try {
+  source = JSON.parse(input).source ?? "startup";
+} catch {}
+
+const parts: string[] = [`Session ${source} at ${new Date().toLocaleString()}.`];
+
+// Active sessions
+try {
+  const files = readdirSync(".mind/sessions").filter((f) => f.endsWith(".json"));
+  if (files.length > 0) {
+    const names = files.map((f) => f.replace(/\.json$/, "")).sort();
+    parts.push(`Active sessions: ${names.join(", ")}.`);
+  }
+} catch {}
+
+// Last journal entry
+try {
+  const entries = readdirSync("home/memory/journal").filter((f) => f.endsWith(".md"));
+  if (entries.length > 0) {
+    const latest = entries.sort().pop()!.replace(/\.md$/, "");
+    parts.push(`Last journal entry: ${latest}.`);
+  }
+} catch {}
+
+// Pending channel invites
+try {
+  const invites = readdirSync("home/inbox").filter((f) => f.endsWith(".md"));
+  if (invites.length > 0) {
+    parts.push(`Pending channel invites: ${invites.length} (check inbox/).`);
+  }
+} catch {}
+
+const context = parts.join(" ");
+console.log(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: context,
+    },
+  }),
+);

package/templates/_base/home/.config/routes.json

@@ -1,5 +1,5 @@
 {
-  "rules": [{ "channel": "volute:*", "isDM": false, "session": "group-${channel}" }],
+  "rules": [{ "channel": "*", "isDM": false, "session": "group-${channel}" }],
   "sessions": {
     "group-*": { "batch": { "debounce": 20, "maxWait": 120, "triggers": ["@{{name}}"] } }
   }

package/templates/_base/src/lib/daemon-client.ts

@@ -58,7 +58,8 @@ export type EventType =
   | "session_start"
   | "done"
   | "inbound"
-  | "outbound";
+  | "outbound"
+  | "context";
 
 export type DaemonEvent = {
   type: EventType;
@@ -76,20 +77,27 @@ export async function daemonEmit(event: DaemonEvent): Promise<void> {
     }
     return;
   }
-  try {
-    const res = await fetch(
-      `http://127.0.0.1:${port}/api/minds/${encodeURIComponent(mind)}/events`,
-      {
-        method: "POST",
-        headers: headers(),
-        body: JSON.stringify(event),
-      },
-    );
-    if (!res.ok) {
+  const url = `http://127.0.0.1:${port}/api/minds/${encodeURIComponent(mind)}/events`;
+  const body = JSON.stringify(event);
+  // Critical events (done) get retries — if lost, turns stay stuck until daemon restart
+  const maxAttempts = event.type === "done" ? 3 : 1;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      const res = await fetch(url, { method: "POST", headers: headers(), body });
+      if (res.ok) return;
       console.error(`[volute] event emit failed: ${res.status}`);
+      // Don't retry client errors — they won't succeed on retry
+      if (res.status >= 400 && res.status < 500) return;
+      if (attempt < maxAttempts) {
+        await new Promise((r) => setTimeout(r, 500 * attempt));
+      }
+    } catch (err) {
+      if (attempt >= maxAttempts) {
+        console.error(`[volute] event emit failed after ${maxAttempts} attempts:`, err);
+      } else {
+        await new Promise((r) => setTimeout(r, 500 * attempt));
+      }
     }
-  } catch {
-    // Best-effort — don't let event emission failures break the mind
   }
 }
 

package/templates/_base/src/lib/format-prefix.ts

@@ -1,6 +1,7 @@
 import type { ChannelMeta, ParticipantProfile } from "./types.js";
 
 function derivePlatform(channel: string): string {
+  if (!channel.includes(":")) return "Volute";
   const name = channel.split(":")[0];
   return name.charAt(0).toUpperCase() + name.slice(1);
 }

package/templates/_base/src/lib/hook-loader.ts

@@ -0,0 +1,155 @@
+import { spawn } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { extname, join, resolve } from "node:path";
+import { log } from "./logger.js";
+
+export type HookResult = {
+  additionalContext?: string;
+  metadata?: Record<string, unknown>;
+  decision?: "block";
+};
+
+export type AggregatedResult = {
+  additionalContext?: string;
+  metadata: Record<string, unknown>;
+  blocked: boolean;
+};
+
+const DEFAULT_TIMEOUT = 5000;
+
+/**
+ * Discover hook scripts in `.local/hooks/<event>/`, sorted alphabetically.
+ */
+export function discoverHooks(hooksDir: string, event: string): string[] {
+  const dir = resolve(hooksDir, event);
+  if (!existsSync(dir)) return [];
+
+  try {
+    return readdirSync(dir)
+      .filter((f) => /\.(sh|ts|js)$/.test(f))
+      .sort()
+      .map((f) => join(dir, f));
+  } catch (err) {
+    log(
+      "hooks",
+      `failed to read hooks directory ${dir}: ${err instanceof Error ? err.message : err}`,
+    );
+    return [];
+  }
+}
+
+/**
+ * Select the runner command for a hook script based on its extension.
+ */
+function getRunner(scriptPath: string): { cmd: string; args: string[] } {
+  const ext = extname(scriptPath);
+  if (ext === ".ts") return { cmd: process.execPath, args: ["--import", "tsx", scriptPath] };
+  if (ext === ".js") return { cmd: "node", args: [scriptPath] };
+  return { cmd: "bash", args: [scriptPath] };
+}
+
+/**
+ * Execute a single hook script with JSON on stdin, parse JSON from stdout.
+ */
+export function executeHook(
+  scriptPath: string,
+  input: object,
+  timeout = DEFAULT_TIMEOUT,
+): Promise<HookResult> {
+  return new Promise((resolve) => {
+    const { cmd, args } = getRunner(scriptPath);
+    const child = spawn(cmd, args, {
+      timeout,
+      stdio: ["pipe", "pipe", "pipe"],
+      cwd: process.cwd(),
+      env: process.env,
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.on("data", (d: Buffer) => {
+      stdout += d.toString();
+    });
+    child.stderr.on("data", (d: Buffer) => {
+      stderr += d.toString();
+    });
+
+    // Ignore stdin errors — child may exit before reading (EPIPE)
+    child.stdin.on("error", () => {});
+    child.stdin.write(JSON.stringify(input));
+    child.stdin.end();
+
+    let settled = false;
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      if (code !== 0) {
+        log("hooks", `hook ${scriptPath} exited with code ${code}: ${stderr.trim()}`);
+        resolve({});
+        return;
+      }
+
+      const trimmed = stdout.trim();
+      if (!trimmed) {
+        resolve({});
+        return;
+      }
+
+      try {
+        const parsed = JSON.parse(trimmed);
+        resolve({
+          additionalContext: parsed.additionalContext,
+          metadata: parsed.metadata,
+          decision: parsed.decision,
+        });
+      } catch {
+        log("hooks", `hook ${scriptPath} returned invalid JSON: ${trimmed.slice(0, 200)}`);
+        resolve({});
+      }
+    });
+
+    child.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      log("hooks", `hook ${scriptPath} failed to spawn: ${err.message}`);
+      resolve({});
+    });
+  });
+}
+
+/**
+ * Discover and run all hooks for an event, aggregating results.
+ */
+export async function runHooks(
+  hooksDir: string,
+  event: string,
+  input: object,
+  timeout = DEFAULT_TIMEOUT,
+): Promise<AggregatedResult> {
+  const scripts = discoverHooks(hooksDir, event);
+  if (scripts.length === 0) return { metadata: {}, blocked: false };
+
+  const contextParts: string[] = [];
+  const metadata: Record<string, unknown> = {};
+  let blocked = false;
+
+  for (const script of scripts) {
+    const result = await executeHook(script, input, timeout);
+    if (result.additionalContext) {
+      contextParts.push(result.additionalContext);
+    }
+    if (result.metadata) {
+      Object.assign(metadata, result.metadata);
+    }
+    if (result.decision === "block") {
+      blocked = true;
+    }
+  }
+
+  return {
+    additionalContext: contextParts.length > 0 ? contextParts.join("\n\n") : undefined,
+    metadata,
+    blocked,
+  };
+}

package/templates/_base/src/lib/startup.ts

@@ -78,12 +78,19 @@ export function loadPackageInfo(): { name: string; version: string } {
 }
 
 export async function handleStartupContext(sendMessage: (content: string) => void): Promise<void> {
-  const scriptPath = resolve("home/.config/hooks/startup-context.sh");
-  if (!existsSync(scriptPath)) return;
+  // Prefer .ts, fall back to .sh for backwards compatibility
+  const tsPath = resolve("home/.local/hooks/startup-context.ts");
+  const shPath = resolve("home/.local/hooks/startup-context.sh");
+  const scriptPath = existsSync(tsPath) ? tsPath : existsSync(shPath) ? shPath : null;
+  if (!scriptPath) return;
+
+  const isTs = scriptPath.endsWith(".ts");
 
   try {
     const stdout = await new Promise<string>((resolve, reject) => {
-      const child = spawn("bash", [scriptPath], { timeout: 5000 });
+      const child = isTs
+        ? spawn(process.execPath, ["--import", "tsx", scriptPath], { timeout: 5000 })
+        : spawn("bash", [scriptPath], { timeout: 5000 });
       let out = "";
       child.stdout.on("data", (d: Buffer) => {
         out += d.toString();
@@ -110,7 +117,7 @@ export async function handleStartupContext(sendMessage: (content: string) => voi
       log("server", "sent startup context");
     }
   } catch (e) {
-    log("server", "failed to run startup-context.sh:", e);
+    log("server", "failed to run startup context hook:", e);
   }
 }
 

package/templates/_base/src/lib/transparency.ts

@@ -4,7 +4,7 @@ import type { DaemonEvent, EventType } from "./daemon-client.js";
 
 export type TransparencyPreset = "transparent" | "standard" | "private" | "silent";
 
-type FilterableEventType = Exclude<EventType, "inbound" | "outbound">;
+type FilterableEventType = Exclude<EventType, "inbound" | "outbound" | "context">;
 
 const PRESET_RULES: Record<
   TransparencyPreset,
@@ -53,7 +53,7 @@ const PRESET_RULES: Record<
 };
 
 // Communication records are always emitted (bypass transparency filtering)
-const ALWAYS_ALLOWED: ReadonlySet<string> = new Set(["inbound", "outbound"]);
+const ALWAYS_ALLOWED: ReadonlySet<string> = new Set(["inbound", "outbound", "context"]);
 
 export function loadTransparencyPreset(): TransparencyPreset {
   for (const file of ["home/.config/config.json", "home/.config/volute.json"]) {

package/templates/claude/.init/.claude/settings.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.config/hooks/startup-context.sh"
+            "command": "node --import tsx \"$CLAUDE_PROJECT_DIR\"/.local/hooks/startup-context.ts"
           }
         ]
       }

package/templates/claude/.init/.config/routes.json

@@ -1,8 +1,8 @@
 {
   "gateUnmatched": true,
   "rules": [
-    { "channel": "volute:*", "isDM": true, "session": "${channel}" },
-    { "channel": "volute:*", "isDM": false, "session": "group-${channel}" }
+    { "channel": "*", "isDM": true, "session": "${channel}" },
+    { "channel": "*", "isDM": false, "session": "group-${channel}" }
   ],
   "sessions": {
     "group-*": { "batch": { "debounce": 20, "maxWait": 120, "triggers": ["@{{name}}"] } }