@schilderlabs/pitown-package 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Schilder Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @schilderlabs/pitown-package
+
+Optional Pi package resources for Pi Town.
+
+This package is intended for deeper Pi integration later, including bundled prompts and extensions.

package/dist/index.d.mts

@@ -0,0 +1,10 @@
+//#region src/index.d.ts
+declare const bundledAgentNames: readonly ["leader", "supervisor", "scout", "planner", "worker", "reviewer", "docs-keeper"];
+declare const townPackageName = "@schilderlabs/pitown-package";
+declare function resolvePiTownPackageRoot(): string;
+declare function resolvePiTownExtensionPath(): string;
+declare function resolvePiTownMayorPromptPath(): string;
+declare function readPiTownMayorPrompt(): string;
+//#endregion
+export { bundledAgentNames, readPiTownMayorPrompt, resolvePiTownExtensionPath, resolvePiTownMayorPromptPath, resolvePiTownPackageRoot, townPackageName };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,34 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+//#region src/index.ts
+const bundledAgentNames = [
+	"leader",
+	"supervisor",
+	"scout",
+	"planner",
+	"worker",
+	"reviewer",
+	"docs-keeper"
+];
+const townPackageName = "@schilderlabs/pitown-package";
+function resolvePackageRoot() {
+	return join(dirname(fileURLToPath(import.meta.url)), "..");
+}
+function resolvePiTownPackageRoot() {
+	return resolvePackageRoot();
+}
+function resolvePiTownExtensionPath() {
+	return join(resolvePackageRoot(), "pi", "extensions", "index.ts");
+}
+function resolvePiTownMayorPromptPath() {
+	return join(resolvePackageRoot(), "pi", "agents", "leader.md");
+}
+function readPiTownMayorPrompt() {
+	return readFileSync(resolvePiTownMayorPromptPath(), "utf-8");
+}
+
+//#endregion
+export { bundledAgentNames, readPiTownMayorPrompt, resolvePiTownExtensionPath, resolvePiTownMayorPromptPath, resolvePiTownPackageRoot, townPackageName };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\"\nimport { dirname, join } from \"node:path\"\nimport { fileURLToPath } from \"node:url\"\n\nexport const bundledAgentNames = [\n\t\"leader\",\n\t\"supervisor\",\n\t\"scout\",\n\t\"planner\",\n\t\"worker\",\n\t\"reviewer\",\n\t\"docs-keeper\",\n] as const\n\nexport const townPackageName = \"@schilderlabs/pitown-package\"\n\nfunction resolvePackageRoot() {\n\treturn join(dirname(fileURLToPath(import.meta.url)), \"..\")\n}\n\nexport function resolvePiTownPackageRoot() {\n\treturn resolvePackageRoot()\n}\n\nexport function resolvePiTownExtensionPath() {\n\treturn join(resolvePackageRoot(), \"pi\", \"extensions\", \"index.ts\")\n}\n\nexport function resolvePiTownMayorPromptPath() {\n\treturn join(resolvePackageRoot(), \"pi\", \"agents\", \"leader.md\")\n}\n\nexport function readPiTownMayorPrompt() {\n\treturn readFileSync(resolvePiTownMayorPromptPath(), \"utf-8\")\n}\n"],"mappings":";;;;;AAIA,MAAa,oBAAoB;CAChC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AAED,MAAa,kBAAkB;AAE/B,SAAS,qBAAqB;AAC7B,QAAO,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC,EAAE,KAAK;;AAG3D,SAAgB,2BAA2B;AAC1C,QAAO,oBAAoB;;AAG5B,SAAgB,6BAA6B;AAC5C,QAAO,KAAK,oBAAoB,EAAE,MAAM,cAAc,WAAW;;AAGlE,SAAgB,+BAA+B;AAC9C,QAAO,KAAK,oBAAoB,EAAE,MAAM,UAAU,YAAY;;AAG/D,SAAgB,wBAAwB;AACvC,QAAO,aAAa,8BAA8B,EAAE,QAAQ"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@schilderlabs/pitown-package",
+  "version": "0.2.1",
+  "description": "Pi package resources for Pi Town",
+  "type": "module",
+  "imports": {
+    "#pitown-extension": "./pi/extensions/index.ts",
+    "#pitown-package-api": "./src/index.ts",
+    "#pitown-mayor-plan": "./pi/extensions/mayor-plan.ts",
+    "#pitown-town-tools": "./pi/extensions/town-tools.ts"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    }
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "pi",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "keywords": [
+    "pitown",
+    "pi-package",
+    "pi",
+    "agents",
+    "orchestration",
+    "night-shift"
+  ],
+  "pi": {
+    "extensions": [
+      "./pi/extensions"
+    ],
+    "prompts": [
+      "./pi/prompts"
+    ]
+  },
+  "dependencies": {
+    "@mariozechner/pi-ai": "0.58.3",
+    "@schilderlabs/pitown-core": "0.2.1"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "0.58.3",
+    "eslint": "9.39.3",
+    "tsdown": "0.20.3",
+    "typescript": "5.9.2",
+    "vitest": "4.0.18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RobSchilderr/pitown.git"
+  },
+  "homepage": "https://github.com/RobSchilderr/pitown#readme",
+  "bugs": {
+    "url": "https://github.com/RobSchilderr/pitown/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/pi/agents/docs-keeper.md

@@ -0,0 +1,14 @@
+---
+name: docs-keeper
+description: Summarizes overnight outcomes into concise human-readable updates
+tools: read, grep, find, ls
+---
+
+You are the Pi Town docs keeper.
+
+Your job is to summarize outcomes, blockers, and continuity for the next run.
+
+Rules:
+- keep summaries factual and compact
+- capture blockers clearly
+- preserve enough context for the next unattended cycle

package/pi/agents/leader.md

@@ -0,0 +1,21 @@
+---
+name: mayor
+description: Primary human-facing coordinator for a Pi Town repo
+tools: read, grep, find, ls, pitown_board, pitown_delegate, pitown_message_agent, pitown_peek_agent, pitown_update_status
+---
+
+You are the Pi Town mayor.
+
+Your job is to coordinate work across the repo and act as the primary interface for the human operator.
+
+Rules:
+- `/plan` puts you into read-only planning mode; use it before execution when the user wants to think through the work first
+- use `pitown_board` before delegating or redirecting work
+- use `pitown_delegate` for bounded implementation, review, or documentation tasks
+- use `pitown_peek_agent` before assuming a worker is blocked or idle
+- use `pitown_message_agent` to redirect or clarify work instead of restating the full task
+- use `pitown_update_status` to keep your own mayor state current in short, high-signal updates
+- break large goals into bounded tasks before delegating
+- prefer spawning focused workers over doing everything yourself
+- check blockers, open questions, and active agent state before creating more work
+- escalate clearly when the next step depends on a human product or policy decision

package/pi/agents/planner.md

@@ -0,0 +1,15 @@
+---
+name: planner
+description: Turns a bounded task into a concrete implementation plan
+tools: read, grep, find, ls
+---
+
+You are the Pi Town planner.
+
+Your job is to turn the task and scout findings into a concrete implementation brief.
+
+Rules:
+- do not change code
+- keep the plan small and specific
+- include checks and risks
+- keep the worker focused on one deliverable

package/pi/agents/reviewer.md

@@ -0,0 +1,15 @@
+---
+name: reviewer
+description: Reviews changes against task intent, repo rules, and code quality
+tools: read, grep, find, ls, bash
+---
+
+You are the Pi Town reviewer.
+
+Review the current changes for correctness, safety, and completeness.
+
+Focus on:
+- task alignment
+- code quality
+- validation confidence
+- whether the work is good enough to reach a human in polished form

package/pi/agents/scout.md

@@ -0,0 +1,15 @@
+---
+name: scout
+description: Fast codebase recon with concise handoff for other agents
+tools: read, grep, find, ls, bash
+---
+
+You are the Pi Town scout.
+
+Your job is to gather the smallest useful body of context so another agent can act without rereading the entire codebase.
+
+Output:
+- relevant files
+- architecture notes
+- likely change points
+- risks and unknowns

package/pi/agents/supervisor.md

@@ -0,0 +1,16 @@
+---
+name: supervisor
+description: Selects the next bounded unit of overnight work
+tools: read, grep, find, ls
+---
+
+You are the Pi Town supervisor.
+
+Your job is to choose the next best bounded task for an unattended run.
+
+Rules:
+- do not edit code
+- prefer one bounded deliverable
+- prefer tasks that unlock downstream work
+- avoid tasks that require remote side effects or human credentials
+- stop and record blockers clearly when the task is underspecified

package/pi/agents/worker.md

@@ -0,0 +1,15 @@
+---
+name: worker
+description: Implements one bounded task at a time
+tools: read, bash, edit, write, grep, find, ls
+---
+
+You are the Pi Town worker.
+
+You implement one bounded task at a time.
+
+Rules:
+- keep scope tight
+- prefer explicit validations before finishing
+- do not widen the task without saying so
+- summarize what changed and what still needs follow-up

package/pi/extensions/index.test.ts

@@ -0,0 +1,288 @@
+import { mkdtempSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"
+import {
+	createAgentSessionRecord,
+	createAgentState,
+	createTaskRecord,
+	readAgentState,
+	readTaskRecord,
+	writeAgentState,
+	writeTaskRecord,
+} from "@schilderlabs/pitown-core"
+import { describe, expect, it, vi } from "vitest"
+
+import piTownPackage from "#pitown-extension"
+
+type RegisteredHandler = (event: unknown, ctx: unknown) => unknown | Promise<unknown>
+
+function createRepoArtifacts() {
+	const repoRoot = mkdtempSync(join(tmpdir(), "pitown-repo-"))
+	const artifactsDir = join(mkdtempSync(join(tmpdir(), "pitown-home-")), "repos", "demo-repo")
+
+	const leaderSessionDir = join(artifactsDir, "agents", "leader", "sessions")
+	const workerSessionDir = join(artifactsDir, "agents", "worker-001", "sessions")
+	const reviewerSessionDir = join(artifactsDir, "agents", "reviewer-001", "sessions")
+	const leaderSessionFile = join(leaderSessionDir, "session_leader.jsonl")
+	const workerSessionFile = join(workerSessionDir, "session_worker.jsonl")
+
+	writeAgentState(
+		artifactsDir,
+		createAgentState({
+			agentId: "leader",
+			role: "leader",
+			status: "running",
+			task: "coordinate town work",
+			lastMessage: "checking board",
+			session: createAgentSessionRecord({
+				sessionDir: leaderSessionDir,
+				sessionPath: leaderSessionFile,
+				sessionId: "leader",
+			}),
+		}),
+	)
+	writeAgentState(
+		artifactsDir,
+		createAgentState({
+			agentId: "worker-001",
+			role: "worker",
+			status: "queued",
+			taskId: "task-123",
+			task: "fix the failing auth flow",
+			session: createAgentSessionRecord({
+				sessionDir: workerSessionDir,
+				sessionPath: workerSessionFile,
+				sessionId: "worker",
+			}),
+		}),
+	)
+	writeAgentState(
+		artifactsDir,
+		createAgentState({
+			agentId: "reviewer-001",
+			role: "reviewer",
+			status: "idle",
+			task: null,
+			session: createAgentSessionRecord({
+				sessionDir: reviewerSessionDir,
+				sessionPath: join(reviewerSessionDir, "session_reviewer.jsonl"),
+				sessionId: "reviewer",
+			}),
+		}),
+	)
+	writeTaskRecord(
+		artifactsDir,
+		createTaskRecord({
+			taskId: "task-123",
+			title: "fix the failing auth flow",
+			status: "queued",
+			role: "worker",
+			assignedAgentId: "worker-001",
+			createdBy: "leader",
+		}),
+	)
+
+	return { repoRoot, artifactsDir, leaderSessionFile, workerSessionFile }
+}
+
+function setup() {
+	const handlers: Record<string, RegisteredHandler[]> = {}
+	const tools = new Map<string, { execute: RegisteredHandler }>()
+	const commands = new Map<string, unknown>()
+	const flags = new Map<string, unknown>()
+	const activeTools: string[] = [
+		"read",
+		"grep",
+		"find",
+		"ls",
+		"pitown_board",
+		"pitown_delegate",
+		"pitown_message_agent",
+		"pitown_peek_agent",
+		"pitown_update_status",
+	]
+	const appendedEntries: Array<{ customType: string; data: unknown }> = []
+	const pi = {
+		on: vi.fn((event: string, handler: RegisteredHandler) => {
+			;(handlers[event] ??= []).push(handler)
+		}),
+		registerTool: vi.fn((definition: { name: string; execute: RegisteredHandler }) => {
+			tools.set(definition.name, definition)
+		}),
+		registerCommand: vi.fn((name: string, definition: unknown) => {
+			commands.set(name, definition)
+		}),
+		registerFlag: vi.fn((name: string, definition: unknown) => {
+			flags.set(name, definition)
+		}),
+		getFlag: vi.fn(() => undefined),
+		getActiveTools: vi.fn(() => [...activeTools]),
+		getAllTools: vi.fn(() => activeTools.map((name) => ({ name }))),
+		setActiveTools: vi.fn((toolNames: string[]) => {
+			activeTools.splice(0, activeTools.length, ...toolNames)
+		}),
+		appendEntry: vi.fn((customType: string, data?: unknown) => {
+			appendedEntries.push({ customType, data })
+		}),
+		sendMessage: vi.fn(),
+	} as unknown as ExtensionAPI & {
+		appendEntry: ReturnType<typeof vi.fn>
+		getActiveTools: ReturnType<typeof vi.fn>
+		getAllTools: ReturnType<typeof vi.fn>
+		getFlag: ReturnType<typeof vi.fn>
+		registerFlag: ReturnType<typeof vi.fn>
+		setActiveTools: ReturnType<typeof vi.fn>
+		sendMessage: ReturnType<typeof vi.fn>
+	}
+
+	piTownPackage(pi)
+
+	return { handlers, tools, commands, flags, appendedEntries, activeTools, pi }
+}
+
+function createToolContext(repoRoot: string, sessionFile: string) {
+	return {
+		hasUI: true,
+		ui: {
+			notify: vi.fn(),
+			setStatus: vi.fn(),
+			setWidget: vi.fn(),
+			theme: {
+				fg: vi.fn((_token: string, value: string) => value),
+			},
+		},
+		cwd: repoRoot,
+		sessionManager: {
+			getSessionFile: () => sessionFile,
+			getEntries: () => [],
+		},
+	}
+}
+
+describe("pi town extension", () => {
+	it("injects hidden town context for managed leader sessions", async () => {
+		const { repoRoot, leaderSessionFile } = createRepoArtifacts()
+		const { handlers } = setup()
+
+		const result = await handlers["before_agent_start"]?.[0]?.(
+			{ systemPrompt: "base", prompt: "coordinate", images: [] },
+			createToolContext(repoRoot, leaderSessionFile),
+		)
+
+		expect(result).toEqual(
+			expect.objectContaining({
+				message: expect.objectContaining({
+					customType: "pitown-context",
+					display: false,
+					content: expect.stringContaining("Allowed Pi Town tools: pitown_board, pitown_delegate"),
+				}),
+			}),
+		)
+	})
+
+	it("renders the live board for town-managed sessions", async () => {
+		const { repoRoot, leaderSessionFile } = createRepoArtifacts()
+		const { tools } = setup()
+		const boardTool = tools.get("pitown_board")
+
+		const result = await boardTool?.execute("tool-call", {}, undefined, () => {}, createToolContext(repoRoot, leaderSessionFile))
+
+		expect(result).toEqual(
+			expect.objectContaining({
+				content: [expect.objectContaining({ text: expect.stringContaining("worker-001") })],
+			}),
+		)
+	})
+
+	it("blocks workers from messaging non-leader agents directly", async () => {
+		const { repoRoot, workerSessionFile } = createRepoArtifacts()
+		const { tools } = setup()
+		const messageTool = tools.get("pitown_message_agent")
+
+		await expect(
+			messageTool?.execute(
+				"tool-call",
+				{ agentId: "reviewer-001", body: "please review now" },
+				undefined,
+				() => {},
+				createToolContext(repoRoot, workerSessionFile),
+			),
+		).rejects.toThrow("Only the leader may message non-leader agents")
+	})
+
+	it("updates worker state and task status through the status tool", async () => {
+		const { artifactsDir, repoRoot, workerSessionFile } = createRepoArtifacts()
+		const { tools } = setup()
+		const statusTool = tools.get("pitown_update_status")
+
+		await statusTool?.execute(
+			"tool-call",
+			{ status: "completed", lastMessage: "auth flow fixed", blocked: false },
+			undefined,
+			() => {},
+			createToolContext(repoRoot, workerSessionFile),
+		)
+
+		expect(readAgentState(artifactsDir, "worker-001")).toEqual(
+			expect.objectContaining({
+				status: "completed",
+				lastMessage: "auth flow fixed",
+			}),
+		)
+		expect(readTaskRecord(artifactsDir, "task-123")).toEqual(
+			expect.objectContaining({
+				status: "completed",
+			}),
+		)
+	})
+
+	it("enables mayor plan mode with a read-only tool set", async () => {
+		const { repoRoot, leaderSessionFile } = createRepoArtifacts()
+		const { commands, activeTools, appendedEntries } = setup()
+		const planCommand = commands.get("plan") as { handler: RegisteredHandler } | undefined
+		const ctx = createToolContext(repoRoot, leaderSessionFile)
+
+		await planCommand?.handler([], ctx)
+
+		expect(activeTools).toEqual(["read", "grep", "find", "ls", "pitown_board", "pitown_peek_agent"])
+		expect(appendedEntries.at(-1)).toEqual(
+			expect.objectContaining({
+				customType: "pitown-mayor-plan",
+			}),
+		)
+	})
+
+	it("captures numbered mayor plan steps after a planning turn", async () => {
+		const { repoRoot, leaderSessionFile } = createRepoArtifacts()
+		const { commands, handlers, pi } = setup()
+		const planCommand = commands.get("plan") as { handler: RegisteredHandler } | undefined
+		const ctx = createToolContext(repoRoot, leaderSessionFile)
+
+		await planCommand?.handler([], ctx)
+		await handlers["agent_end"]?.[0]?.(
+			{
+				messages: [
+					{
+						role: "assistant",
+						content: [
+							{
+								type: "text",
+								text: "Plan:\n1. Inspect the current board and open tasks.\n2. Split the work into two bounded worker tasks.",
+							},
+						],
+					},
+				],
+			},
+			ctx,
+		)
+
+		expect(pi.sendMessage).toHaveBeenCalledWith(
+			expect.objectContaining({
+				customType: "pitown-mayor-plan-captured",
+				content: expect.stringContaining("1. ○ Inspect the current board and open tasks."),
+			}),
+			{ triggerTurn: false },
+		)
+	})
+})

package/pi/extensions/index.ts

@@ -0,0 +1,64 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"
+import { registerMayorPlanMode } from "#pitown-mayor-plan"
+import { registerTownTools } from "#pitown-town-tools"
+
+const extensionDir = dirname(fileURLToPath(import.meta.url))
+const agentsDir = join(extensionDir, "..", "agents")
+
+function parseFrontmatter(content: string): { frontmatter: Record<string, string>; body: string } {
+	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/)
+	if (!match) return { frontmatter: {}, body: content.trim() }
+
+	const frontmatter: Record<string, string> = {}
+	for (const rawLine of match[1]!.split(/\r?\n/)) {
+		const index = rawLine.indexOf(":")
+		if (index === -1) continue
+		frontmatter[rawLine.slice(0, index).trim()] = rawLine.slice(index + 1).trim()
+	}
+
+	return { frontmatter, body: match[2]!.trim() }
+}
+
+function listBundledAgents(): Array<{ name: string; description: string }> {
+	if (!existsSync(agentsDir)) return []
+
+	return readdirSync(agentsDir)
+		.filter((file) => file.endsWith(".md"))
+		.map((file) => {
+			const content = readFileSync(join(agentsDir, file), "utf-8")
+			const { frontmatter } = parseFrontmatter(content)
+			return {
+				name: frontmatter["name"] ?? file.replace(/\.md$/, ""),
+				description: frontmatter["description"] ?? "",
+			}
+		})
+}
+
+export default function piTownPackage(pi: ExtensionAPI) {
+	registerTownTools(pi)
+	registerMayorPlanMode(pi)
+
+	pi.registerCommand("town-status", {
+		description: "Show Pi Town package status",
+		handler: async (_args, ctx) => {
+			ctx.ui.notify("Pi Town package loaded. Use /town-agents to inspect bundled roles.", "info")
+		},
+	})
+
+	pi.registerCommand("town-agents", {
+		description: "List bundled Pi Town agents",
+		handler: async (_args, ctx) => {
+			const agents = listBundledAgents()
+			if (agents.length === 0) {
+				ctx.ui.notify("No bundled Pi Town agents were found.", "warning")
+				return
+			}
+
+			const lines = ["Bundled Pi Town agents:", ...agents.map((agent) => `- ${agent.name}: ${agent.description}`)]
+			ctx.ui.notify(lines.join("\n"), "info")
+		},
+	})
+}