@aexol/spectral 0.7.0 → 0.7.1

package/dist/designer/systems.js

@@ -0,0 +1,216 @@
+/**
+ * Design System Registry — 150+ Curated Systems from Open Design
+ *
+ * Design systems are stored as DESIGN.md + tokens.css files under
+ * data/systems/<name>/. At import time, we scan the directory and
+ * parse each system's metadata (name, category, description) from
+ * the DESIGN.md frontmatter. Full content is lazily loaded on first
+ * access and cached.
+ *
+ * The tool interface remains the same as the original systems.ts:
+ *   findSystem(name)  → DesignSystem | undefined
+ *   formatSystemForLLM(system) → string
+ *   listSystemsForLLM() → string
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// ---------------------------------------------------------------------------
+// Discovery — build the registry from data/systems/
+// ---------------------------------------------------------------------------
+/** The directory containing design system data. We try multiple paths to
+ *  handle both dev (src/) and production (dist/) layouts. */
+function discoverDataDir() {
+    // Production: __dirname is dist/designer/, data is dist/designer/data/systems/
+    const prodPath = resolve(__dirname, "data", "systems");
+    if (existsSync(prodPath))
+        return prodPath;
+    // Both dev (src/designer/) and production (dist/designer/) layouts resolve the same way
+    return prodPath;
+}
+function parseCategory(line) {
+    const m = /Category:\s*(.+)/i.exec(line);
+    return m ? m[1].trim() : "Uncategorised";
+}
+function parseName(h1) {
+    return h1
+        .replace(/^#\s*Design System Inspired by\s*/i, "")
+        .replace(/^#\s*/i, "")
+        .trim();
+}
+function parseDescription(lines) {
+    // Take the first non-empty, non-heading, non-bracket line after the header
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith(">"))
+            continue;
+        // Take up to 120 chars for the description
+        return trimmed.length > 120 ? trimmed.slice(0, 117) + "..." : trimmed;
+    }
+    return "Design system from the Open Design registry.";
+}
+function buildRegistry() {
+    const map = new Map();
+    const baseDir = discoverDataDir();
+    if (!existsSync(baseDir)) {
+        process.stderr.write(`[designer] Design system data directory not found at ${baseDir}\n`);
+        return map;
+    }
+    let entries;
+    try {
+        entries = readdirSync(baseDir, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name);
+    }
+    catch {
+        process.stderr.write(`[designer] Cannot read design system directory ${baseDir}\n`);
+        return map;
+    }
+    for (const name of entries) {
+        const dir = resolve(baseDir, name);
+        const mdPath = resolve(dir, "DESIGN.md");
+        const cssPath = resolve(dir, "tokens.css");
+        if (!existsSync(mdPath))
+            continue;
+        let designMd;
+        try {
+            designMd = readFileSync(mdPath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const mdLines = designMd.split("\n");
+        // Extract metadata from the first heading lines
+        let h1Line = "";
+        let categoryLine = "";
+        const bodyLines = [];
+        for (const line of mdLines) {
+            const t = line.trim();
+            if (!h1Line && t.startsWith("# "))
+                h1Line = t;
+            else if (!categoryLine && t.startsWith("> Category:"))
+                categoryLine = t;
+            else
+                bodyLines.push(line);
+        }
+        const parsedName = parseName(h1Line || `# ${name}`);
+        const category = parseCategory(categoryLine);
+        const description = parseDescription(bodyLines);
+        let tokensCss = "";
+        if (existsSync(cssPath)) {
+            try {
+                tokensCss = readFileSync(cssPath, "utf-8");
+            }
+            catch {
+                // tokens optional
+            }
+        }
+        let componentsHtml = "";
+        const compPath = resolve(dir, "components.html");
+        if (existsSync(compPath)) {
+            try {
+                componentsHtml = readFileSync(compPath, "utf-8");
+            }
+            catch {
+                // components optional
+            }
+        }
+        map.set(parsedName.toLowerCase(), {
+            name: parsedName,
+            category,
+            description,
+            designMd,
+            tokensCss,
+            componentsHtml,
+        });
+    }
+    return map;
+}
+// ---------------------------------------------------------------------------
+// Registry singleton
+// ---------------------------------------------------------------------------
+let _registry = null;
+function registry() {
+    if (!_registry)
+        _registry = buildRegistry();
+    return _registry;
+}
+// ---------------------------------------------------------------------------
+// Lookup
+// ---------------------------------------------------------------------------
+export function findSystem(name) {
+    const lower = name.toLowerCase().trim();
+    const reg = registry();
+    // Exact match
+    if (reg.has(lower))
+        return reg.get(lower);
+    // Prefix / fuzzy match
+    for (const [key, sys] of reg) {
+        if (key.startsWith(lower) || key.includes(lower))
+            return sys;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// LLM formatters
+// ---------------------------------------------------------------------------
+/**
+ * Format a single design system for the LLM.
+ * Concatenates the DESIGN.md and tokens.css for a complete picture.
+ */
+export function formatSystemForLLM(system) {
+    const parts = [system.designMd];
+    if (system.tokensCss) {
+        parts.push("\n---\n## CSS Custom Properties (tokens.css)\n");
+        parts.push("```css");
+        parts.push(system.tokensCss);
+        parts.push("```");
+    }
+    if (system.componentsHtml) {
+        parts.push("\n---\n## Component Examples (components.html)\n");
+        parts.push(system.componentsHtml);
+    }
+    parts.push("\n---\n", "## How to Use This System\n", "1. Copy the `:root { ... }` block from tokens.css into your `<style>` block.", "2. Reference tokens as `var(--bg)`, `var(--fg)`, `var(--accent)`, `var(--font-body)`, etc.", "3. Follow the component styling guidelines from the DESIGN.md sections.", "4. Use the component examples as concrete starting points — adapt colors and fonts to the active design system.", "5. Apply typography rules: font families, sizes, and line-heights from the tokens.");
+    return parts.join("\n");
+}
+/**
+ * List all available design systems as a compact markdown table for the LLM.
+ */
+export function listSystemsForLLM() {
+    const reg = registry();
+    const all = [...reg.values()];
+    // Group by category
+    const byCategory = new Map();
+    for (const sys of all) {
+        const cat = sys.category;
+        if (!byCategory.has(cat))
+            byCategory.set(cat, []);
+        byCategory.get(cat).push(sys);
+    }
+    const lines = [
+        `# Available Design Systems (${all.length} total)`,
+        "",
+        "Grouped by category. Use `designer_get_system` with the system **name** to load full tokens and guidelines.",
+        "",
+    ];
+    for (const [category, systems] of [...byCategory].sort((a, b) => a[0].localeCompare(b[0]))) {
+        systems.sort((a, b) => a.name.localeCompare(b.name));
+        lines.push(`## ${category}`);
+        lines.push("");
+        for (const s of systems) {
+            lines.push(`- **${s.name}** — ${s.description}`);
+        }
+        lines.push("");
+    }
+    // Quick-select list at the end
+    lines.push("---");
+    lines.push("");
+    lines.push("Quick reference (all system names, one per line):");
+    lines.push("");
+    const sorted = [...all].sort((a, b) => a.name.localeCompare(b.name));
+    for (const s of sorted) {
+        lines.push(`- ${s.name}`);
+    }
+    return lines.join("\n");
+}

package/dist/server/pi-bridge.js

@@ -51,10 +51,12 @@
 import { createJiti } from "@mariozechner/jiti";
 import { AuthStorage, createAgentSession, DefaultResourceLoader, ModelRegistry, SessionManager, } from "@mariozechner/pi-coding-agent";
 import { randomUUID } from "node:crypto";
-import { existsSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import aexolMcpExtension from "../extensions/aexol-mcp.js";
+import subagentExt from "../agent/index.js";
+import designerExtension from "../designer/index.js";
 import observationalMemory from "../memory/index.js";
 import { Runtime } from "../memory/runtime.js";
 import { OBSERVATIONAL_MEMORY_CONTEXT_CUSTOM_TYPE, OBSERVATIONAL_MEMORY_SNAPSHOT_CUSTOM_TYPE, } from "../memory/types.js";
@@ -73,6 +75,37 @@ import { fetchAllowedModels as defaultFetchAllowedModels, } from "../relay/model
 const SPECTRAL_PROXY_ANTHROPIC = "spectral-proxy-anthropic";
 const SPECTRAL_PROXY_OPENAI = "spectral-proxy-openai";
 const SPECTRAL_PROXY_USER_MODEL = "spectral-proxy-user-model";
+/**
+ * Walk ancestor directories from `cwd` up to the filesystem root, collecting
+ * any existing skill directories at the given relative paths (e.g.
+ * `.opencode/skills` or `.aexol/skills`).
+ *
+ * Directories are returned in order from the deepest ancestor to `cwd` so
+ * project-local skills override ancestor-level ones when there are name
+ * collisions (pi's skill loader keeps the first found).
+ */
+function collectAncestorSkillDirs(cwd, relativePaths) {
+    const found = [];
+    let dir = resolve(cwd);
+    while (true) {
+        for (const rel of relativePaths) {
+            const candidate = join(dir, rel);
+            try {
+                if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+                    found.push(candidate);
+                }
+            }
+            catch {
+                // skip permission errors etc.
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return found;
+}
 /**
  * Concatenate text from an `AssistantMessage.content` array. Returns the
  * empty string when no text blocks are present (tool-only turns) or when
@@ -356,7 +389,7 @@ export class PiBridge {
     async start() {
         if (this.disposed)
             throw new Error("PiBridge already disposed");
-        const extensionFactories = [aexolMcpExtension, async (pi) => { observationalMemory(pi); }];
+        const extensionFactories = [aexolMcpExtension, async (pi) => { subagentExt(pi); }, async (pi) => { designerExtension(pi); }, async (pi) => { observationalMemory(pi); }];
         // Load pi-mcp-adapter via jiti so tsc never crawls its .ts files in
         // node_modules. The static `import` was causing tsc to type-check
         // pi-mcp-adapter's source and fail the build on its type errors.
@@ -380,15 +413,22 @@ export class PiBridge {
         // ResourceLoader with extensions wired in via factories.
         // Each factory's signature `(pi: ExtensionAPI) => Promise<void>` matches
         // the ExtensionFactory type exactly, so we can pass them directly.
+        //
+        // Skill discovery: pi's defaults scan ~/.pi/agent/skills/ (user),
+        // .pi/skills/ (project via CONFIG_DIR_NAME), and .agents/skills/
+        // (ancestor-walked). We additionally walk ancestors for
+        // .opencode/skills and .aexol/skills so OpenCode/Codex/Aexol skills
+        // work out of the box.
+        const extraSkillPaths = collectAncestorSkillDirs(this.opts.cwd, [".opencode/skills", ".aexol/skills"]);
         const resourceLoader = new DefaultResourceLoader({
             cwd: this.opts.cwd,
             agentDir: this.opts.agentDir ?? `${process.env.HOME ?? ""}/.pi/agent`,
             extensionFactories,
-            // Skip on-disk extension/skill discovery so the server is self-contained.
             noExtensions: false,
-            noSkills: true,
+            noSkills: false,
             noPromptTemplates: true,
             noThemes: true,
+            additionalSkillPaths: extraSkillPaths,
         });
         await resourceLoader.reload();
         // In-memory session: SQLite is our source of truth.
@@ -1029,6 +1069,27 @@ export class PiBridge {
                 return;
             }
             case "tool_execution_start": {
+                // Emit subagent_start for subagent tool invocations (Option B frontend panels).
+                if (ev.toolName === "subagent") {
+                    const args = ev.args;
+                    const mode = args?.chain?.length > 0 ? "chain"
+                        : args?.tasks?.length > 0 ? "parallel"
+                            : "single";
+                    const se = {
+                        type: "subagent_start",
+                        toolCallId: ev.toolCallId,
+                        mode,
+                        agent: typeof args?.agent === "string" ? args.agent : undefined,
+                        task: typeof args?.task === "string" ? args.task : undefined,
+                        taskCount: mode === "chain"
+                            ? args?.chain?.length
+                            : mode === "parallel"
+                                ? args?.tasks?.length
+                                : undefined,
+                        totalSteps: mode === "chain" ? args?.chain?.length : undefined,
+                    };
+                    this.emitAndBuffer(se);
+                }
                 this.emitAndBuffer({
                     type: "tool_call",
                     messageId: this.pending?.messageId ?? "",
@@ -1038,7 +1099,96 @@ export class PiBridge {
                 });
                 return;
             }
+            case "tool_execution_update": {
+                // Emit subagent_progress for subagent tool updates.
+                if (ev.toolName === "subagent") {
+                    const partialResult = ev.partialResult;
+                    const details = partialResult?.details;
+                    if (details?.results) {
+                        const mode = (details.mode ?? "single");
+                        const total = details.results.length;
+                        const done = details.results.filter(r => r.exitCode !== undefined && r.exitCode !== -1).length;
+                        const running = total - done;
+                        const currentAgent = details.results.find(r => r.exitCode === -1 || r.exitCode === undefined)?.agent;
+                        const se = {
+                            type: "subagent_progress",
+                            toolCallId: ev.toolCallId,
+                            mode,
+                            completedCount: done,
+                            totalCount: total,
+                            currentStep: mode === "chain" ? details.results[details.results.length - 1]?.step : undefined,
+                            currentAgent,
+                            message: mode === "parallel"
+                                ? `Parallel: ${done}/${total} done, ${running} running`
+                                : mode === "chain"
+                                    ? `Chain: step ${details.results.length}/${total}`
+                                    : `Running ${currentAgent ?? "subagent"}...`,
+                        };
+                        try {
+                            this.opts.emit(se);
+                        }
+                        catch { /* best-effort */ }
+                    }
+                }
+                return;
+            }
             case "tool_execution_end": {
+                // Emit subagent_end for subagent tool completions.
+                if (ev.toolName === "subagent") {
+                    const result = ev.result;
+                    const details = result?.details;
+                    if (details?.results && details.results.length > 0) {
+                        const mode = (details.mode ?? "single");
+                        const getOutput = (msgs) => {
+                            if (!msgs)
+                                return "(no output)";
+                            for (let i = msgs.length - 1; i >= 0; i--) {
+                                if (msgs[i].role === "assistant") {
+                                    for (const part of msgs[i].content) {
+                                        if (part.type === "text" && part.text)
+                                            return part.text;
+                                    }
+                                }
+                            }
+                            return "(no output)";
+                        };
+                        const results = details.results.map(r => ({
+                            agent: r.agent,
+                            agentSource: r.agentSource ?? "unknown",
+                            task: r.task,
+                            exitCode: r.exitCode,
+                            output: getOutput(r.messages),
+                            model: r.model,
+                            errorMessage: r.errorMessage,
+                            stopReason: r.stopReason,
+                            step: r.step,
+                            usage: {
+                                inputTokens: r.usage?.input ?? 0,
+                                outputTokens: r.usage?.output ?? 0,
+                                cacheReadTokens: r.usage?.cacheRead ?? 0,
+                                cacheWriteTokens: r.usage?.cacheWrite ?? 0,
+                                cost: r.usage?.cost ?? 0,
+                                turns: r.usage?.turns ?? 0,
+                            },
+                        }));
+                        const totalUsage = results.reduce((acc, r) => ({
+                            inputTokens: acc.inputTokens + r.usage.inputTokens,
+                            outputTokens: acc.outputTokens + r.usage.outputTokens,
+                            cacheReadTokens: acc.cacheReadTokens + r.usage.cacheReadTokens,
+                            cacheWriteTokens: acc.cacheWriteTokens + r.usage.cacheWriteTokens,
+                            cost: acc.cost + r.usage.cost,
+                            turns: acc.turns + r.usage.turns,
+                        }), { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, cost: 0, turns: 0 });
+                        const se = {
+                            type: "subagent_end",
+                            toolCallId: ev.toolCallId,
+                            mode,
+                            results,
+                            totalUsage,
+                        };
+                        this.emitAndBuffer(se);
+                    }
+                }
                 this.emitAndBuffer({
                     type: "tool_result",
                     messageId: this.pending?.messageId ?? "",

package/dist/server/session-stream.js

@@ -1130,8 +1130,30 @@ export class SessionStreamManager {
         }
         // Track compaction lifecycle so prompt() can block new messages while
         // compaction is running.
+        //
+        // Persist synthetic system messages so historic session replay (reconnect,
+        // page refresh) shows compaction events in the message timeline. These are
+        // broadcast live to connected subscribers AND persisted, so both live and
+        // historic sessions see them.
         if (event.type === "compaction_start") {
             stream.compacting = true;
+            const reasonLabel = event.reason === "manual"
+                ? "Manual compaction"
+                : event.reason === "overflow"
+                    ? "Context overflow"
+                    : "Context threshold";
+            const sysMsg = `${reasonLabel} — compacting conversation context…`;
+            try {
+                this.store.appendMessage(stream.sessionId, {
+                    role: "system",
+                    content: sysMsg,
+                    eventsJsonl: "",
+                    createdAt: Date.now(),
+                });
+            }
+            catch {
+                // best-effort; never block the stream on persistence
+            }
         }
         if (event.type === "compaction_end") {
             stream.compacting = false;
@@ -1139,6 +1161,25 @@ export class SessionStreamManager {
                 prunePersistedHistoryAfterCompaction(this.store, stream.sessionId, stream.bridge);
             }
             persistObservationalMemorySnapshot(this.store, stream.sessionId, stream.bridge);
+            const tokensMsg = typeof event.tokensBefore === "number"
+                ? ` (from ~${event.tokensBefore.toLocaleString()} tokens)`
+                : "";
+            const sysMsg = event.aborted
+                ? "Compaction aborted."
+                : event.summary
+                    ? `Compaction complete${tokensMsg}. Summary: ${event.summary}`
+                    : `Compaction complete${tokensMsg}.`;
+            try {
+                this.store.appendMessage(stream.sessionId, {
+                    role: "system",
+                    content: sysMsg,
+                    eventsJsonl: "",
+                    createdAt: Date.now(),
+                });
+            }
+            catch {
+                // best-effort
+            }
         }
         this.broadcast(stream, event);
         if (event.type === "agent_end") {
@@ -1378,7 +1419,10 @@ function isReplayable(event) {
         event.type === "tool_result" ||
         event.type === "message_end" ||
         event.type === "token_usage" ||
-        event.type === "error");
+        event.type === "error" ||
+        event.type === "subagent_start" ||
+        event.type === "subagent_progress" ||
+        event.type === "subagent_end");
 }
 function snapshotTurn(turn) {
     // Defensive copy of the events array so the snapshot can't be mutated by

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexol/spectral",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Always-on coding agent for Aexol — branded pi wrapper with relay-based browser access.",
   "type": "module",
   "private": false,