@schilderlabs/pitown-package 0.2.1

package/pi/extensions/town-tools.ts

@@ -0,0 +1,309 @@
+import { Type } from "@mariozechner/pi-ai"
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent"
+import {
+	delegateTask,
+	listAgentStates,
+	queueAgentMessage,
+	readAgentMessages,
+	readAgentState,
+	updateAgentStatus,
+} from "@schilderlabs/pitown-core"
+import { readPiTownMayorPrompt, resolvePiTownExtensionPath } from "#pitown-package-api"
+
+type TownToolName =
+	| "pitown_board"
+	| "pitown_delegate"
+	| "pitown_message_agent"
+	| "pitown_peek_agent"
+	| "pitown_update_status"
+
+interface TownAgentContext {
+	artifactsDir: string
+	repoSlug: string
+	agentId: string
+	role: string
+	sessionFile: string
+}
+
+const ROLE_STATUS = Type.Union([
+	Type.Literal("queued"),
+	Type.Literal("running"),
+	Type.Literal("idle"),
+	Type.Literal("blocked"),
+	Type.Literal("completed"),
+	Type.Literal("failed"),
+])
+
+const toolPermissions: Record<string, TownToolName[]> = {
+	leader: ["pitown_board", "pitown_delegate", "pitown_message_agent", "pitown_peek_agent", "pitown_update_status"],
+	worker: ["pitown_board", "pitown_message_agent", "pitown_peek_agent", "pitown_update_status"],
+	reviewer: ["pitown_board", "pitown_message_agent", "pitown_peek_agent", "pitown_update_status"],
+	"docs-keeper": ["pitown_board", "pitown_message_agent", "pitown_peek_agent", "pitown_update_status"],
+}
+
+export function resolveTownAgentContext(sessionFile: string | null | undefined): TownAgentContext | null {
+	if (!sessionFile) return null
+
+	const normalizedSessionFile = sessionFile.replace(/\\/g, "/")
+	const match = normalizedSessionFile.match(/^(.*\/repos\/([^/]+))\/agents\/([^/]+)\/sessions\/[^/]+\.jsonl$/)
+	if (!match) return null
+
+	const artifactsDir = match[1]
+	const repoSlug = match[2]
+	const agentId = match[3]
+	if (!artifactsDir || !repoSlug || !agentId) return null
+
+	const state = readAgentState(artifactsDir, agentId)
+	if (state === null) return null
+
+	return {
+		artifactsDir,
+		repoSlug,
+		agentId,
+		role: state.role,
+		sessionFile: normalizedSessionFile,
+	}
+}
+
+function getAllowedTools(role: string): TownToolName[] {
+	return toolPermissions[role] ?? ["pitown_board"]
+}
+
+function assertPermission(context: TownAgentContext, toolName: TownToolName, targetAgentId?: string) {
+	if (!getAllowedTools(context.role).includes(toolName)) {
+		throw new Error(`${context.role} agents may not use ${toolName}`)
+	}
+
+	if (toolName === "pitown_delegate" && context.role !== "leader") {
+		throw new Error("Only the leader may delegate work")
+	}
+
+	if (toolName === "pitown_message_agent" && context.role !== "leader" && targetAgentId && targetAgentId !== "leader") {
+		throw new Error("Only the leader may message non-leader agents")
+	}
+
+	if (toolName === "pitown_peek_agent" && context.role !== "leader" && targetAgentId) {
+		const allowedTargets = new Set([context.agentId, "leader"])
+		if (!allowedTargets.has(targetAgentId)) {
+			throw new Error("Non-leader agents may only peek themselves or the leader")
+		}
+	}
+}
+
+function formatBoard(artifactsDir: string): string {
+	const agents = listAgentStates(artifactsDir)
+	if (agents.length === 0) return "No agents found."
+
+	return agents
+		.map((agent) => {
+			const task = agent.task ?? "no active task"
+			const taskId = agent.taskId ? ` [${agent.taskId}]` : ""
+			const note = agent.lastMessage ? ` | ${agent.lastMessage}` : ""
+			const waitingOn = agent.waitingOn ? ` | waiting on: ${agent.waitingOn}` : ""
+			return `${agent.agentId.padEnd(12)} ${agent.status.padEnd(9)} ${task}${taskId}${note}${waitingOn}`
+		})
+		.join("\n")
+}
+
+function formatMailbox(artifactsDir: string, agentId: string, box: "inbox" | "outbox"): string {
+	const records = readAgentMessages(artifactsDir, agentId, box).slice(-3)
+	if (records.length === 0) return `${box}: empty`
+
+	return `${box}:\n${records.map((record) => `- ${record.from}: ${record.body}`).join("\n")}`
+}
+
+function buildStartupContext(context: TownAgentContext): string {
+	const state = readAgentState(context.artifactsDir, context.agentId)
+	if (state === null) throw new Error(`Unknown agent: ${context.agentId}`)
+
+	const currentTask = state.task ?? "no active task"
+	const board = formatBoard(context.artifactsDir)
+	const tools = getAllowedTools(context.role).join(", ")
+
+	return [
+		`Pi Town agent context: ${context.agentId} (${context.role})`,
+		`Repo slug: ${context.repoSlug}`,
+		`Current task: ${currentTask}`,
+		`Allowed Pi Town tools: ${tools}`,
+		"",
+		"Current board:",
+		board,
+	].join("\n")
+}
+
+function requireTownContext(ctx: ExtensionContext): TownAgentContext {
+	const context = resolveTownAgentContext(ctx.sessionManager.getSessionFile())
+	if (context === null) {
+		throw new Error("This Pi session is not managed by Pi Town")
+	}
+	return context
+}
+
+export function registerTownTools(pi: ExtensionAPI) {
+	pi.on("before_agent_start", async (_event, ctx) => {
+		const context = resolveTownAgentContext(ctx.sessionManager.getSessionFile())
+		if (context === null) return undefined
+
+		return {
+			message: {
+				customType: "pitown-context",
+				content: buildStartupContext(context),
+				display: false,
+			},
+		}
+	})
+
+	pi.registerTool({
+		name: "pitown_board",
+		label: "Pi Town Board",
+		description: "Show the current Pi Town board with all known agents and their statuses",
+		parameters: Type.Object({}),
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			const context = requireTownContext(ctx)
+			assertPermission(context, "pitown_board")
+
+			return {
+				content: [{ type: "text", text: formatBoard(context.artifactsDir) }],
+				details: { agentId: context.agentId, role: context.role },
+			}
+		},
+	})
+
+	pi.registerTool({
+		name: "pitown_delegate",
+		label: "Pi Town Delegate",
+		description: "Delegate a bounded task to a new Pi Town agent",
+		parameters: Type.Object({
+			role: Type.String({ description: "Agent role to spawn, such as worker or reviewer" }),
+			task: Type.String({ description: "Bounded task description" }),
+			agentId: Type.Optional(Type.String({ description: "Optional explicit agent id" })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const context = requireTownContext(ctx)
+			assertPermission(context, "pitown_delegate")
+			const input = params as { role: string; task: string; agentId?: string }
+
+			const result = delegateTask({
+				repoRoot: ctx.cwd,
+				artifactsDir: context.artifactsDir,
+				fromAgentId: context.agentId,
+				role: input.role,
+				task: input.task,
+				agentId: input.agentId ?? null,
+				extensionPath: resolvePiTownExtensionPath(),
+				appendedSystemPrompt: input.role === "leader" ? readPiTownMayorPrompt() : null,
+			})
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Delegated ${result.task.taskId} to ${result.agentId} (${input.role}). Exit code: ${result.piResult.exitCode}.`,
+					},
+				],
+				details: {
+					taskId: result.task.taskId,
+					agentId: result.agentId,
+					status: result.task.status,
+					sessionPath: result.latestSession.sessionPath,
+				},
+			}
+		},
+	})
+
+	pi.registerTool({
+		name: "pitown_message_agent",
+		label: "Pi Town Message Agent",
+		description: "Send a durable message to another Pi Town agent",
+		parameters: Type.Object({
+			agentId: Type.String({ description: "Target Pi Town agent id" }),
+			body: Type.String({ description: "Message body" }),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const context = requireTownContext(ctx)
+			const input = params as { agentId: string; body: string }
+			assertPermission(context, "pitown_message_agent", input.agentId)
+
+			queueAgentMessage({
+				artifactsDir: context.artifactsDir,
+				agentId: input.agentId,
+				from: context.agentId,
+				body: input.body,
+			})
+
+			return {
+				content: [{ type: "text", text: `Queued message for ${input.agentId}.` }],
+				details: { agentId: input.agentId },
+			}
+		},
+	})
+
+	pi.registerTool({
+		name: "pitown_peek_agent",
+		label: "Pi Town Peek Agent",
+		description: "Inspect another Pi Town agent's current state and recent mailbox activity",
+		parameters: Type.Object({
+			agentId: Type.String({ description: "Agent id to inspect" }),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const context = requireTownContext(ctx)
+			const input = params as { agentId: string }
+			assertPermission(context, "pitown_peek_agent", input.agentId)
+
+			const state = readAgentState(context.artifactsDir, input.agentId)
+			if (state === null) throw new Error(`Unknown agent: ${input.agentId}`)
+
+			const summary = [
+				`${state.agentId} (${state.role})`,
+				`status: ${state.status}`,
+				`task: ${state.task ?? "none"}`,
+				`taskId: ${state.taskId ?? "none"}`,
+				`last message: ${state.lastMessage ?? "none"}`,
+				`waiting on: ${state.waitingOn ?? "none"}`,
+				formatMailbox(context.artifactsDir, input.agentId, "inbox"),
+				formatMailbox(context.artifactsDir, input.agentId, "outbox"),
+			].join("\n")
+
+			return {
+				content: [{ type: "text", text: summary }],
+				details: { agentId: state.agentId, status: state.status, taskId: state.taskId },
+			}
+		},
+	})
+
+	pi.registerTool({
+		name: "pitown_update_status",
+		label: "Pi Town Update Status",
+		description: "Update this Pi Town agent's durable status on the board",
+		parameters: Type.Object({
+			status: ROLE_STATUS,
+			lastMessage: Type.Optional(Type.String({ description: "Short progress update" })),
+			waitingOn: Type.Optional(Type.String({ description: "What this agent is waiting on, if anything" })),
+			blocked: Type.Optional(Type.Boolean({ description: "Whether the agent is currently blocked" })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const context = requireTownContext(ctx)
+			assertPermission(context, "pitown_update_status")
+			const input = params as {
+				status: "queued" | "running" | "idle" | "blocked" | "completed" | "failed"
+				lastMessage?: string
+				waitingOn?: string
+				blocked?: boolean
+			}
+
+			updateAgentStatus({
+				artifactsDir: context.artifactsDir,
+				agentId: context.agentId,
+				status: input.status,
+				lastMessage: input.lastMessage ?? null,
+				waitingOn: input.waitingOn ?? null,
+				blocked: input.blocked,
+			})
+
+			return {
+				content: [{ type: "text", text: `Updated ${context.agentId} to ${input.status}.` }],
+				details: { agentId: context.agentId, status: input.status },
+			}
+		},
+	})
+}

package/pi/prompts/overnight-start.md

@@ -0,0 +1,8 @@
+Start a Pi Town overnight run.
+
+Goals:
+- choose one bounded task
+- keep context explicit and minimal
+- prefer scout -> planner -> worker -> reviewer
+- record blockers instead of stalling forever
+- optimize for reviewed progress, not raw output volume

package/pi/prompts/retry-task.md

@@ -0,0 +1,8 @@
+Retry the current task with the newest available context.
+
+Checklist:
+1. restate the task briefly
+2. identify what blocked the prior attempt
+3. narrow the scope if needed
+4. prefer structural fixes over repeated blind retries
+5. stop and record a blocker if human input is truly required