@aexol/spectral 0.0.1

package/dist/server/title-generator.js

@@ -0,0 +1,196 @@
+/**
+ * Auto-titler for sessions whose title is still the default
+ * ("New conversation" / null / empty).
+ *
+ * Strategy:
+ *   - After the first assistant turn completes (agent_end), the session-stream
+ *     manager fires `generateAndPersistTitle` once per session per server
+ *     lifetime. We track attempted ids in `SessionStreamManager` so a second
+ *     message in the same session never retriggers.
+ *   - Title generation itself is a one-shot LLM call. To keep the prod path
+ *     decoupled from tests, the call is injectable via the `llmCall`
+ *     dependency. The default implementation spawns a one-off pi
+ *     `AgentSession` with `noTools: "all"`, sends the prompt, and accumulates
+ *     `text_delta` events until `agent_end`. This reuses every bit of pi's
+ *     auth + model selection without introducing a new SDK code path.
+ *   - All failures are swallowed: log a warning and leave the title alone.
+ *     The caller's stream is never affected — title gen runs fire-and-forget.
+ *
+ * Sanitization rules (applied after the LLM responds):
+ *   - Trim whitespace
+ *   - Strip surrounding quotes (`"…"`, `'…'`, `“…”`)
+ *   - Take only the first non-empty line
+ *   - Drop trailing punctuation (`.`, `,`, `!`, `?`, `;`, `:`)
+ *   - Truncate to 60 characters
+ *
+ * Edge cases:
+ *   - Empty assistant message (e.g. only tool calls) → fall back to using the
+ *     user message alone for the prompt; if that's also empty, skip.
+ *   - LLM returns empty string after sanitization → return null, skip rename.
+ */
+import { createAgentSession, SessionManager, } from "@mariozechner/pi-coding-agent";
+const DEFAULT_TITLES = new Set(["New conversation", "", "Untitled"]);
+export const SESSION_TITLE_DEFAULT = "New conversation";
+/** True if `title` looks like the auto-generated default and is fair game. */
+export function isDefaultTitle(title) {
+    if (title == null)
+        return true;
+    return DEFAULT_TITLES.has(title.trim());
+}
+/**
+ * Sanitize raw LLM output into a usable session title.
+ * Returns `null` if nothing usable remains.
+ */
+export function sanitizeTitle(raw) {
+    if (!raw)
+        return null;
+    // First non-empty line.
+    const firstLine = raw
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    if (!firstLine)
+        return null;
+    let out = firstLine;
+    // Strip surrounding quote pairs.
+    const quotePairs = [
+        ['"', '"'],
+        ["'", "'"],
+        ["\u201C", "\u201D"], // “ ”
+        ["\u2018", "\u2019"], // ‘ ’
+        ["`", "`"],
+    ];
+    for (const [open, close] of quotePairs) {
+        if (out.startsWith(open) && out.endsWith(close) && out.length >= 2) {
+            out = out.slice(open.length, out.length - close.length).trim();
+            break;
+        }
+    }
+    // Drop trailing punctuation.
+    out = out.replace(/[.,!?;:]+$/u, "").trim();
+    // Truncate.
+    if (out.length > 60)
+        out = out.slice(0, 60).trim();
+    if (!out)
+        return null;
+    return out;
+}
+/**
+ * Build the prompt sent to the LLM. Truncates the assistant message body so
+ * a long answer doesn't blow out the context window of a tiny title model.
+ */
+export function buildTitlePrompt(firstUserMessage, firstAssistantMessage) {
+    const userText = firstUserMessage.trim();
+    const assistantText = firstAssistantMessage.trim().slice(0, 500);
+    const lines = [
+        "Generate a short title (4-6 words, no quotes, no trailing punctuation) for this conversation.",
+        "Respond with ONLY the title — no preamble, no explanation, no quotes.",
+        "",
+        `User: ${userText}`,
+    ];
+    if (assistantText)
+        lines.push("", `Assistant: ${assistantText}`);
+    lines.push("", "Title:");
+    return lines.join("\n");
+}
+/**
+ * Generate a sanitized title for a conversation, or `null` if generation
+ * failed / produced nothing usable.
+ */
+export async function generateSessionTitle(firstUserMessage, firstAssistantMessage, opts) {
+    const trimmedUser = firstUserMessage.trim();
+    if (!trimmedUser) {
+        // Nothing to summarize — pi was driven by an empty user turn (shouldn't
+        // happen via the wire path, but be defensive).
+        return null;
+    }
+    const prompt = buildTitlePrompt(trimmedUser, firstAssistantMessage);
+    const llmCall = opts.llmCall ?? defaultLlmCall(opts);
+    try {
+        const raw = await llmCall(prompt);
+        return sanitizeTitle(raw);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`[spectral] warn: title generation failed: ${msg}`);
+        return null;
+    }
+}
+/**
+ * Default LLM call: spawn a one-off pi `AgentSession` with no tools, send the
+ * prompt, and accumulate `text_delta`s until `agent_end`. Disposes the session
+ * on completion (or failure).
+ *
+ * This deliberately reuses pi's existing model/auth resolution so the user
+ * doesn't have to configure an extra API key just for title generation. The
+ * downside is a slightly heavier code path than calling an LLM SDK directly;
+ * the upside is zero new auth surface.
+ */
+function defaultLlmCall(opts) {
+    return async (prompt) => {
+        const { session } = await createAgentSession({
+            cwd: opts.cwd,
+            agentDir: opts.agentDir,
+            sessionManager: SessionManager.inMemory(opts.cwd),
+            noTools: "all",
+        });
+        let text = "";
+        let resolveDone;
+        let rejectDone;
+        const done = new Promise((resolve, reject) => {
+            resolveDone = resolve;
+            rejectDone = reject;
+        });
+        const unsubscribe = session.subscribe((ev) => {
+            if (ev.type === "message_update") {
+                const inner = ev.assistantMessageEvent;
+                if (inner.type === "text_delta")
+                    text += inner.delta;
+            }
+            else if (ev.type === "agent_end") {
+                resolveDone();
+            }
+        });
+        try {
+            // `prompt` resolves when the turn ends; `agent_end` should already
+            // have fired by then but we double-await for safety.
+            await session.prompt(prompt);
+            // In the event prompt() resolves before agent_end (defensive), wait a
+            // microtask to let the listener flush.
+            await Promise.race([
+                done,
+                new Promise((r) => setTimeout(r, 0)).then(() => undefined),
+            ]);
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            try {
+                unsubscribe();
+            }
+            catch {
+                /* ignore */
+            }
+            try {
+                session.dispose();
+            }
+            catch {
+                /* ignore */
+            }
+            rejectDone(e);
+            throw e;
+        }
+        try {
+            unsubscribe();
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            session.dispose();
+        }
+        catch {
+            /* ignore */
+        }
+        return text;
+    };
+}

package/dist/server/wire.js

@@ -0,0 +1,12 @@
+/**
+ * WebSocket wire protocol types shared between the spectral local server and
+ * the (future) browser client in `landing/`.
+ *
+ * Keep this file dependency-free. It will be copied or imported by the
+ * frontend in Day 3, so we don't want it to drag in `better-sqlite3`,
+ * `ws`, or any pi SDK types.
+ *
+ * Naming: client → server messages are `ClientMessage`, server → client
+ * frames are `ServerEvent`. JSON-encoded one-per-frame on the wire.
+ */
+export {};

package/dist/studio-binding.js

@@ -0,0 +1,97 @@
+/**
+ * Studio Binding utilities.
+ *
+ * Read/write/delete `.aexol/aexol.jsonc` — the local file that links a
+ * repository directory to an Aexol Studio project.
+ */
+import { readFile, writeFile, mkdir, unlink, access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { join } from "node:path";
+const BINDING_DIR = ".aexol";
+const BINDING_FILE = "aexol.jsonc";
+function bindingDir() {
+    return join(process.cwd(), BINDING_DIR);
+}
+function bindingPath() {
+    return join(bindingDir(), BINDING_FILE);
+}
+/**
+ * Strip JSONC comments (// line and /* block *​/) from raw source text.
+ * Kept simple — the binding file shape is well-known.
+ */
+export function stripJsoncComments(raw) {
+    return raw
+        .replace(/\/\*[\s\S]*?\*\//g, "") // block comments
+        .replace(/^\s*\/\/.*$/gm, ""); // line comments (standalone lines only)
+}
+/**
+ * Read and parse the local Studio binding file.
+ * Returns `null` when no binding file exists (file missing, or directory
+ * absent — treated the same way: not bound).
+ */
+export async function readStudioBinding() {
+    try {
+        const raw = await readFile(bindingPath(), "utf8");
+        return JSON.parse(stripJsoncComments(raw));
+    }
+    catch (err) {
+        const code = err.code;
+        // Missing file or missing directory → not bound.
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return null;
+        throw err;
+    }
+}
+/**
+ * Read and parse the Studio binding file at an arbitrary project path.
+ * Works like `readStudioBinding()` but reads from `projectPath/.aexol/aexol.jsonc`
+ * instead of `process.cwd()`.
+ */
+export async function readStudioBindingAt(projectPath) {
+    try {
+        const raw = await readFile(join(projectPath, BINDING_DIR, BINDING_FILE), "utf8");
+        return JSON.parse(stripJsoncComments(raw));
+    }
+    catch (err) {
+        const code = err.code;
+        // Missing file or missing directory → not bound.
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return null;
+        throw err;
+    }
+}
+/**
+ * Persist a Studio binding. Creates `.aexol/` if it does not exist.
+ */
+export async function writeStudioBinding(binding) {
+    const dir = bindingDir();
+    try {
+        await access(dir, constants.F_OK);
+    }
+    catch {
+        await mkdir(dir, { recursive: true });
+    }
+    const content = `// Aexol Studio Binding\n` +
+        `// Links this repository to a Studio project.\n` +
+        `// Schema: https://aexol.ai/schemas/studio-binding.json\n` +
+        `\n` +
+        JSON.stringify(binding, null, 2) +
+        "\n";
+    await writeFile(bindingPath(), content, "utf8");
+}
+/**
+ * Remove the local Studio binding file.
+ * Returns `true` when the file existed and was deleted, `false` otherwise (no-op).
+ */
+export async function deleteStudioBinding() {
+    try {
+        await unlink(bindingPath());
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return false;
+        throw err;
+    }
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@aexol/spectral",
+  "version": "0.0.1",
+  "description": "Always-on coding agent for Aexol — branded pi wrapper with relay-based browser access.",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "spectral": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && node scripts/postbuild.mjs",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "aexol",
+    "spectral",
+    "coding-agent",
+    "ai",
+    "cli",
+    "pi",
+    "claude",
+    "openai",
+    "agent",
+    "relay"
+  ],
+  "homepage": "https://aexol.com",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.aexol.com/aexol/spectral.git",
+    "directory": "cli-node"
+  },
+  "bugs": {
+    "url": "https://gitlab.aexol.com/aexol/spectral/-/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.2.0",
+    "@mariozechner/pi-coding-agent": "^0.70.2",
+    "better-sqlite3": "^12.9.0",
+    "picocolors": "^1.1.1",
+    "ws": "^8.20.0"
+  },
+  "devDependencies": {
+    "@aexol/relay-protocol": "file:../packages/relay-protocol",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^20.11.0",
+    "@types/ws": "^8.18.1",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.9"
+  }
+}