chapterhouse 0.5.2 → 0.7.0

package/.pr-types.json

@@ -0,0 +1,14 @@
+[
+  "feat",
+  "fix",
+  "docs",
+  "style",
+  "refactor",
+  "perf",
+  "test",
+  "chore",
+  "build",
+  "ci",
+  "revert",
+  "release"
+]

package/README.md

@@ -91,6 +91,12 @@ cd ~/.chapterhouse/src
 npm install && npm run build && npm link
 ```
 
+If you're opening a sprint PR from the repo, validate the title first:
+
+```bash
+npm run pr:title:check -- "chore: add PR title preflight validation"
+```
+
 ## Upgrading
 
 ```bash

package/dist/api/agent-edit-access.js

@@ -0,0 +1,11 @@
+import { ForbiddenError } from "./errors.js";
+export function assertAgentEditAccess(options, user) {
+    if (!options.entraAuthEnabled) {
+        return;
+    }
+    if (user?.role === "team-lead") {
+        return;
+    }
+    throw new ForbiddenError("Admin access required");
+}
+//# sourceMappingURL=agent-edit-access.js.map

package/dist/api/agents.api.test.js

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createAgentFile, isBuiltinAgent, parseAgentMd } from "../copilot/agents.js";
+test("isBuiltinAgent returns true for shipped agent slugs", () => {
+    assert.equal(isBuiltinAgent("chapterhouse"), true);
+    assert.equal(isBuiltinAgent("coder"), true);
+    assert.equal(isBuiltinAgent("designer"), true);
+    assert.equal(isBuiltinAgent("general-purpose"), true);
+    assert.equal(isBuiltinAgent("custom-helper"), false);
+});
+test("parseAgentMd parses block-style YAML arrays", () => {
+    const agent = parseAgentMd([
+        "---",
+        "name: Designer",
+        "description: Handles UI flows",
+        "model: claude-sonnet-4.6",
+        "skills:",
+        "  - frontend-design",
+        "  - ux-copy",
+        "tools:",
+        "  - read",
+        "  - write",
+        "---",
+        "",
+        "You are Designer.",
+    ].join("\n"), "designer");
+    assert.ok(agent, "agent charter should parse");
+    assert.deepEqual(agent.skills, ["frontend-design", "ux-copy"]);
+    assert.deepEqual(agent.tools, ["read", "write"]);
+});
+test("slug validation regex rejects traversal-like agent slugs", () => {
+    const error = createAgentFile("..%2F..%2F", "Traversal", "Should fail validation", "claude-sonnet-4.6", "You are not valid.");
+    assert.equal(error, "Invalid slug '..%2F..%2F': must be kebab-case (a-z0-9 with hyphens).");
+});
+test("parseAgentMd returns null for invalid frontmatter", () => {
+    const agent = parseAgentMd([
+        "---",
+        "name: Designer",
+        "description: Handles UI flows",
+        "model: claude-sonnet-4.6",
+        "skills: [frontend-design",
+        "---",
+        "",
+        "You are Designer.",
+    ].join("\n"), "designer");
+    assert.equal(agent, null);
+});
+//# sourceMappingURL=agents.api.test.js.map

package/dist/api/server.js

@@ -1,18 +1,19 @@
 import cors from "cors";
 import express from "express";
 import helmet from "helmet";
-import { existsSync } from "fs";
-import { join, dirname } from "path";
+import { existsSync, readFileSync, statSync, writeFileSync } from "fs";
+import { join, dirname, resolve, sep } from "path";
 import { fileURLToPath } from "url";
 import { z } from "zod";
-import { sendToOrchestrator, interruptCurrentTurn, enqueueForSse, getAgentInfo, cancelCurrentMessage, interruptSessionTurn, getLastRouteResult, getCurrentSessionKey } from "../copilot/orchestrator.js";
+import { sendToOrchestrator, interruptCurrentTurn, enqueueForSse, cancelCurrentMessage, interruptSessionTurn, getLastRouteResult, getCurrentSessionKey, getPersistentAgentSessionState, reloadPersistentAgent } from "../copilot/orchestrator.js";
 import { agentEventBus } from "../copilot/agent-event-bus.js";
-import { ensureDefaultAgents, getAgentRegistry, loadAgents } from "../copilot/agents.js";
+import { ensureDefaultAgents, getAgent, getAgentRegistry, isBuiltinAgent, loadAgents, notifyAgentSaved, parseAgentMd, parseAgentMdOrThrow, serializeAgentMd, setAgentSaveRuntimeHooks, SLUG_REGEX, } from "../copilot/agents.js";
 import { config, persistModel } from "../config.js";
 import { ModeContext } from "../mode-context.js";
 import { getRouterConfig, updateRouterConfig } from "../copilot/router.js";
 import { searchIndex, parseIndex } from "../wiki/index-manager.js";
 import { createAuthMiddleware, getBootstrapAuthResponse } from "./auth.js";
+import { assertAgentEditAccess } from "./agent-edit-access.js";
 import { createConcurrentConnectionLimiter, createFixedWindowRateLimiter } from "./rate-limit.js";
 import { createTeamRouter } from "./team.js";
 import { writePage, deletePage, pageExists, listPages, ensureWikiStructure, assertPagePath, } from "../wiki/fs.js";
@@ -23,7 +24,7 @@ import { readWikiPage, teamWikiSync } from "../wiki/team-sync.js";
 import { withWikiWrite } from "../wiki/lock.js";
 import { listSkills, removeSkill } from "../copilot/skills.js";
 import { restartDaemon } from "../daemon.js";
-import { API_TOKEN_PATH } from "../paths.js";
+import { AGENTS_DIR, API_TOKEN_PATH } from "../paths.js";
 import { getCurrentRunId, getDb, getSessionMessages, getTaskEvents } from "../store/db.js";
 import { getTaskLogEvents, subscribeTaskLog } from "../copilot/task-event-log.js";
 import { subscribeSession, getSessionEventsFromDb, getSessionMaxSeqFromDb, oldestSessionSeq, } from "../copilot/turn-event-log.js";
@@ -78,6 +79,22 @@ const autoRequestSchema = z.object({
 const wikiWriteSchema = z.object({
     content: z.string({ error: "Missing 'content' string in request body" }),
 }).strict();
+const agentPatchSchema = z.object({
+    name: requiredString("name must be a non-empty string").optional(),
+    description: requiredString("description must be a non-empty string").optional(),
+    model: requiredString("model must be a non-empty string").optional(),
+    systemPrompt: z.string().optional(),
+}).passthrough().superRefine((value, ctx) => {
+    for (const key of ["slug", "scope", "tools", "skills"]) {
+        if (Object.prototype.hasOwnProperty.call(value, key)) {
+            ctx.addIssue({
+                code: "custom",
+                path: [key],
+                message: `'${key}' is read-only`,
+            });
+        }
+    }
+});
 const projectCreateSchema = z.object({
     slug: requiredString("Missing 'slug' in request body")
         .regex(/^[a-z0-9][a-z0-9-]*$/, "Project slug must be a lowercase slug"),
@@ -284,6 +301,18 @@ Create your first page via the wiki UI or by editing files under \`pages/\`.
 const sseClients = new Map();
 const pendingSseMessages = [];
 let connectionCounter = 0;
+function broadcastSsePayload(payload) {
+    for (const [, res] of sseClients) {
+        res.write(formatSseData(payload));
+    }
+}
+setAgentSaveRuntimeHooks({
+    getPersistentSessionState: getPersistentAgentSessionState,
+    reloadPersistentSession: reloadPersistentAgent,
+    emitAgentReloadEvent: (event) => {
+        broadcastSsePayload(event);
+    },
+});
 // ---------------------------------------------------------------------------
 // Bootstrap — hands the API token to the same-origin SPA on first load.
 // Loopback-only by IP / Origin check.
@@ -316,18 +345,145 @@ const handleHealth = (_req, res) => {
 };
 app.get("/status", handleHealth);
 app.get("/health", handleHealth);
+function getLoadedAgents() {
+    let agents = getAgentRegistry();
+    if (agents.length === 0) {
+        ensureDefaultAgents();
+        agents = loadAgents();
+    }
+    return agents;
+}
+function getAgentLastEdited(slug) {
+    try {
+        return statSync(join(AGENTS_DIR, `${slug}.agent.md`)).mtime.toISOString();
+    }
+    catch {
+        return null;
+    }
+}
 // ---------------------------------------------------------------------------
 // Workers / agents
 // ---------------------------------------------------------------------------
 app.get("/api/agents", (_req, res) => {
-    res.json(getAgentInfo());
+    const agents = getLoadedAgents()
+        .map((agent) => ({
+        name: agent.name,
+        slug: agent.slug,
+        description: agent.description,
+        model: agent.model,
+        scope: agent.scope ?? null,
+        type: isBuiltinAgent(agent.slug) ? "builtin" : "custom",
+        lastEdited: getAgentLastEdited(agent.slug),
+    }))
+        .sort((left, right) => {
+        if (left.type !== right.type) {
+            return left.type === "builtin" ? -1 : 1;
+        }
+        return left.name.localeCompare(right.name);
+    });
+    res.json(agents);
 });
-app.get("/api/channels", (_req, res) => {
-    let agents = getAgentRegistry();
-    if (agents.length === 0) {
-        ensureDefaultAgents();
-        agents = loadAgents();
+app.get("/api/agents/:slug", (req, res, next) => {
+    const slugParam = req.params.slug;
+    const slug = Array.isArray(slugParam) ? slugParam[0] : slugParam;
+    if (slug === "stream") {
+        next();
+        return;
     }
+    if (!SLUG_REGEX.test(slug)) {
+        res.status(400).json({ error: "Invalid slug" });
+        return;
+    }
+    getLoadedAgents();
+    const filePath = join(AGENTS_DIR, `${slug}.agent.md`);
+    const resolvedAgentsDir = resolve(AGENTS_DIR);
+    const resolvedFilePath = resolve(filePath);
+    if (!(resolvedFilePath === resolvedAgentsDir || resolvedFilePath.startsWith(`${resolvedAgentsDir}${sep}`))) {
+        res.status(403).json({ error: "Access denied" });
+        return;
+    }
+    let content;
+    try {
+        content = readFileSync(filePath, "utf-8");
+    }
+    catch {
+        res.status(404).json({ error: `Agent '${slug}' not found` });
+        return;
+    }
+    const agent = parseAgentMd(content, slug);
+    if (!agent) {
+        res.status(500).json({ error: `Agent '${slug}' could not be parsed` });
+        return;
+    }
+    const builtin = isBuiltinAgent(slug);
+    res.json({
+        name: agent.name,
+        slug: agent.slug,
+        description: agent.description,
+        model: agent.model,
+        scope: agent.scope ?? null,
+        persistent: agent.persistent ?? false,
+        skills: agent.skills ?? [],
+        type: builtin ? "builtin" : "custom",
+        editable: !builtin,
+        systemPrompt: agent.systemMessage,
+    });
+});
+app.patch("/api/agents/:slug", async (req, res) => {
+    const slugParam = req.params.slug;
+    const slug = Array.isArray(slugParam) ? slugParam[0] : slugParam;
+    if (!SLUG_REGEX.test(slug)) {
+        throw new BadRequestError("Invalid slug");
+    }
+    if (modeContext.isTeam() && req.user?.role !== "team-lead") {
+        throw new ForbiddenError("Forbidden");
+    }
+    const patch = parseRequest(agentPatchSchema, req.body ?? {});
+    const filePath = join(AGENTS_DIR, `${slug}.agent.md`);
+    const resolvedAgentsDir = resolve(AGENTS_DIR);
+    const resolvedFilePath = resolve(filePath);
+    if (!(resolvedFilePath === resolvedAgentsDir || resolvedFilePath.startsWith(`${resolvedAgentsDir}${sep}`))) {
+        throw new ForbiddenError("Access denied");
+    }
+    assertAgentEditAccess({ entraAuthEnabled: config.entraAuthEnabled }, req.user);
+    if (isBuiltinAgent(slug)) {
+        throw new ForbiddenError("Built-in agents are read-only");
+    }
+    if (!existsSync(filePath)) {
+        throw new NotFoundError("Agent not found");
+    }
+    try {
+        const current = parseAgentMdOrThrow(readFileSync(filePath, "utf-8"), slug);
+        const updated = {
+            ...current,
+            name: patch.name ?? current.name,
+            description: patch.description ?? current.description,
+            model: patch.model ?? current.model,
+            systemMessage: patch.systemPrompt ?? current.systemMessage,
+        };
+        const nextContent = serializeAgentMd(updated);
+        writeFileSync(filePath, nextContent, "utf-8");
+        await notifyAgentSaved(slug, updated);
+        res.json({
+            name: updated.name,
+            slug: updated.slug,
+            description: updated.description,
+            model: updated.model,
+            scope: updated.scope ?? null,
+            persistent: updated.persistent ?? false,
+            skills: updated.skills ?? [],
+            type: "custom",
+            editable: true,
+            systemPrompt: updated.systemMessage,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new BadRequestError(`Invalid content: ${message}`);
+    }
+});
+app.get("/api/channels", (_req, res) => {
+    const agents = getLoadedAgents();
     const persistentAgentChannels = agents
         .filter((agent) => agent.persistent)
         .map((agent) => ({
@@ -650,6 +806,21 @@ app.post("/api/cancel", async (_req, res) => {
     }
     res.json({ status: "ok", cancelled });
 });
+app.post("/api/agents/:slug/reload-confirm", async (req, res) => {
+    const slugParam = Array.isArray(req.params.slug) ? req.params.slug[0] : req.params.slug;
+    const slug = slugParam?.trim() || "";
+    const agent = getAgent(slug);
+    if (!agent?.persistent) {
+        throw new NotFoundError("Agent not found");
+    }
+    const sessionKey = `agent:${agent.slug}`;
+    await interruptSessionTurn(sessionKey);
+    const reloadResult = await reloadPersistentAgent(agent.slug);
+    if (reloadResult === "reloaded") {
+        broadcastSsePayload({ type: "agent_reloaded", slug: agent.slug, reason: "confirmed_restart" });
+    }
+    res.json({ status: "ok" });
+});
 // Cancel the active turn for one session key without touching other channels.
 app.post("/api/session/:sessionKey/interrupt", async (req, res) => {
     const sessionKey = Array.isArray(req.params.sessionKey)