repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

perf(the-system): defer operational runtime loading

0fdd32728fc009e5873316099832924ec3b71ffc

Oliver Jan Krylow <oliver@bugabinga.net> ·

SSH signature · not checked

Browse filesCompare with HEAD

Changed files (17)

extensions/the-system/__e2e__/renderer.spec.ts

Modified
186 186 const root = systemFixture();
187 187 const runtime = createBoardRuntime();
189 - runtime.beginProposal(root);
189 + await runtime.beginProposal(root);
190 190 await runtime.tool.execute(
191 191 "assessment",

extensions/the-system/__tests__/harness.test.ts

Modified
30 30 const sendUserMessage = vi
31 31 .spyOn(t.session, "sendUserMessage")
32 32 .mockResolvedValue();
33 - expect(extension.tools.has("system_bundle_slot")).toBe(true);
33 + expect(extension.tools.has("system_bundle_slot")).toBe(false);
34 34 expect(t.session.getActiveToolNames()).not.toContain("system_bundle_slot");
35 35 await extension.commands
36 36 .get("system")
39 39 t.session.extensionRunner.createCommandContext(),
41 41 expect(sendUserMessage).toHaveBeenCalledOnce();
42 + expect(extension.tools.has("system_bundle_slot")).toBe(true);
42 43 expect(t.session.getActiveToolNames()).toContain("system_bundle_slot");
43 44 expect(t.session.systemPrompt).toContain(
44 45 "- system_bundle_slot: Reserve an ID and path for a System bundle",

extensions/the-system/__tests__/startup.test.ts

Added
new file mode 100644
1 +import assert from "node:assert/strict";
2 +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
3 +import { tmpdir } from "node:os";
4 +import path from "node:path";
5 +import { afterEach, beforeEach, describe, it, vi } from "vitest";
7 +const markdown = vi.hoisted(() => ({ loaded: false }));
9 +vi.mock("../markdown.ts", async (importOriginal) => {
10 + markdown.loaded = true;
11 + return importOriginal();
12 +});
14 +const roots: string[] = [];
16 +function validSystem(): string {
17 + const root = mkdtempSync(path.join(tmpdir(), "the-system-startup-"));
18 + roots.push(root);
19 + mkdirSync(path.join(root, ".git"));
20 + mkdirSync(path.join(root, ".system"));
21 + for (const directory of ["specs", "phases", "plans", "issues", "research"])
22 + mkdirSync(path.join(root, ".system", directory));
23 + for (const name of ["SYSTEM.md", "MISSION.md", "RULES.md"])
24 + writeFileSync(path.join(root, ".system", name), `# ${name}\n`, "utf8");
25 + writeFileSync(
26 + path.join(root, ".system", "config.json"),
27 + '{"prefix":"PX","schemaVersion":0}\n',
28 + "utf8",
29 + );
30 + writeFileSync(
31 + path.join(root, ".system", "board.json"),
32 + '{"schemaVersion":0,"items":{}}\n',
33 + "utf8",
34 + );
35 + return root;
38 +beforeEach(() => {
39 + markdown.loaded = false;
40 + vi.resetModules();
41 +});
43 +afterEach(() => {
44 + for (const root of roots.splice(0)) rmSync(root, { recursive: true });
45 +});
47 +describe("The System startup", () => {
48 + it("does not load the Markdown parser for a project without a current phase", async () => {
49 + const handlers = new Map<
50 + string,
51 + ((event: { cwd: string }) => Promise<unknown>)[]
52 + >();
53 + const { default: registerTheSystem } = await import("../index.ts");
54 + registerTheSystem({
55 + events: { emit() {} },
56 + getActiveTools: () => [],
57 + on: (
58 + event: string,
59 + handler: (event: { cwd: string }) => Promise<unknown>,
60 + ) => {
61 + handlers.set(event, [...(handlers.get(event) ?? []), handler]);
62 + },
63 + registerCommand() {},
64 + registerTool() {},
65 + setActiveTools() {},
66 + } as never);
68 + const discover = handlers.get("resources_discover")?.[0];
69 + assert.ok(discover);
70 + await discover({ cwd: validSystem() });
71 + assert.equal(markdown.loaded, false);
72 + });
73 +});

extensions/the-system/__tests__/system.test.ts

Modified
104 104 describe("runtime core injection", () => {
105 - it("injects the current phase after MISSION without mutating it", () => {
105 + it("injects the current phase after MISSION without mutating it", async () => {
106 106 const project = root();
107 107 const phase = ".system/phases/PX-PHASE-PHASE001-pre-v1/index.md";
108 108 write(
134 134 prefix: "PX",
135 135 phaseLabel: "pre-v1",
137 + assert.deepEqual(await startupRuntimeState(project), {
138 + active: true,
139 + prefix: "PX",
140 + phaseLabel: "pre-v1",
141 + });
137 142 rmSync(path.join(project, path.dirname(phase)), {
138 143 recursive: true,
139 144 force: true,

extensions/the-system/__tests__/the-system.test.ts

Modified
183 183 assert.match(prompt, /Terse governs prose, not models/);
186 - it("registers /system and scoped extension tools", () => {
186 + it("registers /system and defers scoped extension tools", () => {
187 187 const commands: string[] = [];
188 188 const tools: string[] = [];
189 189 registerTheSystem({
192 192 on() {},
193 193 } as never);
194 194 assert.deepEqual(commands, ["system"]);
195 - assert.deepEqual(tools, [
196 - "system_bundle_slot",
197 - "system_board_propose",
198 - "system_board_update",
199 - ]);
195 + assert.deepEqual(tools, []);
202 198 it("keeps scoped tools through clarification until their existing completion signal", async () => {
725 721 assert.doesNotMatch(notices[0] ?? "", /\/reload/);
724 + it("waits for board activation before sending lifecycle prompts", async () => {
725 + const project = temp();
726 + validSystem(project);
727 + const sent: string[] = [];
728 + let release: (() => void) | undefined;
729 + const activated = new Promise<void>((resolve) => {
730 + release = resolve;
731 + });
732 + const command = createSystemCommand(
734 + sendUserMessage: (message: string) => sent.push(message),
735 + } as never,
736 + { activateBoardProposal: () => activated },
737 + );
739 + const pending = command.handler("assess", {
740 + cwd: project,
741 + ui: { notify() {} },
742 + } as never);
743 + await Promise.resolve();
744 + assert.deepEqual(sent, []);
745 + release?.();
746 + await pending;
747 + assert.equal(sent.length, 1);
748 + });
728 750 it("injects lifecycle prompts and activates bundle allocation", async () => {
729 751 const project = temp();
730 752 validSystem(project);

extensions/the-system/board-constants.ts

Added
new file mode 100644
1 +export const BOARD_NOTE_LIMIT = 200;

extensions/the-system/board-runtime.ts

Modified
2 2 import { StringEnum } from "@earendil-works/pi-ai";
3 3 import { defineTool, keyHint } from "@earendil-works/pi-coding-agent";
4 4 import { Text } from "@earendil-works/pi-tui";
5 5 import { Type } from "typebox";
6 +import { BOARD_NOTE_LIMIT } from "./board-constants.ts";
6 7 import type { BoardServer } from "./board-server.ts";
7 -import {
8 - BOARD_NOTE_LIMIT,
9 - type BoardProposal,
10 - readBoardState,
11 - updateBoardState,
12 - writeBoardState,
13 -} from "./board-state.ts";
14 -import { discoverProjectRoot } from "./documents.ts";
8 +import type { BoardProposal } from "./board-state.ts";
15 9 import {
16 10 loadBoardServer,
11 + loadBoardState,
17 12 loadOpenBrowser,
13 + loadProjectIndex,
18 14 loadSystemRenderer,
19 15 } from "./loaders.js";
20 -import { loadProjectIndex } from "./project-index.ts";
16 +import { discoverProjectRoot } from "./project-root.ts";
21 17 import { expandableFallback } from "./tool-rendering.ts";
23 19 const STATES = ["todo", "done", "open"] as const;
91 87 let updateFinished = false;
92 88 const proposals = new Map<string, Map<string, BoardProposal>>();
93 89 const servers = new Set<BoardServer>();
90 + const loadBoard = async (cwd: string) => {
91 + const root = discoverProjectRoot(cwd);
92 + const [projectIndex, boardState] = await Promise.all([
93 + loadProjectIndex(),
94 + loadBoardState(),
95 + ]);
96 + const index = projectIndex.loadProjectIndex(root);
97 + const state = boardState.readBoardState(root, index.prefix);
98 + return { boardState, index, root, state };
99 + };
94 100 const tool = defineTool({
95 101 name: "system_board_propose",
96 102 label: "system_board_propose",
137 143 throw new Error(
138 144 "system_board_propose is only available during /system assess or /system exec",
140 - const index = loadProjectIndex(root);
146 + const { index } = await loadBoard(root);
147 + if (root !== proposalRoot)
148 + throw new Error(
149 + "system_board_propose is only available during /system assess or /system exec",
150 + );
141 151 const byId = new Map(
142 152 index.documents.map((document) => [document.metadata.id, document]),
224 234 throw new Error(
225 235 "system_board_update is only available during /system exec",
227 - const index = loadProjectIndex(root);
228 - let state = readBoardState(root, index.prefix);
237 + const loaded = await loadBoard(root);
238 + if (root !== updateRoot)
239 + throw new Error(
240 + "system_board_update is only available during /system exec",
241 + );
242 + let state = loaded.state;
229 243 const updatedAt = new Date().toISOString();
230 244 const applied: BoardProposal[] = [];
231 245 for (const raw of params.items) {
232 - state = updateBoardState(
246 + state = loaded.boardState.updateBoardState(
233 247 state,
234 - index.documents,
248 + loaded.index.documents,
235 249 raw.id,
236 250 raw.state,
237 251 "agent",
244 258 rationale: raw.note.trim(),
247 - if (applied.length > 0) writeBoardState(root, state);
261 + if (applied.length > 0) loaded.boardState.writeBoardState(root, state);
248 262 updateFinished = true;
249 263 const items = [...applied].sort((left, right) =>
250 264 left.id.localeCompare(right.id),
267 281 return {
269 283 updateTool,
270 - beginUpdate(cwd: string) {
271 - const root = discoverProjectRoot(cwd);
272 - const index = loadProjectIndex(root);
273 - readBoardState(root, index.prefix);
284 + async beginUpdate(cwd: string) {
285 + const { root } = await loadBoard(cwd);
274 286 updateRoot = root;
275 287 updateFinished = false;
281 293 updateRoot = undefined;
282 294 updateFinished = false;
284 - beginProposal(cwd: string) {
285 - const root = discoverProjectRoot(cwd);
286 - const index = loadProjectIndex(root);
287 - readBoardState(root, index.prefix);
296 + async beginProposal(cwd: string) {
297 + const { root } = await loadBoard(cwd);
288 298 proposalRoot = root;
289 299 proposalFinished = false;
290 300 proposals.set(root, new Map());
297 307 proposalFinished = false;
299 309 async open(cwd: string): Promise<string> {
300 - const index = loadProjectIndex(cwd);
301 - readBoardState(index.root, index.prefix);
310 + const { index } = await loadBoard(cwd);
302 311 const [{ renderSystemBoardSite }, { startBoardServer }, { openUrl }] =
303 312 await Promise.all([
304 313 loadSystemRenderer(),

extensions/the-system/board-state.ts

Modified
1 1 import { readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
2 2 import path from "node:path";
3 -import {
4 - type BundleDocumentRecord,
5 - type DocumentMetadata,
6 - parseDocumentId,
7 - resolveGovernedPath,
8 - SystemDocumentError,
9 -} from "./documents.ts";
3 +import { BOARD_NOTE_LIMIT } from "./board-constants.ts";
4 +import type { BundleDocumentRecord, DocumentMetadata } from "./documents.ts";
5 +import { resolveGovernedPath, SystemDocumentError } from "./project-root.ts";
6 +import { parseDocumentId } from "./system-config.ts";
11 8 export const BOARD_SCHEMA_VERSION = 0;
12 9 export const BOARD_PATH = ".system/board.json";
14 -export const BOARD_NOTE_LIMIT = 200;
11 +export { BOARD_NOTE_LIMIT } from "./board-constants.ts";
15 12 export type BoardItemState = "todo" | "done" | "open";
16 13 export type BoardItemSource = "manual" | "assess" | "agent";
17 14 export type BoardEntry = Readonly<{

extensions/the-system/documents.ts

Modified
6 6 parseRichMarkdown,
7 7 } from "./markdown.ts";
8 8 import { SystemDocumentError } from "./project-root.ts";
9 +import {
10 + type DocumentType,
11 + parseDocumentId,
12 + type SystemConfig,
13 +} from "./system-config.ts";
10 -export { discoverProjectRoot, SystemDocumentError } from "./project-root.ts";
15 +export {
16 + discoverProjectRoot,
17 + resolveGovernedPath,
18 + SystemDocumentError,
19 +} from "./project-root.ts";
20 +export * from "./system-config.ts";
12 -export const SCHEMA_VERSION = 0;
13 22 export const PHASE_BYTE_LIMIT = 32 * 1024;
15 -export function resolveGovernedPath(root: string, candidate: string): string {
16 - const normalizedRoot = path.resolve(root);
17 - const target = path.resolve(normalizedRoot, candidate);
18 - const relative = path.relative(normalizedRoot, target);
19 - if (
20 - relative === ".." ||
21 - relative.startsWith(`..${path.sep}`) ||
22 - path.isAbsolute(relative)
23 - )
24 - throw new SystemDocumentError(
25 - "path.outside-root",
26 - `Path is outside project root: ${candidate}`,
27 - );
28 - return target;
31 -export const DOCUMENT_TYPES = [
32 - "spec",
33 - "phase",
34 - "plan",
35 - "issue",
36 - "research",
37 -] as const;
38 -export type DocumentType = (typeof DOCUMENT_TYPES)[number];
39 -export type SystemConfig = Readonly<{
40 - prefix: string;
41 - schemaVersion: number;
42 - title?: string;
43 - currentPhase?: string;
44 -}>;
45 -export type InitializationSystemConfig = Readonly<{
46 - config: SystemConfig;
47 - sourceSchemaVersion?: number;
48 -}>;
49 -export type ParsedDocumentId = Readonly<{
50 - id: string;
51 - prefix: string;
52 - type: DocumentType;
53 - token: string;
54 -}>;
55 23 export type ResearchMetadata = Readonly<{
56 24 id: string;
57 25 type: "research";
113 81 diagnostics: readonly Diagnostic[];
116 -const PREFIX = /^[A-Z][A-Z0-9]{1,7}$/;
117 84 const SLUG = "[a-z0-9]+(?:-[a-z0-9]+)*";
118 -const ID_CHARS = "[A-Z0-9_-]{8}";
119 -const TYPE_BY_TOKEN = new Map(
120 - DOCUMENT_TYPES.map((type) => [type.toUpperCase(), type]),
121 -);
122 85 const DIRECTORY_BY_TYPE: Readonly<Record<DocumentType, string>> = {
123 86 spec: "specs",
124 87 phase: "phases",
131 94 return DIRECTORY_BY_TYPE[type];
134 -const objectValue = (
135 - value: unknown,
136 - label: string,
137 -): Record<string, unknown> => {
138 - if (typeof value !== "object" || value === null || Array.isArray(value))
139 - throw new SystemDocumentError(
140 - "json.shape",
141 - `${label} must be a JSON object`,
142 - );
143 - return value as Record<string, unknown>;
144 -};
145 -const duplicateTopLevelKeys = (source: string): string[] => {
146 - const keys: string[] = [];
147 - const duplicates = new Set<string>();
148 - let depth = 0;
149 - let index = 0;
150 - while (index < source.length) {
151 - const character = source[index];
152 - if (character === "{") {
153 - depth += 1;
154 - index += 1;
155 - continue;
156 - }
157 - if (character === "}") {
158 - depth -= 1;
159 - index += 1;
160 - continue;
161 - }
162 - if (character !== '"') {
163 - index += 1;
164 - continue;
165 - }
166 - const start = index++;
167 - let escaped = false;
168 - while (index < source.length) {
169 - const current = source[index++];
170 - if (!escaped && current === '"') break;
171 - escaped = !escaped && current === "\\";
172 - if (current !== "\\") escaped = false;
173 - }
174 - if (depth !== 1) continue;
175 - let cursor = index;
176 - while (/\s/.test(source[cursor] ?? "")) cursor += 1;
177 - if (source[cursor] !== ":") continue;
178 - const key = JSON.parse(source.slice(start, index)) as string;
179 - if (keys.includes(key)) duplicates.add(key);
180 - keys.push(key);
181 - }
182 - return [...duplicates].sort();
183 -};
185 -export function parseSystemConfig(source: string): SystemConfig {
186 - let parsed: unknown;
187 - try {
188 - parsed = JSON.parse(source);
189 - } catch {
190 - throw new SystemDocumentError("config.invalid-json", "Invalid config JSON");
191 - }
192 - const duplicates = duplicateTopLevelKeys(source);
193 - if (duplicates.length)
194 - throw new SystemDocumentError(
195 - "config.duplicate-key",
196 - `Duplicate config keys: ${duplicates.join(", ")}`,
197 - );
198 - const value = objectValue(parsed, "Config");
199 - if (value.schemaVersion !== SCHEMA_VERSION)
200 - throw new SystemDocumentError(
201 - "config.version",
202 - `Schema version ${String(value.schemaVersion)} does not match ${SCHEMA_VERSION}; run /system init`,
203 - );
204 - const keys = Object.keys(value).sort();
205 - const validKeys = ["currentPhase", "prefix", "schemaVersion", "title"];
206 - if (
207 - !("prefix" in value) ||
208 - !("schemaVersion" in value) ||
209 - keys.some((key) => !validKeys.includes(key))
210 - )
211 - throw new SystemDocumentError(
212 - "json.keys",
213 - `Expected keys prefix, schemaVersion[, title, currentPhase]; received ${keys.join(", ")}`,
214 - );
215 - if (typeof value.prefix !== "string" || !PREFIX.test(value.prefix))
216 - throw new SystemDocumentError("config.prefix", "Invalid project prefix");
217 - if (
218 - "title" in value &&
219 - (typeof value.title !== "string" || value.title.trim() === "")
220 - )
221 - throw new SystemDocumentError("config.title", "Invalid project title");
222 - if ("currentPhase" in value) {
223 - if (typeof value.currentPhase !== "string")
224 - throw new SystemDocumentError(
225 - "config.current-phase",
226 - "Current phase must be a phase ID",
227 - );
228 - const current = parseDocumentId(value.currentPhase, value.prefix);
229 - if (current.type !== "phase")
230 - throw new SystemDocumentError(
231 - "config.current-phase",
232 - "Current phase must be a phase ID",
233 - );
234 - }
235 - return {
236 - prefix: value.prefix,
237 - schemaVersion: value.schemaVersion as number,
238 - ...(typeof value.title === "string" ? { title: value.title } : {}),
239 - ...(typeof value.currentPhase === "string"
240 - ? { currentPhase: value.currentPhase }
241 - : {}),
242 - };
245 -export function systemConfigForInitialization(
246 - source: string,
247 -): InitializationSystemConfig {
248 - try {
249 - return { config: parseSystemConfig(source) };
250 - } catch (error) {
251 - if (
252 - !(error instanceof SystemDocumentError) ||
253 - error.code !== "config.version"
254 - )
255 - throw error;
256 - const parsed = objectValue(JSON.parse(source), "Config");
257 - if (
258 - duplicateTopLevelKeys(source).length > 0 ||
259 - typeof parsed.schemaVersion !== "number" ||
260 - !Number.isInteger(parsed.schemaVersion)
261 - )
262 - throw error;
263 - const config = parseSystemConfig(
264 - JSON.stringify({
265 - prefix: parsed.prefix,
266 - schemaVersion: SCHEMA_VERSION,
267 - ...("title" in parsed ? { title: parsed.title } : {}),
268 - ...("currentPhase" in parsed
269 - ? { currentPhase: parsed.currentPhase }
270 - : {}),
271 - }),
272 - );
273 - return { config, sourceSchemaVersion: parsed.schemaVersion };
274 - }
277 -export function parseDocumentId(
278 - source: string,
279 - expectedPrefix?: string,
280 -): ParsedDocumentId {
281 - const match = new RegExp(
282 - `^([A-Z][A-Z0-9]{1,7})-(SPEC|PHASE|PLAN|ISSUE|RESEARCH)-(${ID_CHARS})$`,
283 - ).exec(source);
284 - if (!match)
285 - throw new SystemDocumentError(
286 - "id.invalid",
287 - `Invalid document ID: ${source}`,
288 - );
289 - if (expectedPrefix && match[1] !== expectedPrefix)
290 - throw new SystemDocumentError(
291 - "id.prefix",
292 - `Document ID must use prefix ${expectedPrefix}: ${source}`,
293 - );
294 - return {
295 - id: source,
296 - prefix: match[1] as string,
297 - type: TYPE_BY_TOKEN.get(match[2]) as DocumentType,
298 - token: match[3] as string,
299 - };
302 97 export function validateDocumentPath(
303 98 documentPath: string,
304 99 metadata: DocumentMetadata,

extensions/the-system/index.ts

Modified
4 4 import path from "node:path";
5 5 import {
6 6 type ExtensionAPI,
7 7 type ExtensionContext,
8 8 isToolCallEventType,
9 9 } from "@earendil-works/pi-coding-agent";
10 -import { createBoardRuntime } from "./board-runtime.js";
11 -import { createBundleSlotTool } from "./bundle-slot-tool.js";
12 10 import { loadStartupNotice, loadSystem, loadSystemCommand } from "./loaders.js";
13 11 import { systemArgumentCompletions } from "./system-command-meta.js";
13 +type BoardRuntime = ReturnType<
14 + typeof import("./board-runtime.js")["createBoardRuntime"]
15 +>;
16 +type BundleSlotTool = ReturnType<
17 + typeof import("./bundle-slot-tool.js")["createBundleSlotTool"]
18 +>;
20 +interface OperationalRuntime {
21 + board: BoardRuntime;
22 + bundleSlot: BundleSlotTool;
25 +const OPERATIONAL_TOOL_NAMES = new Set([
26 + "system_bundle_slot",
27 + "system_board_propose",
28 + "system_board_update",
29 +]);
15 31 function isStaleContextError(error: unknown): boolean {
16 32 return (
17 33 error instanceof Error &&
24 40 let boardProposalRunActive = false;
25 41 let boardUpdateRunActive = false;
26 42 let bundleMigrationRunActive = false;
27 - const bundleSlot = createBundleSlotTool(() => {
28 - bundleSlotUsed = true;
29 - });
30 - const board = createBoardRuntime();
43 + // Scoped tools stay inactive until /system starts governed work; defer their
44 + // runtime graph so routine Pi startup does not transpile unused tool code.
45 + let operational: OperationalRuntime | undefined;
46 + let operationalPromise: Promise<OperationalRuntime> | undefined;
47 + const loadOperationalRuntime = (): Promise<OperationalRuntime> => {
48 + if (operational) return Promise.resolve(operational);
49 + if (operationalPromise) return operationalPromise;
50 + operationalPromise = Promise.all([
51 + import("./board-runtime.js"),
52 + import("./bundle-slot-tool.js"),
53 + ]).then(([{ createBoardRuntime }, { createBundleSlotTool }]) => {
54 + const runtime = {
55 + board: createBoardRuntime(),
56 + bundleSlot: createBundleSlotTool(() => {
57 + bundleSlotUsed = true;
58 + }),
59 + };
60 + pi.registerTool(runtime.bundleSlot);
61 + pi.registerTool(runtime.board.tool);
62 + pi.registerTool(runtime.board.updateTool);
63 + pi.setActiveTools(
64 + pi.getActiveTools().filter((name) => !OPERATIONAL_TOOL_NAMES.has(name)),
65 + );
66 + operational = runtime;
67 + return runtime;
68 + });
69 + return operationalPromise;
70 + };
31 71 const activateBundleSlot = () => {
72 + const bundleSlot = operational?.bundleSlot;
73 + if (!bundleSlot) throw new Error("The System tools are not loaded");
32 74 const active = pi.getActiveTools();
33 75 if (!active.includes(bundleSlot.name))
34 76 pi.setActiveTools([...active, bundleSlot.name]);
36 78 bundleSlotUsed = false;
38 80 const deactivateBundleSlot = () => {
81 + const bundleSlot = operational?.bundleSlot;
39 82 const active = pi.getActiveTools();
40 - if (active.includes(bundleSlot.name))
83 + if (bundleSlot && active.includes(bundleSlot.name))
41 84 pi.setActiveTools(active.filter((name) => name !== bundleSlot.name));
42 85 bundleSlotRunActive = false;
43 86 bundleSlotUsed = false;
45 - const activateBoardProposal = (cwd: string) => {
46 - board.beginProposal(cwd);
88 + const activateBoardProposal = async (cwd: string) => {
89 + const board = operational?.board;
90 + if (!board) throw new Error("The System tools are not loaded");
91 + await board.beginProposal(cwd);
47 92 const active = pi.getActiveTools();
48 93 if (!active.includes(board.tool.name))
49 94 pi.setActiveTools([...active, board.tool.name]);
50 95 boardProposalRunActive = true;
52 97 const deactivateBoardProposal = () => {
98 + const board = operational?.board;
53 99 const active = pi.getActiveTools();
54 - if (active.includes(board.tool.name))
100 + if (board && active.includes(board.tool.name))
55 101 pi.setActiveTools(active.filter((name) => name !== board.tool.name));
56 - board.endProposal();
102 + board?.endProposal();
57 103 boardProposalRunActive = false;
59 - const activateBoardUpdate = (cwd: string) => {
60 - board.beginUpdate(cwd);
105 + const activateBoardUpdate = async (cwd: string) => {
106 + const board = operational?.board;
107 + if (!board) throw new Error("The System tools are not loaded");
108 + await board.beginUpdate(cwd);
61 109 const active = pi.getActiveTools();
62 110 if (!active.includes(board.updateTool.name))
63 111 pi.setActiveTools([...active, board.updateTool.name]);
64 112 boardUpdateRunActive = true;
66 114 const deactivateBoardUpdate = () => {
115 + const board = operational?.board;
67 116 const active = pi.getActiveTools();
68 - if (active.includes(board.updateTool.name))
117 + if (board && active.includes(board.updateTool.name))
69 118 pi.setActiveTools(
70 119 active.filter((name) => name !== board.updateTool.name),
72 - board.endUpdate();
121 + board?.endUpdate();
73 122 boardUpdateRunActive = false;
75 124 const activateBundleMigration = () => {
158 207 boardProposalRunActive = false;
159 208 boardUpdateRunActive = false;
160 209 bundleMigrationRunActive = false;
161 - board.shutdown();
210 + operational?.board.shutdown();
163 212 pi.on("before_agent_start", async (event, ctx) => {
164 213 void syncRuntimeIndicator(ctx, generation).catch((error) =>
173 222 notifyFailure(ctx, "The System status refresh failed", error),
175 224 if (bundleSlotRunActive && bundleSlotUsed) deactivateBundleSlot();
176 - if (boardProposalRunActive && board.proposalComplete())
225 + if (boardProposalRunActive && operational?.board.proposalComplete())
177 226 deactivateBoardProposal();
178 - if (boardUpdateRunActive && board.updateComplete()) deactivateBoardUpdate();
227 + if (boardUpdateRunActive && operational?.board.updateComplete())
228 + deactivateBoardUpdate();
179 229 bundleMigrationRunActive = false;
181 231 pi.on("tool_call", async (event, ctx) => {
196 246 return result ? { block: true, reason: result.reason } : undefined;
199 - pi.registerTool(bundleSlot);
200 - pi.registerTool(board.tool);
201 - pi.registerTool(board.updateTool);
202 249 pi.registerCommand("system", {
203 250 description: "The System project governance",
204 251 getArgumentCompletions: systemArgumentCompletions,
205 252 handler: async (args, ctx) => {
206 - const { createSystemCommand } = await loadSystemCommand();
253 + const [{ createSystemCommand }, runtime] = await Promise.all([
254 + loadSystemCommand(),
255 + loadOperationalRuntime(),
256 + ]);
207 257 await createSystemCommand(pi, {
208 258 beginLifecycle,
209 259 activateBundleTool: activateBundleSlot,
210 260 activateBoardProposal,
211 261 activateBoardUpdate,
212 262 activateBundleMigration,
213 - openBoard: board.open,
263 + openBoard: runtime.board.open,
214 264 }).handler(args, ctx);

extensions/the-system/init.ts

Modified
9 9 } from "./board-state.ts";
10 10 import {
11 11 discoverProjectRoot,
12 - parseSystemConfig,
13 12 resolveGovernedPath,
14 - SCHEMA_VERSION,
15 13 SystemDocumentError,
14 +} from "./project-root.ts";
15 +import {
16 + parseSystemConfig,
17 + SCHEMA_VERSION,
16 18 systemConfigForInitialization,
17 -} from "./documents.ts";
19 +} from "./system-config.ts";
19 21 export type InitializationInspection = Readonly<{
20 22 root: string;

extensions/the-system/loaders.ts

Modified
14 14 export const loadBoardServer = lazy(() => import("./board-server.ts"));
15 15 export const loadOpenBrowser = lazy(() => import("./open-browser.ts"));
16 16 export const loadBundleSlot = lazy(() => import("./bundle-slot.js"));
17 +export const loadBoardState = lazy(() => import("./board-state.ts"));
18 +export const loadProjectIndex = lazy(() => import("./project-index.ts"));

extensions/the-system/project-root.ts

Modified
28 +export function resolveGovernedPath(root: string, candidate: string): string {
29 + const normalizedRoot = path.resolve(root);
30 + const target = path.resolve(normalizedRoot, candidate);
31 + const relative = path.relative(normalizedRoot, target);
32 + if (
33 + relative === ".." ||
34 + relative.startsWith(`..${path.sep}`) ||
35 + path.isAbsolute(relative)
36 + )
37 + throw new SystemDocumentError(
38 + "path.outside-root",
39 + `Path is outside project root: ${candidate}`,
40 + );
41 + return target;
28 44 export function discoverProjectRoot(
29 45 cwd: string,
30 46 markerExists = existsSync,

extensions/the-system/startup-notice.ts

Modified
1 -import { existsSync } from "node:fs";
2 -import path from "node:path";
3 -import { loadSystem } from "./loaders.js";
4 -import { discoverProjectRoot } from "./project-root.ts";
5 -import type { SystemRuntimeState } from "./system.ts";
1 +import {
2 + readStartupRuntimeState,
3 + type StartupRuntimeState,
4 +} from "./startup-state.ts";
7 6 export async function startupRuntimeState(
8 7 cwd: string,
9 -): Promise<SystemRuntimeState> {
10 - let root: string;
11 - try {
12 - root = discoverProjectRoot(cwd);
13 - } catch {
14 - return { active: false };
15 - }
16 - if (!existsSync(path.join(root, ".system"))) return { active: false };
17 - const { runtimeState } = await loadSystem();
18 - return runtimeState(cwd);
8 +): Promise<StartupRuntimeState> {
9 + return readStartupRuntimeState(cwd);
21 12 export async function startupRuntimeNotice(

extensions/the-system/startup-state.ts

Added
new file mode 100644
1 +import { existsSync } from "node:fs";
2 +import path from "node:path";
3 +import { inspectInitialization } from "./init.ts";
4 +import { loadSystem } from "./loaders.js";
5 +import { discoverProjectRoot } from "./project-root.ts";
6 +import { SCHEMA_VERSION } from "./system-config.ts";
8 +export type StartupRuntimeState = Readonly<{
9 + active: boolean;
10 + prefix?: string;
11 + phaseLabel?: string;
12 + notice?: string;
13 +}>;
15 +const INCOMPLETE_NOTICE =
16 + "The System is incomplete or invalid; run /system init before governed work.";
17 +const SCHEMA_NOTICE = `The System schema does not match ${SCHEMA_VERSION}; run /system init to update it.`;
19 +/** Keep routine startup on config and board JSON only.
20 + * Current phases require full Markdown validation and deliberately cross the
21 + * heavier System implementation boundary. */
22 +export async function readStartupRuntimeState(
23 + cwd: string,
24 +): Promise<StartupRuntimeState> {
25 + let root: string;
26 + try {
27 + root = discoverProjectRoot(cwd);
28 + } catch {
29 + return { active: false };
30 + }
31 + if (!existsSync(path.join(root, ".system"))) return { active: false };
32 + try {
33 + const inspection = inspectInitialization(root);
34 + if (inspection.rewrites.length > 0)
35 + return { active: true, notice: SCHEMA_NOTICE };
36 + if (inspection.currentPhase) {
37 + const { runtimeState } = await loadSystem();
38 + return runtimeState(cwd);
39 + }
40 + const incomplete =
41 + inspection.creates.length > 0 ||
42 + inspection.cores.some(({ state }) => state === "missing");
43 + return {
44 + active: true,
45 + ...(inspection.prefix ? { prefix: inspection.prefix } : {}),
46 + ...(incomplete ? { notice: INCOMPLETE_NOTICE } : {}),
47 + };
48 + } catch {
49 + return { active: true, notice: INCOMPLETE_NOTICE };
50 + }

extensions/the-system/system-command.ts

Modified
44 44 type SystemCommandHooks = Readonly<{
45 45 beginLifecycle?: () => void;
46 46 activateBundleTool?: () => void;
47 - activateBoardProposal?: (cwd: string) => void;
48 - activateBoardUpdate?: (cwd: string) => void;
47 + activateBoardProposal?: (cwd: string) => void | Promise<void>;
48 + activateBoardUpdate?: (cwd: string) => void | Promise<void>;
49 49 activateBundleMigration?: () => void;
50 50 openBoard?: (cwd: string) => Promise<string>;
126 126 if (BUNDLE_SUBCOMMANDS.has(parsed.subcommand))
127 127 hooks.activateBundleTool?.();
128 128 if (parsed.subcommand === "assess")
129 - hooks.activateBoardProposal?.(ctx.cwd);
130 - if (parsed.subcommand === "exec") hooks.activateBoardUpdate?.(ctx.cwd);
129 + await hooks.activateBoardProposal?.(ctx.cwd);
130 + if (parsed.subcommand === "exec")
131 + await hooks.activateBoardUpdate?.(ctx.cwd);
131 132 pi.sendUserMessage(
132 133 systemPromptFor(
133 134 parsed.subcommand,

extensions/the-system/system-config.ts

Added
new file mode 100644
1 +import { SystemDocumentError } from "./project-root.ts";
3 +export const SCHEMA_VERSION = 0;
5 +export const DOCUMENT_TYPES = [
6 + "spec",
7 + "phase",
8 + "plan",
9 + "issue",
10 + "research",
11 +] as const;
12 +export type DocumentType = (typeof DOCUMENT_TYPES)[number];
13 +export type SystemConfig = Readonly<{
14 + prefix: string;
15 + schemaVersion: number;
16 + title?: string;
17 + currentPhase?: string;
18 +}>;
19 +export type InitializationSystemConfig = Readonly<{
20 + config: SystemConfig;
21 + sourceSchemaVersion?: number;
22 +}>;
23 +export type ParsedDocumentId = Readonly<{
24 + id: string;
25 + prefix: string;
26 + type: DocumentType;
27 + token: string;
28 +}>;
30 +const PREFIX = /^[A-Z][A-Z0-9]{1,7}$/;
31 +const ID_CHARS = "[A-Z0-9_-]{8}";
32 +const TYPE_BY_TOKEN = new Map(
33 + DOCUMENT_TYPES.map((type) => [type.toUpperCase(), type]),
34 +);
36 +const objectValue = (
37 + value: unknown,
38 + label: string,
39 +): Record<string, unknown> => {
40 + if (typeof value !== "object" || value === null || Array.isArray(value))
41 + throw new SystemDocumentError(
42 + "json.shape",
43 + `${label} must be a JSON object`,
44 + );
45 + return value as Record<string, unknown>;
46 +};
48 +const duplicateTopLevelKeys = (source: string): string[] => {
49 + const keys: string[] = [];
50 + const duplicates = new Set<string>();
51 + let depth = 0;
52 + let index = 0;
53 + while (index < source.length) {
54 + const character = source[index];
55 + if (character === "{") {
56 + depth += 1;
57 + index += 1;
58 + continue;
59 + }
60 + if (character === "}") {
61 + depth -= 1;
62 + index += 1;
63 + continue;
64 + }
65 + if (character !== '"') {
66 + index += 1;
67 + continue;
68 + }
69 + const start = index++;
70 + let escaped = false;
71 + while (index < source.length) {
72 + const current = source[index++];
73 + if (!escaped && current === '"') break;
74 + escaped = !escaped && current === "\\";
75 + if (current !== "\\") escaped = false;
76 + }
77 + if (depth !== 1) continue;
78 + let cursor = index;
79 + while (/\s/.test(source[cursor] ?? "")) cursor += 1;
80 + if (source[cursor] !== ":") continue;
81 + const key = JSON.parse(source.slice(start, index)) as string;
82 + if (keys.includes(key)) duplicates.add(key);
83 + keys.push(key);
84 + }
85 + return [...duplicates].sort();
86 +};
88 +export function parseSystemConfig(source: string): SystemConfig {
89 + let parsed: unknown;
90 + try {
91 + parsed = JSON.parse(source);
92 + } catch {
93 + throw new SystemDocumentError("config.invalid-json", "Invalid config JSON");
94 + }
95 + const duplicates = duplicateTopLevelKeys(source);
96 + if (duplicates.length)
97 + throw new SystemDocumentError(
98 + "config.duplicate-key",
99 + `Duplicate config keys: ${duplicates.join(", ")}`,
100 + );
101 + const value = objectValue(parsed, "Config");
102 + if (value.schemaVersion !== SCHEMA_VERSION)
103 + throw new SystemDocumentError(
104 + "config.version",
105 + `Schema version ${String(value.schemaVersion)} does not match ${SCHEMA_VERSION}; run /system init`,
106 + );
107 + const keys = Object.keys(value).sort();
108 + const validKeys = ["currentPhase", "prefix", "schemaVersion", "title"];
109 + if (
110 + !("prefix" in value) ||
111 + !("schemaVersion" in value) ||
112 + keys.some((key) => !validKeys.includes(key))
114 + throw new SystemDocumentError(
115 + "json.keys",
116 + `Expected keys prefix, schemaVersion[, title, currentPhase]; received ${keys.join(", ")}`,
117 + );
118 + if (typeof value.prefix !== "string" || !PREFIX.test(value.prefix))
119 + throw new SystemDocumentError("config.prefix", "Invalid project prefix");
120 + if (
121 + "title" in value &&
122 + (typeof value.title !== "string" || value.title.trim() === "")
124 + throw new SystemDocumentError("config.title", "Invalid project title");
125 + if ("currentPhase" in value) {
126 + if (typeof value.currentPhase !== "string")
127 + throw new SystemDocumentError(
128 + "config.current-phase",
129 + "Current phase must be a phase ID",
130 + );
131 + const current = parseDocumentId(value.currentPhase, value.prefix);
132 + if (current.type !== "phase")
133 + throw new SystemDocumentError(
134 + "config.current-phase",
135 + "Current phase must be a phase ID",
136 + );
138 + return {
139 + prefix: value.prefix,
140 + schemaVersion: value.schemaVersion as number,
141 + ...(typeof value.title === "string" ? { title: value.title } : {}),
142 + ...(typeof value.currentPhase === "string"
143 + ? { currentPhase: value.currentPhase }
144 + : {}),
145 + };
148 +export function systemConfigForInitialization(
149 + source: string,
150 +): InitializationSystemConfig {
151 + try {
152 + return { config: parseSystemConfig(source) };
153 + } catch (error) {
154 + if (
155 + !(error instanceof SystemDocumentError) ||
156 + error.code !== "config.version"
158 + throw error;
159 + const parsed = objectValue(JSON.parse(source), "Config");
160 + if (
161 + duplicateTopLevelKeys(source).length > 0 ||
162 + typeof parsed.schemaVersion !== "number" ||
163 + !Number.isInteger(parsed.schemaVersion)
165 + throw error;
166 + const config = parseSystemConfig(
167 + JSON.stringify({
168 + prefix: parsed.prefix,
169 + schemaVersion: SCHEMA_VERSION,
170 + ...("title" in parsed ? { title: parsed.title } : {}),
171 + ...("currentPhase" in parsed
172 + ? { currentPhase: parsed.currentPhase }
173 + : {}),
174 + }),
175 + );
176 + return { config, sourceSchemaVersion: parsed.schemaVersion };
180 +export function parseDocumentId(
181 + source: string,
182 + expectedPrefix?: string,
183 +): ParsedDocumentId {
184 + const match = new RegExp(
185 + `^([A-Z][A-Z0-9]{1,7})-(SPEC|PHASE|PLAN|ISSUE|RESEARCH)-(${ID_CHARS})$`,
186 + ).exec(source);
187 + if (!match)
188 + throw new SystemDocumentError(
189 + "id.invalid",
190 + `Invalid document ID: ${source}`,
191 + );
192 + if (expectedPrefix && match[1] !== expectedPrefix)
193 + throw new SystemDocumentError(
194 + "id.prefix",
195 + `Document ID must use prefix ${expectedPrefix}: ${source}`,
196 + );
197 + return {
198 + id: source,
199 + prefix: match[1] as string,
200 + type: TYPE_BY_TOKEN.get(match[2]) as DocumentType,
201 + token: match[3] as string,
202 + };