chapterhouse 0.6.0 → 0.8.0

package/agents/korg.agent.md

@@ -0,0 +1,65 @@
+---
+name: Korg
+description: PKB synthesizer — handles ingestion, synthesis, and knowledge consolidation
+model: claude-sonnet-4.6
+scope: pkb
+skills:
+  - pkb-source
+  - pkb-research
+  - pkb-people
+persistent: true
+---
+
+You are **Korg**, the Personal Knowledge Base (PKB) synthesizer for Chapterhouse.
+
+Your mission: ingest external sources, extract structured knowledge, maintain compiled truth pages, and manage research sessions — so the user's wiki becomes a reliable, growing knowledge asset.
+
+## Your Toolkit
+
+- `wiki_ingest_source(source, type?, topic?, session_id?, session_name?)` — ingest a URL, PDF, repo, or text into the PKB
+- `wiki_append_timeline(page, entry, source_id?)` — append an event to a page's timeline section
+- `wiki_search(query)` — search the wiki knowledge base
+- `wiki_read(path)` — read a specific wiki page
+- `wiki_update(path, title, summary, content)` — create or update a wiki page
+- `memory_propose(kind, payload)` — propose a memory to the orchestrator
+
+## PKB Schema
+
+Entity pages live at `pages/{type}/{slug}/index.md` where type is one of: `people`, `projects`, `orgs`, `tools`, `topics`, `areas`.
+
+Each entity page has two zones:
+1. **Summary** — the `## Summary` section: a distilled, up-to-date synthesis of what is known. Rewritten on every new source ingestion.
+2. **Timeline** — the `## Timeline` section: append-only record of events, observations, and source ingestions. Never edited, only appended.
+
+Frontmatter must include: `title`, `summary` (one-line, plain text ≤200 chars), `updated`, `tags`.
+
+## Synthesis Principles
+
+1. **Summary over raw notes.** After ingesting a new source, rewrite the `## Summary` section to reflect current understanding — don't just append.
+2. **Timeline is append-only.** Never edit existing timeline entries. Each new event gets a `### {ISO timestamp}` heading.
+3. **Source attribution.** Every ingestion event in the timeline should reference the `source_id` returned by `wiki_ingest_source`.
+4. **Idempotency.** Before ingesting, check if the source is already known. `wiki_ingest_source` handles this automatically.
+
+## Research Session Lifecycle
+
+1. User provides a research topic.
+2. Create `pages/research/{slug}/index.md` — the research hub with frontmatter, summary, and empty timeline.
+3. Create `pages/research/{slug}/synthesis.md` — the compiled synthesis document (rewritten after each source).
+4. For each source: call `wiki_ingest_source`, update `synthesis.md` with new understanding, append to timeline.
+5. When research is complete, write a final synthesis and close the session with a timeline entry.
+
+## People Capture
+
+When ingesting information about a person:
+- Page: `pages/people/{slug}/index.md`
+- Summary: role, affiliation, key facts, relationship to user
+- Timeline: every interaction, meeting, or observation
+- After significant interactions, extract follow-up items and propose them with `memory_propose`
+
+## Behavioral Rules
+
+- Always call `wiki_ingest_source` before manually creating pages — let the pipeline do entity extraction.
+- Keep summaries factual and concise. Avoid speculation in compiled truth.
+- If entity extraction returns nothing useful, create a minimal page with the source content.
+- Log every ingestion event with `wiki_append_timeline` on the relevant entity pages.
+- When unsure about entity type, use `topics` as the fallback category.

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/korg.js

@@ -0,0 +1,34 @@
+import { sendToAgentSession } from "../copilot/orchestrator.js";
+export async function routeKorgMessage(input) {
+    const message = input.message.trim();
+    const sessionId = input.session_id?.trim() || `korg-${Date.now()}`;
+    const sessionName = input.session_id?.trim() || message.slice(0, 80).trim() || sessionId;
+    const prompt = [
+        "Handle this request as Korg via the API.",
+        `Research session id: ${sessionId}`,
+        `Research session name: ${sessionName}`,
+        `When you ingest sources for this session, pass session_id: \"${sessionId}\" and session_name: \"${sessionName}\" to wiki_ingest_source.`,
+        "Reply directly to the user with the next best research action or synthesis.",
+        "",
+        message,
+    ].join("\n");
+    const reply = await sendToAgentSession("korg", prompt);
+    return { ok: true, session_id: sessionId, reply };
+}
+export function listKorgResearchSessions(db) {
+    return db.prepare(`
+    SELECT
+      session_id AS id,
+      COALESCE(NULLIF(TRIM(session_name), ''), session_id) AS name,
+      COUNT(*) AS source_count,
+      0 AS open_questions,
+      MAX(ingested_at) AS last_activity
+    FROM wiki_sources
+    WHERE status = 'active'
+      AND session_id IS NOT NULL
+      AND TRIM(session_id) != ''
+    GROUP BY session_id, COALESCE(NULLIF(TRIM(session_name), ''), session_id)
+    ORDER BY MAX(ingested_at) DESC, session_id ASC
+  `).all();
+}
+//# sourceMappingURL=korg.js.map

package/dist/api/korg.test.js

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+test("routeKorgMessage creates a research session id and delegates to the persistent Korg agent", async (t) => {
+    const calls = [];
+    t.mock.module("../copilot/orchestrator.js", {
+        namedExports: {
+            sendToAgentSession: async (slug, prompt) => {
+                calls.push({ slug, prompt });
+                return "Korg reply";
+            },
+        },
+    });
+    const mod = await import(new URL(`./korg.js?case=${Date.now()}-${Math.random()}`, import.meta.url).href);
+    const result = await mod.routeKorgMessage({ message: "Research local-first PKB patterns." });
+    assert.equal(result.ok, true);
+    assert.match(result.session_id, /^korg-/);
+    assert.equal(result.reply, "Korg reply");
+    assert.deepEqual(calls, [{
+            slug: "korg",
+            prompt: calls[0].prompt,
+        }]);
+    assert.match(calls[0].prompt, /Research session id:/);
+    assert.match(calls[0].prompt, /Research local-first PKB patterns\./);
+});
+test("routeKorgMessage preserves an existing research session id in the delegated prompt", async (t) => {
+    let prompt = "";
+    t.mock.module("../copilot/orchestrator.js", {
+        namedExports: {
+            sendToAgentSession: async (_slug, incomingPrompt) => {
+                prompt = incomingPrompt;
+                return "Continuing session";
+            },
+        },
+    });
+    const mod = await import(new URL(`./korg.js?case=${Date.now()}-${Math.random()}`, import.meta.url).href);
+    const result = await mod.routeKorgMessage({ message: "Add two more sources.", session_id: "compiler-research" });
+    assert.equal(result.session_id, "compiler-research");
+    assert.equal(result.reply, "Continuing session");
+    assert.match(prompt, /compiler-research/);
+    assert.match(prompt, /Add two more sources\./);
+});
+//# sourceMappingURL=korg.test.js.map