[ { "path": ".gitignore", "content": "result\nconfig/fish/fish_variables\n__pycache__\n\nnushell/history*\nbin\nnode_modules\n" }, { "path": ".gitmodules", "content": "[submodule \"dotbot\"]\n\tpath = dotbot\n\turl = https://github.com/anishathalye/dotbot\n\tignore = dirty\n" }, { "path": "Makefile", "content": "linux:\n\tnh home switch --flake .#elianiva --print-build-logs\n\ndarwin:\n\tnh darwin switch .\n\nclean:\n\tnh clean\n" }, { "path": "README.md", "content": "# elianiva's personal dotfiles\n\nThis is my personal dotfiles repository which has gone through many iterations.\n\nHere are some of the screenshots from time to time (the config may or may not be still here, idk):\n\n![arch](./screenshots/preview-arch.png)\n![arch-new](./screenshots/preview-arch-new.png)\n![old](./screenshots/preview-old.png)\n![plasma](./screenshots/preview-plasma.png)\n![fedora](./screenshots/preview-fedora.png)\n![fedora-2](https://github.com/user-attachments/assets/ce263afd-1986-4c55-93a8-10494302c464)\n![macos](https://github.com/user-attachments/assets/e6a1be22-b773-4e0c-b022-eedc70fa8ca8)\n" }, { "path": "agents/AGENTS.md", "content": "# Important Rules\n- Be extremely concise. Sacrifice grammar for the sake of concision.\n- Don't add tests for what the type system already guarantees.\n- At the end of each plan, give me a list of unresolved questions to answer, if any. The last thing visible should be numbered list of questions or concrete steps.\n- No compatibility wrappers, no legacy shims, no temporary plumbing, no backward compats, no reexport for \"convenience\".\n- Treat the project as greenfield unless stated otherwise.\n- You are not alone, expect parallel changes in unrelated files by others.\n" }, { "path": "agents/opencode/opencode.json", "content": "{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"agent\": {\n \"general\": {\n \"disable\": true\n },\n \"explore\": {\n \"disable\": true\n },\n \"plan\": {\n \"permission\": {\n \"edit\": {\n \"*\": \"deny\",\n \"*.md\": \"ask\"\n },\n \"skill\": {\n \"*\": \"deny\",\n \"code-review-*\": \"allow\",\n \"brainstorming\": \"allow\",\n \"build-feature\": \"allow\",\n \"*-best-practices\": \"allow\",\n }\n }\n }\n },\n \"permission\": {\n \"*\": \"deny\",\n \"read\": \"allow\",\n \"write\": \"allow\",\n \"bash\": \"allow\",\n \"webfetch\": \"allow\",\n \"websearch\": \"allow\",\n \"lsp\": \"allow\",\n \"list\": \"allow\",\n \"grep\": \"allow\",\n \"glob\": \"allow\",\n \"edit\": \"allow\",\n \"external_directory\": {\n \"*\": \"ask\",\n \"~/Development/personal/*\": \"allow\",\n \"~/Development/work/*\": \"allow\",\n \"~/Repositories/*\": \"allow\",\n \"/tmp/*\": \"allow\",\n },\n \"question\": \"allow\",\n \"codesearch\": \"allow\",\n \"skill\": {\n \"*\": \"allow\",\n \"pdf\": \"deny\",\n \"xlsx\": \"deny\",\n },\n }\n}\n" }, { "path": "agents/pi/extensions/agent-profiles.ts", "content": "/**\n * Agent Profiles Extension\n *\n * Define agent personas in markdown files with frontmatter.\n * Content is appended to system prompt each turn.\n *\n * Location:\n * - ~/.pi/agent/agents/*.md (global)\n * - .pi/agents/*.md (project-local, overrides)\n *\n * Format:\n * ```markdown\n * ---\n * name: my-agent\n * description: What this agent does\n * tools: [read, bash, edit, write] # whitelist (omit for all)\n * disabledTools: [grep] # blacklist (omit for none)\n * ---\n *\n * Your system prompt additions here...\n * ```\n *\n * Usage:\n * - `pi --agent plan` - start with plan agent\n * - `/agent` - show selector\n * - `/agent plan` - switch to plan agent\n * - `/agent default` - reset to default\n */\n\nimport { existsSync, readFileSync, readdirSync } from \"node:fs\";\nimport { homedir } from \"node:os\";\nimport { join, basename, extname } from \"node:path\";\nimport type {\n ExtensionAPI,\n ExtensionContext,\n} from \"@mariozechner/pi-coding-agent\";\nimport { DynamicBorder } from \"@mariozechner/pi-coding-agent\";\nimport {\n Key,\n Container,\n type SelectItem,\n SelectList,\n Text,\n} from \"@mariozechner/pi-tui\";\n\ninterface AgentProfile {\n name: string;\n description: string;\n tools?: string[];\n disabledTools?: string[];\n provider?: string;\n content: string; // appended to system prompt\n}\n\nconst DEFAULT_TOOLS = [\"read\", \"bash\", \"edit\", \"write\", \"grep\", \"find\", \"ls\", \"mcp\", \"ask\"];\n\n// Hardcoded default agent - always available as fallback\nconst DEFAULT_AGENT: AgentProfile = {\n name: \"default\",\n description: \"Default agent with full capabilities\",\n tools: DEFAULT_TOOLS,\n content:\n \"You are pi, a minimal terminal coding agent. Use the tools available to help the user.\",\n};\n\n/**\n * Parse frontmatter from markdown content\n */\nfunction parseFrontmatter(content: string): {\n frontmatter: Record;\n body: string;\n} {\n const match = content.match(/^---\\s*\\n([\\s\\S]*?)\\n---\\s*\\n([\\s\\S]*)$/);\n if (!match) {\n return { frontmatter: {}, body: content };\n }\n\n const yamlText = match[1];\n const body = match[2].trim();\n\n const frontmatter: Record = {};\n for (const line of yamlText.split(\"\\n\")) {\n const colonIdx = line.indexOf(\":\");\n if (colonIdx === -1) continue;\n\n const key = line.slice(0, colonIdx).trim();\n let value: unknown = line.slice(colonIdx + 1).trim();\n\n // Parse arrays: [item1, item2]\n if (\n typeof value === \"string\" &&\n value.startsWith(\"[\") &&\n value.endsWith(\"]\")\n ) {\n value = value\n .slice(1, -1)\n .split(\",\")\n .map((s) => s.trim())\n .filter(Boolean);\n }\n\n frontmatter[key] = value;\n }\n\n return { frontmatter, body };\n}\n\n/**\n * Load agent profiles from directory\n */\nfunction loadAgentsFromDir(dir: string): Map {\n const agents = new Map();\n\n if (!existsSync(dir)) return agents;\n\n const entries = readdirSync(dir, { withFileTypes: true });\n\n for (const entry of entries) {\n if (!entry.isFile()) continue;\n if (extname(entry.name) !== \".md\") continue;\n\n const filepath = join(dir, entry.name);\n try {\n const content = readFileSync(filepath, \"utf-8\");\n const { frontmatter, body } = parseFrontmatter(content);\n\n const name = (frontmatter.name as string) || basename(entry.name, \".md\");\n\n agents.set(name, {\n name,\n description: (frontmatter.description as string) || \"\",\n tools: frontmatter.tools as string[] | undefined,\n disabledTools: frontmatter.disabledTools as string[] | undefined,\n provider: frontmatter.provider as string | undefined,\n content: body,\n });\n } catch {\n // skip invalid files\n }\n }\n\n return agents;\n}\n\n/**\n * Load all agents (global + project, project overrides)\n * Default agent is always available as fallback\n */\nfunction loadAgents(cwd: string): Map {\n const globalDir = join(homedir(), \".pi\", \"agent\", \"agents\");\n const projectDir = join(cwd, \".pi\", \"agents\");\n\n // Start with default agent\n const agents = new Map();\n agents.set(\"default\", DEFAULT_AGENT);\n\n // Load global agents (can override default if explicitly defined)\n const globalAgents = loadAgentsFromDir(globalDir);\n for (const [name, agent] of globalAgents) {\n agents.set(name, agent);\n }\n\n // Load project agents (override global)\n const projectAgents = loadAgentsFromDir(projectDir);\n for (const [name, agent] of projectAgents) {\n agents.set(name, agent);\n }\n\n return agents;\n}\n\n/**\n * Get effective tools list for an agent\n */\nfunction getEffectiveTools(agent: AgentProfile | undefined): string[] {\n if (!agent) return DEFAULT_TOOLS;\n\n // Explicit whitelist\n if (agent.tools) {\n return agent.tools.filter((t) => DEFAULT_TOOLS.includes(t));\n }\n\n // Blacklist mode\n if (agent.disabledTools) {\n return DEFAULT_TOOLS.filter((t) => !agent.disabledTools?.includes(t));\n }\n\n return DEFAULT_TOOLS;\n}\n\nexport default function agentProfilesExtension(pi: ExtensionAPI) {\n let agents = new Map();\n let activeAgent: AgentProfile | undefined;\n let baseSystemPrompt = \"\"; // captured at session start\n\n // Register --agent CLI flag\n pi.registerFlag(\"agent\", {\n description: \"Agent profile to use\",\n type: \"string\",\n });\n\n /**\n * Apply an agent profile\n */\n async function applyAgent(\n name: string,\n agent: AgentProfile | undefined,\n ctx: ExtensionContext,\n ): Promise {\n activeAgent = agent;\n\n // Emit event for other extensions (e.g., starship-prompt)\n pi.events.emit(\"agent-profile:changed\", {\n name: agent?.name ?? \"default\",\n description: agent?.description ?? \"\",\n });\n\n if (!agent) {\n // Reset to default\n pi.setActiveTools(DEFAULT_TOOLS);\n ctx.ui.notify(\"Reset to default agent\", \"info\");\n updateStatus(ctx);\n return;\n }\n\n // Apply tools - this rebuilds the system prompt with correct tool descriptions\n const tools = getEffectiveTools(agent);\n pi.setActiveTools(tools);\n\n ctx.ui.notify(`Agent \"${name}\" activated (${tools.length} tools)`, \"info\");\n updateStatus(ctx);\n }\n\n /**\n * Build description for UI\n */\n function buildDescription(agent: AgentProfile): string {\n const parts: string[] = [];\n\n const tools = getEffectiveTools(agent);\n if (tools.length !== DEFAULT_TOOLS.length) {\n parts.push(`${tools.length} tools`);\n }\n\n if (agent.description) {\n const truncated =\n agent.description.length > 40\n ? `${agent.description.slice(0, 37)}...`\n : agent.description;\n parts.push(truncated);\n }\n\n return parts.join(\" | \") || \"Custom agent profile\";\n }\n\n /**\n * Show agent selector UI\n */\n async function showAgentSelector(ctx: ExtensionContext): Promise {\n const agentList = Array.from(agents.values()).sort((a, b) =>\n a.name.localeCompare(b.name),\n );\n\n if (agentList.length === 0) {\n ctx.ui.notify(\n \"No agent profiles found. Create files in ~/.pi/agent/agents/ or .pi/agents/\",\n \"warning\",\n );\n return;\n }\n\n const items: SelectItem[] = [\n {\n value: \"default\",\n label: \"default\",\n description: \"Reset to default (all tools, no additions)\",\n },\n ...agentList.map((agent) => ({\n value: agent.name,\n label:\n agent.name === activeAgent?.name\n ? `${agent.name} (active)`\n : agent.name,\n description: buildDescription(agent),\n })),\n ];\n\n const result = await ctx.ui.custom(\n (tui, theme, _kb, done) => {\n const container = new Container();\n container.addChild(new DynamicBorder((str) => theme.fg(\"accent\", str)));\n container.addChild(\n new Text(theme.fg(\"accent\", theme.bold(\"Select Agent Profile\"))),\n );\n\n const selectList = new SelectList(items, Math.min(items.length, 12), {\n selectedPrefix: (text) => theme.fg(\"accent\", text),\n selectedText: (text) => theme.fg(\"accent\", text),\n description: (text) => theme.fg(\"muted\", text),\n scrollInfo: (text) => theme.fg(\"dim\", text),\n noMatch: (text) => theme.fg(\"warning\", text),\n });\n\n selectList.onSelect = (item) => done(item.value);\n selectList.onCancel = () => done(null);\n\n const k = (s: string) => theme.bold(theme.fg(\"accent\", s));\n const l = (s: string) => theme.fg(\"dim\", s);\n container.addChild(selectList);\n container.addChild(\n new Text(\n ` ${k(\"↑↓\")}${l(\" select\")} · ${k(\"enter\")}${l(\" submit\")} · ${k(\"esc\")}${l(\" dismiss\")}`,\n ),\n );\n container.addChild(new DynamicBorder((str) => theme.fg(\"accent\", str)));\n\n return {\n render(width: number) {\n return container.render(width);\n },\n invalidate() {\n container.invalidate();\n },\n handleInput(data: string) {\n selectList.handleInput(data);\n tui.requestRender();\n },\n };\n },\n );\n\n if (!result) return;\n\n if (result === \"default\") {\n await applyAgent(\"default\", undefined, ctx);\n } else {\n const agent = agents.get(result);\n if (agent) {\n await applyAgent(result, agent, ctx);\n }\n }\n }\n\n /**\n * Update status in footer\n */\n function updateStatus(ctx: ExtensionContext) {\n if (activeAgent && activeAgent.name !== \"default\") {\n ctx.ui.setStatus(\n \"agent\",\n ctx.ui.theme.fg(\"accent\", `agent:${activeAgent.name}`),\n );\n } else {\n ctx.ui.setStatus(\"agent\", undefined);\n }\n }\n\n /**\n * Get ordered list of agent names for cycling\n */\n function getAgentOrder(): string[] {\n return [\n \"default\",\n ...Array.from(agents.keys())\n .filter((n) => n !== \"default\")\n .sort(),\n ];\n }\n\n /**\n * Cycle to next agent\n */\n async function cycleAgent(ctx: ExtensionContext): Promise {\n const agentNames = getAgentOrder();\n if (agentNames.length <= 1) {\n ctx.ui.notify(\"No custom agents to cycle\", \"warning\");\n return;\n }\n\n const currentName = activeAgent?.name ?? \"default\";\n const currentIndex = agentNames.indexOf(currentName);\n const nextIndex =\n currentIndex === -1 ? 0 : (currentIndex + 1) % agentNames.length;\n const nextName = agentNames[nextIndex];\n\n if (nextName === \"default\") {\n await applyAgent(\"default\", undefined, ctx);\n } else {\n const agent = agents.get(nextName);\n if (agent) {\n await applyAgent(nextName, agent, ctx);\n }\n }\n }\n\n // Register keyboard shortcut to cycle agents\n pi.registerShortcut(Key.ctrl(\";\"), {\n description: \"Cycle to next agent profile\",\n handler: (ctx) => cycleAgent(ctx),\n });\n\n // Inject agent content into system prompt each turn\n // This appends to the base system prompt (which was already rebuilt with correct tools)\n pi.on(\"before_agent_start\", async (event) => {\n if (activeAgent?.content) {\n return {\n systemPrompt: `${event.systemPrompt}\\n\\n${activeAgent.content}`,\n };\n }\n });\n\n // Initialize on session start\n pi.on(\"session_start\", async (_event, ctx) => {\n // Load agents (includes hardcoded default)\n agents = loadAgents(ctx.cwd);\n\n // Set default as initial active agent\n activeAgent = DEFAULT_AGENT;\n\n // Capture base system prompt (for reference, not used directly)\n baseSystemPrompt = ctx.getSystemPrompt();\n\n // Emit initial state immediately so other extensions (e.g., starship-prompt) have valid state\n pi.events.emit(\"agent-profile:changed\", {\n name: DEFAULT_AGENT.name,\n description: DEFAULT_AGENT.description,\n });\n\n // Check CLI flag first\n const agentFlag = pi.getFlag(\"agent\");\n if (typeof agentFlag === \"string\" && agentFlag) {\n if (agentFlag === \"default\") {\n // Already default, just notify\n ctx.ui.notify(\"Using default agent\", \"info\");\n } else {\n const agent = agents.get(agentFlag);\n if (agent) {\n await applyAgent(agentFlag, agent, ctx);\n } else {\n const available = [\"default\", ...Array.from(agents.keys())].join(\n \", \",\n );\n ctx.ui.notify(\n `Unknown agent \"${agentFlag}\". Available: ${available}`,\n \"warning\",\n );\n }\n }\n updateStatus(ctx);\n return;\n }\n\n // Restore from session state\n const entries = ctx.sessionManager.getEntries();\n const agentEntry = entries\n .filter(\n (e: { type: string; customType?: string }) =>\n e.type === \"custom\" && e.customType === \"agent-profile\",\n )\n .pop() as { data?: { name: string } } | undefined;\n\n if (agentEntry?.data?.name && agentEntry.data.name !== \"default\") {\n const agent = agents.get(agentEntry.data.name);\n if (agent) {\n await applyAgent(agentEntry.data.name, agent, ctx);\n }\n }\n\n updateStatus(ctx);\n });\n\n // Persist active agent when it changes\n pi.on(\"agent-profile:changed\", async (event) => {\n pi.appendEntry(\"agent-profile\", { name: event.name });\n });\n\n // Register /agent command\n pi.registerCommand(\"agent\", {\n description: \"Switch agent profile\",\n handler: async (args, ctx) => {\n const name = args?.trim();\n\n if (!name) {\n await showAgentSelector(ctx);\n return;\n }\n\n if (name === \"default\") {\n await applyAgent(\"default\", undefined, ctx);\n return;\n }\n\n const agent = agents.get(name);\n if (!agent) {\n const available = [\"default\", ...Array.from(agents.keys())].join(\", \");\n ctx.ui.notify(\n `Unknown agent \"${name}\". Available: ${available}`,\n \"error\",\n );\n return;\n }\n\n await applyAgent(name, agent, ctx);\n },\n });\n}\n" }, { "path": "agents/pi/extensions/ask.ts", "content": "/**\n * Ask Tool Extension\n *\n * Provides an interactive Q&A tool for the LLM to ask users questions\n * with multiple choice options or free-form text input.\n */\n\nimport type { ExtensionAPI, ToolResult } from \"@mariozechner/pi-coding-agent\";\nimport { Key, matchesKey, truncateToWidth } from \"@mariozechner/pi-tui\";\nimport { Type } from \"@sinclair/typebox\";\n\n// Ask tool option schema\nconst AskOptionSchema = Type.Object({\n label: Type.String({ description: \"Display label for the option\" }),\n description: Type.Optional(\n Type.String({ description: \"Optional description shown below label\" }),\n ),\n});\n\nconst AskQuestionSchema = Type.Object({\n question: Type.String({ description: \"The question to ask the user\" }),\n options: Type.Array(AskOptionSchema, {\n description: \"Options for the user to choose from\",\n }),\n shortTitle: Type.Optional(\n Type.String({\n description: \"Short 1-2 word title for tab display (defaults to number)\",\n }),\n ),\n});\n\n// Single object with everything optional to avoid union issues\nconst AskParams = Type.Object({\n questions: Type.Optional(\n Type.Array(AskQuestionSchema, {\n description: \"A list of questions to ask the user\",\n }),\n ),\n question: Type.Optional(\n Type.String({ description: \"The question to ask the user\" }),\n ),\n options: Type.Optional(\n Type.Array(AskOptionSchema, {\n description: \"Options for the user to choose from\",\n }),\n ),\n});\n\ninterface AskDetails {\n question: string;\n options: string[];\n answer: string | null;\n wasCustom?: boolean;\n}\n\ninterface MultiAskDetails {\n results: AskDetails[];\n}\n\ninterface QuestionState {\n optionIndex: number;\n editMode: boolean;\n customAnswer: string;\n answer: string | null;\n wasCustom: boolean;\n}\n\nexport default function askToolExtension(pi: ExtensionAPI): void {\n pi.registerTool({\n name: \"ask\",\n label: \"Ask\",\n description:\n \"Ask the user one or more questions and let them pick from options or type a custom answer. Use when you need user input to proceed with a decision.\",\n parameters: AskParams,\n\n async execute(_toolCallId, params, _signal, _onUpdate, ctx) {\n const questions: {\n question: string;\n options: { label: string; description?: string }[];\n shortTitle?: string;\n }[] = [];\n\n if (params.questions && params.questions.length > 0) {\n questions.push(...params.questions);\n } else if (params.question && params.options) {\n questions.push({ question: params.question, options: params.options });\n }\n\n if (questions.length === 0) {\n return {\n content: [\n {\n type: \"text\",\n text: \"Error: No questions (or question/options) provided\",\n },\n ],\n };\n }\n\n if (!ctx.hasUI) {\n return {\n content: [\n {\n type: \"text\",\n text: \"Error: UI not available (running in non-interactive mode)\",\n },\n ],\n details: {\n results: questions.map((q) => ({\n question: q.question,\n options: q.options.map((o) => o.label),\n answer: null,\n })),\n } as MultiAskDetails,\n };\n }\n\n // Single question: use simple flow (no tabs, no review)\n if (questions.length === 1) {\n return handleSingleQuestion(ctx, questions[0]);\n }\n\n // Multiple questions: use tabbed UI with review\n return handleMultipleQuestions(ctx, questions);\n },\n });\n}\n\nasync function handleSingleQuestion(\n ctx: ExtensionAPI[\"ctx\"],\n q: {\n question: string;\n options: { label: string; description?: string }[];\n shortTitle?: string;\n },\n): Promise {\n const allOptions = [\n ...q.options,\n { label: \"Type your own answer\", description: \"Write a custom response\" },\n ];\n\n const result = await ctx.ui.custom<{\n answer: string;\n wasCustom: boolean;\n index?: number;\n } | null>((tui, theme, _kb, done) => {\n let optionIndex = 0;\n let editMode = false;\n let customAnswer = \"\";\n let cachedLines: string[] | undefined;\n\n function refresh() {\n cachedLines = undefined;\n tui.requestRender();\n }\n\n function handleInput(data: string) {\n if (editMode) {\n if (matchesKey(data, Key.escape)) {\n editMode = false;\n customAnswer = \"\";\n refresh();\n return;\n }\n if (matchesKey(data, Key.enter)) {\n const trimmed = customAnswer.trim();\n if (trimmed) {\n done({ answer: trimmed, wasCustom: true });\n } else {\n editMode = false;\n customAnswer = \"\";\n refresh();\n }\n return;\n }\n if (matchesKey(data, Key.backspace)) {\n customAnswer = customAnswer.slice(0, -1);\n refresh();\n return;\n }\n if (data.length === 1 && data.charCodeAt(0) >= 32) {\n customAnswer += data;\n refresh();\n }\n return;\n }\n\n if (matchesKey(data, Key.up)) {\n optionIndex = Math.max(0, optionIndex - 1);\n refresh();\n return;\n }\n if (matchesKey(data, Key.down)) {\n optionIndex = Math.min(allOptions.length - 1, optionIndex + 1);\n refresh();\n return;\n }\n if (matchesKey(data, Key.enter)) {\n const selected = allOptions[optionIndex];\n const isLastOption = optionIndex === allOptions.length - 1;\n if (isLastOption) {\n editMode = true;\n refresh();\n } else {\n done({\n answer: selected.label,\n wasCustom: false,\n index: optionIndex + 1,\n });\n }\n return;\n }\n if (matchesKey(data, Key.escape)) {\n done(null);\n }\n }\n\n function render(width: number): string[] {\n if (cachedLines) return cachedLines;\n\n const lines: string[] = [];\n const add = (s: string) => lines.push(truncateToWidth(s, width));\n\n // Top border\n add(theme.fg(\"accent\", \"─\".repeat(width)));\n\n // Question\n add(theme.fg(\"text\", ` ${q.question}`));\n lines.push(\"\");\n\n // Options\n for (let i = 0; i < allOptions.length; i++) {\n const opt = allOptions[i];\n const selected = i === optionIndex;\n const isLast = i === allOptions.length - 1;\n const prefix = selected ? theme.fg(\"accent\", \"> \") : \" \";\n const num = `${i + 1}.`;\n\n if (isLast && editMode) {\n add(prefix + theme.fg(\"accent\", `${num} ${opt.label} ✎`));\n } else if (selected) {\n add(prefix + theme.fg(\"accent\", `${num} ${opt.label}`));\n } else {\n add(` ${theme.fg(\"text\", `${num} ${opt.label}`)}`);\n }\n\n if (opt.description) {\n add(` ${theme.fg(\"muted\", opt.description)}`);\n }\n }\n\n if (editMode) {\n lines.push(\"\");\n add(theme.fg(\"muted\", \" Your answer:\"));\n const inputLine = ` > ${customAnswer}_`;\n add(truncateToWidth(inputLine, width));\n }\n\n // Help text\n lines.push(\"\");\n const k = (s: string) => theme.bold(theme.fg(\"accent\", s));\n const l = (s: string) => theme.fg(\"dim\", s);\n if (editMode) {\n add(` ${k(\"enter\")}${l(\" · submit\")} · ${k(\"esc\")}${l(\" go back\")}`);\n } else {\n add(\n ` ${k(\"↑↓\")}${l(\" select\")} · ${k(\"enter\")}${l(\" submit\")} · ${k(\"esc\")}${l(\" dismiss\")}`,\n );\n }\n\n // Bottom border\n add(theme.fg(\"accent\", \"─\".repeat(width)));\n\n cachedLines = lines;\n return lines;\n }\n\n return {\n render,\n invalidate: () => {\n cachedLines = undefined;\n },\n handleInput,\n };\n });\n\n if (!result) {\n return {\n content: [{ type: \"text\", text: \"User cancelled the question\" }],\n details: {\n results: [\n {\n question: q.question,\n options: q.options.map((o) => o.label),\n answer: null,\n },\n ],\n } as MultiAskDetails,\n };\n }\n\n return {\n content: [\n {\n type: \"text\",\n text: result.wasCustom\n ? `User answered: ${result.answer}`\n : `User selected: ${result.answer}`,\n },\n ],\n details: {\n results: [\n {\n question: q.question,\n options: q.options.map((o) => o.label),\n answer: result.answer,\n wasCustom: result.wasCustom,\n },\n ],\n } as MultiAskDetails,\n };\n}\n\nasync function handleMultipleQuestions(\n ctx: ExtensionAPI[\"ctx\"],\n questions: {\n question: string;\n options: { label: string; description?: string }[];\n shortTitle?: string;\n }[],\n): Promise {\n // Initialize state for each question\n const states: QuestionState[] = questions.map(() => ({\n optionIndex: 0,\n editMode: false,\n customAnswer: \"\",\n answer: null as string | null,\n wasCustom: false,\n }));\n\n let currentQuestion = 0;\n let inReview = false;\n let reviewOptionIndex = 0; // 0 = go back, 1 = submit\n\n const result = await ctx.ui.custom<{\n results: { answer: string; wasCustom: boolean }[];\n } | null>((tui, theme, _kb, done) => {\n let cachedLines: string[] | undefined;\n\n function refresh() {\n cachedLines = undefined;\n tui.requestRender();\n }\n\n function getCurrentOptions() {\n const q = questions[currentQuestion];\n return [\n ...q.options,\n {\n label: \"Type your own answer\",\n description: \"Write a custom response\",\n },\n ];\n }\n\n function handleInput(data: string) {\n if (inReview) {\n handleReviewInput(data);\n return;\n }\n\n const state = states[currentQuestion];\n const allOptions = getCurrentOptions();\n\n if (state.editMode) {\n if (matchesKey(data, Key.escape)) {\n state.editMode = false;\n state.customAnswer = \"\";\n refresh();\n return;\n }\n if (matchesKey(data, Key.enter)) {\n const trimmed = state.customAnswer.trim();\n if (trimmed) {\n state.answer = trimmed;\n state.wasCustom = true;\n state.editMode = false;\n // Auto-advance to next question or review\n if (currentQuestion < questions.length - 1) {\n currentQuestion++;\n } else {\n inReview = true;\n }\n refresh();\n } else {\n state.editMode = false;\n state.customAnswer = \"\";\n refresh();\n }\n return;\n }\n if (matchesKey(data, Key.backspace)) {\n state.customAnswer = state.customAnswer.slice(0, -1);\n refresh();\n return;\n }\n if (data.length === 1 && data.charCodeAt(0) >= 32) {\n state.customAnswer += data;\n refresh();\n }\n return;\n }\n\n // Tab navigation between questions\n if (matchesKey(data, Key.tab)) {\n currentQuestion = (currentQuestion + 1) % questions.length;\n refresh();\n return;\n }\n if (matchesKey(data, Key.shift(Key.tab))) {\n currentQuestion =\n (currentQuestion - 1 + questions.length) % questions.length;\n refresh();\n return;\n }\n\n // Option selection within current question\n if (matchesKey(data, Key.up)) {\n state.optionIndex = Math.max(0, state.optionIndex - 1);\n refresh();\n return;\n }\n if (matchesKey(data, Key.down)) {\n state.optionIndex = Math.min(\n allOptions.length - 1,\n state.optionIndex + 1,\n );\n refresh();\n return;\n }\n if (matchesKey(data, Key.enter)) {\n const selected = allOptions[state.optionIndex];\n const isLastOption = state.optionIndex === allOptions.length - 1;\n if (isLastOption) {\n state.editMode = true;\n refresh();\n } else {\n state.answer = selected.label;\n state.wasCustom = false;\n // Auto-advance to next question or review\n if (currentQuestion < questions.length - 1) {\n currentQuestion++;\n } else {\n inReview = true;\n }\n refresh();\n }\n return;\n }\n if (matchesKey(data, Key.escape)) {\n done(null);\n }\n }\n\n function handleReviewInput(data: string) {\n if (matchesKey(data, Key.left) || matchesKey(data, Key.up)) {\n reviewOptionIndex = 0;\n refresh();\n return;\n }\n if (matchesKey(data, Key.right) || matchesKey(data, Key.down)) {\n reviewOptionIndex = 1;\n refresh();\n return;\n }\n if (matchesKey(data, Key.enter)) {\n if (reviewOptionIndex === 0) {\n // Go back to edit\n inReview = false;\n currentQuestion = 0;\n refresh();\n } else {\n // Submit\n done({\n results: states.map((s) => ({\n answer: s.answer!,\n wasCustom: s.wasCustom,\n })),\n });\n }\n return;\n }\n if (matchesKey(data, Key.escape)) {\n inReview = false;\n refresh();\n }\n }\n\n function render(width: number): string[] {\n if (cachedLines) return cachedLines;\n\n if (inReview) {\n return renderReview(width);\n }\n return renderQuestion(width);\n }\n\n function renderQuestion(width: number): string[] {\n const lines: string[] = [];\n const add = (s: string) => lines.push(truncateToWidth(s, width));\n const state = states[currentQuestion];\n const q = questions[currentQuestion];\n const allOptions = getCurrentOptions();\n\n // Tab bar with short titles (fallback to numbers)\n const tabs = questions.map((q, i) => {\n const isActive = i === currentQuestion;\n const isAnswered = states[i].answer !== null;\n const label = q.shortTitle || `${i + 1}`;\n if (isActive) {\n return theme.fg(\"accent\", theme.bold(label));\n }\n if (isAnswered) {\n return theme.fg(\"muted\", `${label}✓`);\n }\n return theme.fg(\"dim\", label);\n });\n add(tabs.join(\" · \"));\n\n // Top border\n add(theme.fg(\"accent\", \"─\".repeat(width)));\n\n // Question\n add(theme.fg(\"text\", ` ${q.question}`));\n lines.push(\"\");\n\n // Options\n for (let i = 0; i < allOptions.length; i++) {\n const opt = allOptions[i];\n const selected = i === state.optionIndex;\n const isLast = i === allOptions.length - 1;\n const prefix = selected ? theme.fg(\"accent\", \"> \") : \" \";\n const num = `${i + 1}.`;\n const isActive = !isLast && state.answer === opt.label;\n const check = isActive ? ` ${theme.fg(\"accent\", \"✓\")}` : \"\";\n\n if (isLast && state.editMode) {\n add(prefix + theme.fg(\"accent\", `${num} ${opt.label} ✎`));\n } else if (isLast && state.wasCustom && state.answer) {\n add(\n prefix +\n (selected\n ? theme.fg(\"accent\", `${num} ${opt.label}`)\n : theme.fg(\"text\", `${num} ${opt.label}`)) +\n ` ${theme.fg(\"accent\", \"✓\")}`,\n );\n } else if (selected) {\n add(prefix + theme.fg(\"accent\", `${num} ${opt.label}`) + check);\n } else {\n add(` ${theme.fg(\"text\", `${num} ${opt.label}`)}` + check);\n }\n\n if (opt.description) {\n add(` ${theme.fg(\"muted\", opt.description)}`);\n }\n }\n\n if (state.editMode) {\n lines.push(\"\");\n add(theme.fg(\"muted\", \" Your answer:\"));\n const inputLine = ` > ${state.customAnswer}_`;\n add(truncateToWidth(inputLine, width));\n }\n\n // Help text\n lines.push(\"\");\n const k = (s: string) => theme.bold(theme.fg(\"accent\", s));\n const l = (s: string) => theme.fg(\"dim\", s);\n if (state.editMode) {\n add(` ${k(\"enter\")}${l(\" · submit\")} · ${k(\"esc\")}${l(\" go back\")}`);\n } else {\n add(\n ` ${k(\"↑↓\")}${l(\" select\")} · ${k(\"tab\")}${l(\" next\")} · ${k(\"enter\")}${l(\" submit\")} · ${k(\"esc\")}${l(\" dismiss\")}`,\n );\n }\n\n // Bottom border\n add(theme.fg(\"accent\", \"─\".repeat(width)));\n\n cachedLines = lines;\n return lines;\n }\n\n function renderReview(width: number): string[] {\n const lines: string[] = [];\n const add = (s: string) => lines.push(truncateToWidth(s, width));\n\n // Header\n add(theme.fg(\"accent\", theme.bold(\" Review your answers\")));\n add(theme.fg(\"accent\", \"─\".repeat(width)));\n lines.push(\"\");\n\n // Questions and answers\n for (let i = 0; i < questions.length; i++) {\n const q = questions[i];\n const state = states[i];\n const label = q.shortTitle || `Q${i + 1}`;\n add(\n ` ${theme.fg(\"text\", theme.bold(`${label}:`))} ${theme.fg(\"text\", q.question)}`,\n );\n if (state.answer) {\n const prefix = state.wasCustom ? \"✎\" : \"✓\";\n add(\n ` ${theme.fg(\"accent\", prefix)} ${theme.fg(\"text\", state.answer)}`,\n );\n } else {\n add(` ${theme.fg(\"dim\", \"○ No answer\")}`);\n }\n lines.push(\"\");\n }\n\n // Action buttons\n const goBackLabel = \"← Go back to edit\";\n const submitLabel = \"✔️Submit answers\";\n const goBack =\n reviewOptionIndex === 0\n ? theme.fg(\"accent\", theme.bold(`> ${goBackLabel}`))\n : theme.fg(\"dim\", ` ${goBackLabel}`);\n const submit =\n reviewOptionIndex === 1\n ? theme.fg(\"accent\", theme.bold(`> ${submitLabel}`))\n : theme.fg(\"dim\", ` ${submitLabel}`);\n add(` ${goBack}`);\n add(` ${submit}`);\n\n // Help text\n lines.push(\"\");\n const k = (s: string) => theme.bold(theme.fg(\"accent\", s));\n const l = (s: string) => theme.fg(\"dim\", s);\n add(\n ` ${k(\"↑↓\")}${l(\" select\")} · ${k(\"enter\")}${l(\" confirm\")} · ${k(\"esc\")}${l(\" go back\")}`,\n );\n\n // Bottom border\n add(theme.fg(\"accent\", \"─\".repeat(width)));\n\n cachedLines = lines;\n return lines;\n }\n\n return {\n render,\n invalidate: () => {\n cachedLines = undefined;\n },\n handleInput,\n };\n });\n\n if (!result) {\n return {\n content: [{ type: \"text\", text: \"User cancelled the questions\" }],\n details: {\n results: questions.map((q, i) => ({\n question: q.question,\n options: q.options.map((o) => o.label),\n answer: states[i].answer,\n })),\n } as MultiAskDetails,\n };\n }\n\n // Format output\n const outputText = questions\n .map((q, i) => {\n const r = result.results[i];\n const prefix = r.wasCustom ? \"Answered\" : \"Selected\";\n const label = q.shortTitle || `Question ${i + 1}`;\n return `${label}: ${q.question}\\n${prefix}: ${r.answer}`;\n })\n .join(\"\\n\\n\");\n\n return {\n content: [{ type: \"text\", text: outputText }],\n details: {\n results: questions.map((q, i) => ({\n question: q.question,\n options: q.options.map((o) => o.label),\n answer: result.results[i].answer,\n wasCustom: result.results[i].wasCustom,\n })),\n } as MultiAskDetails,\n };\n}\n" }, { "path": "agents/pi/extensions/composed-editor/index.ts", "content": "/**\n * Composed Editor - Combines starship-prompt + pi-ckers\n *\n * This is your local extension that composes multiple editor features.\n * Place this in ~/.pi/extensions/composed-editor/\n */\n\nimport { type ExtensionAPI, CustomEditor } from \"@mariozechner/pi-coding-agent\";\nimport type { Picker } from \"@elianiva/pi-ckers\";\nimport { createStarshipWidget, setupStarshipEvents } from \"@elianiva/pi-starship\";\nimport { withPickers } from \"@elianiva/pi-ckers\";\nimport { filePicker, dirPicker } from \"@elianiva/pi-ckers/builtin/fff\";\nimport { grepPicker } from \"@elianiva/pi-ckers/builtin/grep\";\n\n// Compose: StarshipEditor + all builtin pickers\nconst pickers: Picker[] = [\n filePicker(),\n dirPicker(),\n grepPicker(),\n];\n\nconst ComposedEditor = withPickers(CustomEditor, pickers);\n\nexport default function composedEditorExtension(pi: ExtensionAPI) {\n pi.on(\"session_start\", async (_event, ctx) => {\n // if (!ctx.hasUI) return;\n //\n // // Set composed editor - pass ctx as 5th argument for picker initialization\n // ctx.ui.setEditorComponent(\n // (tui, theme, keybindings) => new ComposedEditor(tui, theme, keybindings, undefined, ctx),\n // );\n\n // Clear footer\n // ctx.ui.setFooter(() => ({ invalidate() {}, render() { return []; } }));\n\n // // Set up starship widget\n // createStarshipWidget(pi, ctx);\n });\n\n // Set up starship event handlers\n // setupStarshipEvents(pi);\n}\n" }, { "path": "agents/pi/extensions/composed-editor/package.json", "content": "{\n \"name\": \"composed-editor\",\n \"version\": \"1.0.0\",\n \"private\": true,\n \"description\": \"Composed editor with starship-prompt + pi-ckers\",\n \"dependencies\": {\n \"@elianiva/pi-ckers\": \"link:@elianiva/pi-ckers\",\n \"@elianiva/pi-starship\": \"link:@elianiva/pi-starship\",\n \"@mariozechner/pi-coding-agent\": \"*\"\n }\n}\n" }, { "path": "agents/pi/extensions/custom-formatting.ts", "content": "import { Theme } from \"@mariozechner/pi-coding-agent\";\nimport type { ExtensionAPI } from \"@mariozechner/pi-coding-agent\";\n\n/**\n * Extension that overrides markdown bold and italic formatting to use colors instead.\n *\n * It monkey-patches the Theme prototype so it works across all themes\n * and doesn't require polling.\n */\nexport default function (pi: ExtensionAPI) {\n const originalBold = Theme.prototype.bold;\n const originalItalic = Theme.prototype.italic;\n\n // Override bold to use 'warning' color (usually yellow/orange)\n Theme.prototype.bold = function(this: Theme, text: string) {\n return originalBold(this.fg(\"mdHeading\", text));\n };\n\n // Override italic to use 'accent' color (usually teal/cyan)\n Theme.prototype.italic = function(this: Theme, text: string) {\n return originalItalic(this.fg(\"accent\", text));\n };\n\n // Restore originals on shutdown\n pi.on(\"session_shutdown\", () => {\n Theme.prototype.bold = originalBold;\n Theme.prototype.italic = originalItalic;\n });\n}\n" }, { "path": "agents/pi/extensions/exit-command.ts", "content": "import type { ExtensionAPI } from \"@mariozechner/pi-coding-agent\";\n\nexport default function (pi: ExtensionAPI) {\n pi.on(\"input\", async (event, ctx) => {\n // Only handle plain \"exit\" without arguments\n if (event.text.trim() === \"exit\") {\n ctx.shutdown();\n return { action: \"handled\" };\n }\n\n return { action: \"continue\" };\n });\n}\n" }, { "path": "agents/pi/extensions/handoff.ts", "content": "/**\n * Handoff extension - transfer context to a new focused session\n *\n * Instead of compacting (which is lossy), handoff extracts what matters\n * for your next task and creates a new session with a generated prompt.\n *\n * Usage:\n * /handoff now implement this for teams as well\n * /handoff execute phase one of the plan\n * /handoff check other places that need this fix\n *\n * The generated prompt appears as a draft in the editor for review/editing.\n */\n\nimport { complete, type Message } from \"@mariozechner/pi-ai\";\nimport type { ExtensionAPI, SessionEntry } from \"@mariozechner/pi-coding-agent\";\nimport { BorderedLoader, convertToLlm, serializeConversation } from \"@mariozechner/pi-coding-agent\";\n\nconst SYSTEM_PROMPT = `You are a context transfer assistant. Given a conversation history and the user's goal for a new thread, generate a focused prompt that:\n\n1. Summarizes relevant context from the conversation (decisions made, approaches taken, key findings)\n2. Lists any relevant files that were discussed or modified\n3. Clearly states the next task based on the user's goal\n4. Is self-contained - the new thread should be able to proceed without the old conversation\n\nFormat your response as a prompt the user can send to start the new thread. Be concise but include all necessary context. Do not include any preamble like \"Here's the prompt\" - just output the prompt itself.\n\nExample output format:\n## Context\nWe've been working on X. Key decisions:\n- Decision 1\n- Decision 2\n\nFiles involved:\n- path/to/file1.ts\n- path/to/file2.ts\n\n## Task\n[Clear description of what to do next based on user's goal]`;\n\nexport default function (pi: ExtensionAPI) {\n\tpi.registerCommand(\"handoff\", {\n\t\tdescription: \"Transfer context to a new focused session\",\n\t\thandler: async (args, ctx) => {\n\t\t\tif (!ctx.hasUI) {\n\t\t\t\tctx.ui.notify(\"handoff requires interactive mode\", \"error\");\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tif (!ctx.model) {\n\t\t\t\tctx.ui.notify(\"No model selected\", \"error\");\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tconst goal = args.trim();\n\t\t\tif (!goal) {\n\t\t\t\tctx.ui.notify(\"Usage: /handoff \", \"error\");\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// Gather conversation context from current branch\n\t\t\tconst branch = ctx.sessionManager.getBranch();\n\t\t\tconst messages = branch\n\t\t\t\t.filter((entry): entry is SessionEntry & { type: \"message\" } => entry.type === \"message\")\n\t\t\t\t.map((entry) => entry.message);\n\n\t\t\tif (messages.length === 0) {\n\t\t\t\tctx.ui.notify(\"No conversation to hand off\", \"error\");\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// Convert to LLM format and serialize\n\t\t\tconst llmMessages = convertToLlm(messages);\n\t\t\tconst conversationText = serializeConversation(llmMessages);\n\t\t\tconst currentSessionFile = ctx.sessionManager.getSessionFile();\n\n\t\t\t// Generate the handoff prompt with loader UI\n\t\t\tconst result = await ctx.ui.custom((tui, theme, _kb, done) => {\n\t\t\t\tconst loader = new BorderedLoader(tui, theme, `Generating handoff prompt...`);\n\t\t\t\tloader.onAbort = () => done(null);\n\n\t\t\t\tconst doGenerate = async () => {\n\t\t\t\t\tconst apiKey = await ctx.modelRegistry.getApiKey(ctx.model!);\n\n\t\t\t\t\tconst userMessage: Message = {\n\t\t\t\t\t\trole: \"user\",\n\t\t\t\t\t\tcontent: [\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\ttype: \"text\",\n\t\t\t\t\t\t\t\ttext: `## Conversation History\\n\\n${conversationText}\\n\\n## User's Goal for New Thread\\n\\n${goal}`,\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t],\n\t\t\t\t\t\ttimestamp: Date.now(),\n\t\t\t\t\t};\n\n\t\t\t\t\tconst response = await complete(\n\t\t\t\t\t\tctx.model!,\n\t\t\t\t\t\t{ systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },\n\t\t\t\t\t\t{ apiKey, signal: loader.signal },\n\t\t\t\t\t);\n\n\t\t\t\t\tif (response.stopReason === \"aborted\") {\n\t\t\t\t\t\treturn null;\n\t\t\t\t\t}\n\n\t\t\t\t\treturn response.content\n\t\t\t\t\t\t.filter((c): c is { type: \"text\"; text: string } => c.type === \"text\")\n\t\t\t\t\t\t.map((c) => c.text)\n\t\t\t\t\t\t.join(\"\\n\");\n\t\t\t\t};\n\n\t\t\t\tdoGenerate()\n\t\t\t\t\t.then(done)\n\t\t\t\t\t.catch((err) => {\n\t\t\t\t\t\tconsole.error(\"Handoff generation failed:\", err);\n\t\t\t\t\t\tdone(null);\n\t\t\t\t\t});\n\n\t\t\t\treturn loader;\n\t\t\t});\n\n\t\t\tif (result === null) {\n\t\t\t\tctx.ui.notify(\"Cancelled\", \"info\");\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// Let user edit the generated prompt\n\t\t\tconst editedPrompt = await ctx.ui.editor(\"Edit handoff prompt\", result);\n\n\t\t\tif (editedPrompt === undefined) {\n\t\t\t\tctx.ui.notify(\"Cancelled\", \"info\");\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// Create new session with parent tracking\n\t\t\tconst newSessionResult = await ctx.newSession({\n\t\t\t\tparentSession: currentSessionFile,\n\t\t\t});\n\n\t\t\tif (newSessionResult.cancelled) {\n\t\t\t\tctx.ui.notify(\"New session cancelled\", \"info\");\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// Set the edited prompt in the main editor for submission\n\t\t\tctx.ui.setEditorText(editedPrompt);\n\t\t\tctx.ui.notify(\"Handoff ready. Submit when ready.\", \"info\");\n\t\t},\n\t});\n}\n" }, { "path": "agents/pi/extensions/lsp/index.ts", "content": "/**\n * LSP Diagnostics Extension\n *\n * Warms up LSP servers on file read, provides diagnostics on write/edit operations.\n * Pattern based on opencode's implementation.\n */\n\nimport type {\n ExtensionAPI,\n ToolResultEvent,\n ExtensionContext,\n} from \"@mariozechner/pi-coding-agent\";\nimport { spawn, type ChildProcess } from \"node:child_process\";\nimport { readFileSync } from \"node:fs\";\nimport { resolve, extname } from \"node:path\";\nimport { pathToFileURL, fileURLToPath } from \"node:url\";\nimport {\n createMessageConnection,\n StreamMessageReader,\n StreamMessageWriter,\n type MessageConnection,\n} from \"vscode-jsonrpc/node\";\nimport type { Diagnostic as VSCodeDiagnostic } from \"vscode-languageserver-protocol\";\nimport { LSP_SERVERS, LANGUAGE_MAP, type LspHandle, type LspServerInfo } from \"./lsp-config.js\";\n\nconst DIAGNOSTICS_TIMEOUT_MS = 5000;\nconst DIAGNOSTICS_DEBOUNCE_MS = 150;\nconst LSP_CONNECTION_TIMEOUT_MS = 5000;\n\ntype Diagnostic = VSCodeDiagnostic;\n\ninterface LspConnection {\n connection: MessageConnection;\n process: ChildProcess;\n rootDir: string;\n serverName: string;\n languages: string[];\n startedAt: number;\n lastActivity: number;\n diagnostics: Map;\n openedFiles: Map;\n initialized: boolean;\n}\n\ninterface LspStatus {\n name: string;\n pid: number | undefined;\n rootDir: string;\n languages: string[];\n uptime: number;\n lastActivity: number;\n filesTracked: number;\n initialized: boolean;\n}\n\nclass LspConnectionManager {\n private connections = new Map();\n private diagnosticCallbacks = new Map void>>();\n\n async getOrCreateConnections(\n filePath: string,\n cwd: string,\n ctx: ExtensionContext,\n ): Promise {\n const ext = extname(filePath);\n const languageId = LANGUAGE_MAP[ext];\n if (!languageId) return [];\n\n // Find all matching servers\n const matchingServers = LSP_SERVERS.filter((server) => server.extensions.includes(ext));\n\n const connections: LspConnection[] = [];\n\n for (const server of matchingServers) {\n const rootDir = await server.root(filePath, cwd);\n if (!rootDir) continue; // Server doesn't apply to this project\n\n const connectionKey = `${server.id}:${rootDir}`;\n if (this.connections.has(connectionKey)) {\n const conn = this.connections.get(connectionKey)!;\n conn.lastActivity = Date.now();\n connections.push(conn);\n continue;\n }\n\n try {\n const handle = await server.spawn(rootDir, cwd);\n if (!handle) {\n ctx.ui.notify(`Could not start ${server.id} LSP server`, \"error\");\n continue;\n }\n const conn = await this.createConnection(\n connectionKey,\n server.id,\n handle,\n rootDir,\n server.extensions,\n ctx,\n AbortSignal.timeout(LSP_CONNECTION_TIMEOUT_MS),\n );\n this.connections.set(connectionKey, conn);\n connections.push(conn);\n } catch (e: any) {\n if (e.name === \"TimeoutError\") {\n ctx.ui.notify(`${server.id} LSP connection timed out, skipping`, \"warning\");\n } else {\n ctx.ui.notify(`Failed to start ${server.id} LSP: ${e}`, \"error\");\n }\n }\n }\n\n return connections;\n }\n\n private async createConnection(\n key: string,\n name: string,\n handle: LspHandle,\n rootDir: string,\n languages: string[],\n ctx: ExtensionContext,\n signal: AbortSignal,\n ): Promise {\n ctx.ui.notify(`Starting ${name} LSP...`, \"info\");\n\n const connection = createMessageConnection(\n new StreamMessageReader(handle.process.stdout),\n new StreamMessageWriter(handle.process.stdin),\n );\n\n const conn: LspConnection = {\n connection,\n process: handle.process,\n rootDir,\n serverName: name,\n languages: [...languages],\n startedAt: Date.now(),\n lastActivity: Date.now(),\n diagnostics: new Map(),\n openedFiles: new Map(),\n initialized: false,\n };\n\n // Handle diagnostics\n connection.onNotification(\"textDocument/publishDiagnostics\", (params: any) => {\n const filePath = this.normalizePath(fileURLToPath(params.uri));\n conn.diagnostics.set(filePath, params.diagnostics);\n\n // Notify waiters\n const callbacks = this.diagnosticCallbacks.get(filePath);\n if (callbacks) {\n for (const cb of callbacks) cb();\n }\n });\n\n // Handle window/workDoneProgress/create\n connection.onRequest(\"window/workDoneProgress/create\", () => null);\n\n // Handle workspace/configuration\n connection.onRequest(\"workspace/configuration\", async () => [handle.initialization ?? {}]);\n\n // Handle client/registerCapability\n connection.onRequest(\"client/registerCapability\", async () => {});\n\n // Handle client/unregisterCapability\n connection.onRequest(\"client/unregisterCapability\", async () => {});\n\n // Handle workspace/workspaceFolders\n connection.onRequest(\"workspace/workspaceFolders\", async () => [\n {\n name: \"workspace\",\n uri: pathToFileURL(rootDir).href,\n },\n ]);\n\n connection.listen();\n\n // Initialize with timeout using AbortSignal\n try {\n await this.initializeConnection(connection, handle, rootDir, signal);\n } catch (e: any) {\n if (e.name === \"TimeoutError\") {\n ctx.ui.notify(`${name} LSP connection timed out, continuing anyway`, \"warning\");\n } else {\n throw e;\n }\n }\n\n conn.initialized = true;\n\n // Handle stderr\n handle.process.stderr?.on(\"data\", (data: Buffer) => {\n const msg = data.toString().trim();\n if (msg) console.error(`[LSP:${name}]`, msg.slice(0, 200));\n });\n\n // Handle process exit\n handle.process.on(\"exit\", (code) => {\n if (code && code !== 0) {\n ctx.ui.notify(`${name} LSP exited with code ${code}`, \"error\");\n }\n this.connections.delete(key);\n });\n\n ctx.ui.notify(`${name} LSP ready`, \"success\");\n return conn;\n }\n\n private async initializeConnection(\n connection: MessageConnection,\n handle: LspHandle,\n rootDir: string,\n signal: AbortSignal,\n ): Promise {\n await connection.sendRequest(\"initialize\", {\n rootUri: pathToFileURL(rootDir).href,\n processId: handle.process.pid,\n workspaceFolders: [\n {\n name: \"workspace\",\n uri: pathToFileURL(rootDir).href,\n },\n ],\n initializationOptions: handle.initialization ?? {},\n capabilities: {\n window: {\n workDoneProgress: true,\n },\n workspace: {\n configuration: true,\n didChangeWatchedFiles: {\n dynamicRegistration: true,\n },\n },\n textDocument: {\n synchronization: {\n didOpen: true,\n didChange: true,\n },\n publishDiagnostics: {\n versionSupport: true,\n },\n },\n },\n });\n\n await connection.sendNotification(\"initialized\", {});\n if (handle.initialization) {\n await connection.sendNotification(\"workspace/didChangeConfiguration\", {\n settings: handle.initialization,\n });\n }\n }\n\n /**\n * Touch file with diagnostic subscription BEFORE sending didOpen\n * This is the key fix from opencode to avoid race conditions\n */\n async touchFile(\n conn: LspConnection,\n filePath: string,\n content: string,\n languageId: string,\n waitForDiagnostics: boolean = false,\n ): Promise {\n const normalizedPath = this.normalizePath(filePath);\n const uri = pathToFileURL(normalizedPath).href;\n const existingVersion = conn.openedFiles.get(normalizedPath);\n\n // Set up diagnostic listener BEFORE sending notification (opencode pattern)\n let diagnosticsPromise: Promise | undefined;\n let debounceTimer: ReturnType | undefined;\n let unsubscribe: (() => void) | undefined;\n\n if (waitForDiagnostics) {\n diagnosticsPromise = new Promise((resolve) => {\n let resolved = false;\n\n const tryResolve = () => {\n if (resolved) return;\n if (debounceTimer) clearTimeout(debounceTimer);\n debounceTimer = setTimeout(() => {\n resolved = true;\n unsubscribe?.();\n resolve(conn.diagnostics.get(normalizedPath) ?? []);\n }, DIAGNOSTICS_DEBOUNCE_MS);\n };\n\n if (!this.diagnosticCallbacks.has(normalizedPath)) {\n this.diagnosticCallbacks.set(normalizedPath, new Set());\n }\n const callbacks = this.diagnosticCallbacks.get(normalizedPath)!;\n callbacks.add(tryResolve);\n unsubscribe = () => callbacks.delete(tryResolve);\n\n // Timeout fallback\n setTimeout(() => {\n if (!resolved) {\n resolved = true;\n unsubscribe?.();\n resolve(conn.diagnostics.get(normalizedPath) ?? []);\n }\n }, DIAGNOSTICS_TIMEOUT_MS);\n });\n }\n\n // Now send the notification\n if (existingVersion !== undefined) {\n conn.diagnostics.delete(normalizedPath);\n const nextVersion = existingVersion + 1;\n conn.openedFiles.set(normalizedPath, nextVersion);\n\n await conn.connection.sendNotification(\"workspace/didChangeWatchedFiles\", {\n changes: [{ uri, type: 2 }], // Changed\n });\n\n await conn.connection.sendNotification(\"textDocument/didChange\", {\n textDocument: { uri, version: nextVersion },\n contentChanges: [{ text: content }],\n });\n } else {\n conn.openedFiles.set(normalizedPath, 0);\n conn.diagnostics.delete(normalizedPath);\n\n await conn.connection.sendNotification(\"workspace/didChangeWatchedFiles\", {\n changes: [{ uri, type: 1 }], // Created\n });\n\n await conn.connection.sendNotification(\"textDocument/didOpen\", {\n textDocument: { uri, languageId, version: 0, text: content },\n });\n }\n\n if (diagnosticsPromise) {\n return diagnosticsPromise;\n }\n return [];\n }\n\n getDiagnostics(conn: LspConnection, filePath: string): Diagnostic[] {\n const normalizedPath = this.normalizePath(filePath);\n return conn.diagnostics.get(normalizedPath) ?? [];\n }\n\n getAllDiagnostics(filePath: string): { conn: LspConnection; diagnostics: Diagnostic[] }[] {\n const normalizedPath = this.normalizePath(filePath);\n const results: { conn: LspConnection; diagnostics: Diagnostic[] }[] = [];\n for (const conn of this.connections.values()) {\n const diags = conn.diagnostics.get(normalizedPath);\n if (diags && diags.length > 0) {\n results.push({ conn, diagnostics: diags });\n }\n }\n return results;\n }\n\n async shutdown(conn: LspConnection): Promise {\n try {\n await conn.connection.sendRequest(\"shutdown\", undefined);\n await conn.connection.sendNotification(\"exit\", {});\n conn.connection.end();\n conn.connection.dispose();\n } catch {\n // Ignore shutdown errors\n }\n conn.process.kill();\n }\n\n async shutdownAll(): Promise {\n const promises = Array.from(this.connections.values()).map((conn) => this.shutdown(conn));\n await Promise.all(promises);\n this.connections.clear();\n }\n\n killConnection(key: string): boolean {\n const conn = this.connections.get(key);\n if (!conn) return false;\n\n conn.process.kill(\"SIGTERM\");\n setTimeout(() => {\n if (!conn.process.killed) {\n conn.process.kill(\"SIGKILL\");\n }\n }, 1000);\n\n this.connections.delete(key);\n return true;\n }\n\n getStatus(): LspStatus[] {\n return Array.from(this.connections.entries()).map(([key, conn]) => ({\n name: conn.serverName,\n pid: conn.process.pid,\n rootDir: conn.rootDir,\n languages: conn.languages,\n uptime: Date.now() - conn.startedAt,\n lastActivity: Date.now() - conn.lastActivity,\n filesTracked: conn.openedFiles.size,\n initialized: conn.initialized,\n }));\n }\n\n private normalizePath(filePath: string): string {\n return resolve(filePath);\n }\n}\n\n// Helper Functions\n\nfunction extractFileFromEvent(event: ToolResultEvent): { path: string; isWrite: boolean } | null {\n if (!event.isError && (event.toolName === \"write\" || event.toolName === \"edit\")) {\n return { path: event.input.path as string, isWrite: true };\n }\n if (!event.isError && event.toolName === \"read\") {\n return { path: event.input.path as string, isWrite: false };\n }\n return null;\n}\n\nfunction formatDiagnostics(diagnostics: Diagnostic[]): string {\n const severityLabels = [\"\", \"ERROR\", \"WARNING\", \"INFO\", \"HINT\"];\n\n return diagnostics\n .map((d) => {\n const line = (d.range?.start?.line ?? 0) + 1;\n const col = (d.range?.start?.character ?? 0) + 1;\n const severity = severityLabels[d.severity ?? 0] || \"UNKNOWN\";\n const code = d.code ? `[${d.code}]` : \"\";\n // const source = d.source ? `${d.source}` : \"\";\n return `${severity} [${line}:${col}] ${d.message}`;\n })\n .join(\"\\n\");\n}\n\nfunction formatDuration(ms: number): string {\n if (ms < 1000) return `${ms}ms`;\n if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;\n return `${(ms / 60000).toFixed(1)}m`;\n}\n\nexport default function (pi: ExtensionAPI) {\n const manager = new LspConnectionManager();\n\n // Warm up LSP on read, full diagnostics on write/edit\n pi.on(\"tool_result\", async (event: ToolResultEvent, ctx: ExtensionContext) => {\n const fileInfo = extractFileFromEvent(event);\n if (!fileInfo) return;\n\n const { path: filePath, isWrite } = fileInfo;\n const absPath = resolve(ctx.cwd, filePath);\n\n const conns = await manager.getOrCreateConnections(filePath, ctx.cwd, ctx);\n if (conns.length === 0) return;\n\n let content: string;\n try {\n content = readFileSync(absPath, \"utf-8\");\n } catch {\n return;\n }\n\n const ext = extname(filePath);\n const languageId = LANGUAGE_MAP[ext];\n if (!languageId) return;\n\n // For read operations: warm up and fetch existing diagnostics if available\n if (!isWrite) {\n await Promise.all(\n conns.map((conn) => manager.touchFile(conn, absPath, content, languageId, false)),\n );\n const allDiags = manager.getAllDiagnostics(absPath);\n // if (allDiags.length > 0) {\n // const combined = allDiags.flatMap((d) => d.diagnostics);\n // const formatted = formatDiagnostics(combined);\n // pi.sendUserMessage(`Current diagnostics for \\`${filePath}\\`:\\n${formatted}`, {\n // deliverAs: \"steer\",\n // });\n // }\n return;\n }\n // For write operations: use opencode pattern - subscribe BEFORE sending\n const diagnostics = (\n await Promise.all(\n conns.map((conn) => manager.touchFile(conn, absPath, content, languageId, true)),\n )\n ).flat();\n\n // Show results\n if (diagnostics.length > 0) {\n const formatted = formatDiagnostics(diagnostics);\n pi.sendUserMessage(`Diagnostics for \\`${filePath}\\`:\\n${formatted}`, {\n deliverAs: \"steer\",\n });\n } else {\n ctx.ui.notify(`✓ ${filePath}: clean`, \"success\");\n }\n });\n\n // Cleanup on shutdown\n pi.on(\"session_shutdown\", async () => {\n await manager.shutdownAll();\n });\n\n // /lsp command - dashboard\n pi.registerCommand(\"lsp\", {\n description:\n \"LSP status dashboard - show running servers, available LSPs, and manage processes\",\n getArgumentCompletions: (prefix: string) => {\n const actions = [\"status\", \"available\", \"kill\", \"killall\"];\n const filtered = actions.filter((a) => a.startsWith(prefix));\n return filtered.length > 0 ? filtered.map((a) => ({ value: a, label: a })) : null;\n },\n handler: async (args: string, ctx) => {\n const parts = args.trim().split(/\\s+/);\n const action = parts[0] || \"status\";\n const serverKey = parts[1];\n\n switch (action) {\n case \"status\": {\n const status = manager.getStatus();\n if (status.length === 0) {\n ctx.ui.notify(\"No LSP servers currently running\", \"info\");\n return;\n }\n\n const lines = [\n \"📊 LSP Server Status\",\n \"\",\n ...status.map((s) => {\n const uptime = formatDuration(s.uptime);\n const statusStr = s.initialized ? \"🟢 ready\" : \"🟡 initializing\";\n return ` ${s.name}\\n PID: ${s.pid} | Status: ${statusStr}\\n Root: ${s.rootDir}\\n Languages: ${s.languages.join(\", \")}\\n Uptime: ${uptime} | Files: ${s.filesTracked}`;\n }),\n \"\",\n \"Use `/lsp kill ` to kill a specific server\",\n \"Use `/lsp killall` to kill all servers\",\n ];\n\n ctx.ui.notify(lines.join(\"\\n\"), \"info\");\n break;\n }\n\n case \"available\": {\n const lines = [\n \"🔧 Available LSP Servers\",\n \"\",\n \"Configured servers:\",\n ...LSP_SERVERS.map((s) => ` ${s.id} - ${s.extensions.join(\", \")}`),\n ];\n\n ctx.ui.notify(lines.join(\"\\n\"), \"info\");\n break;\n }\n\n case \"kill\": {\n if (!serverKey) {\n const status = manager.getStatus();\n if (status.length === 0) {\n ctx.ui.notify(\"No servers running\", \"info\");\n return;\n }\n\n const keys = status.map((s) => `${s.name}:${s.rootDir}`);\n ctx.ui.notify(\"Usage: /lsp kill \\n\\nAvailable servers:\", \"error\");\n ctx.ui.notify(keys.join(\"\\n\"), \"info\");\n return;\n }\n\n const killed = manager.killConnection(serverKey);\n if (killed) {\n ctx.ui.notify(`Killed LSP server: ${serverKey}`, \"success\");\n } else {\n ctx.ui.notify(`Server not found: ${serverKey}`, \"error\");\n }\n break;\n }\n\n case \"killall\": {\n const status = manager.getStatus();\n await manager.shutdownAll();\n ctx.ui.notify(\n `Killed ${status.length} LSP server${status.length > 1 ? \"s\" : \"\"}`,\n \"success\",\n );\n break;\n }\n }\n },\n });\n}\n" }, { "path": "agents/pi/extensions/lsp/lsp-config.ts", "content": "/**\n * LSP Server Configurations\n *\n * Each server defines:\n * - id: Unique identifier\n * - extensions: File extensions this server handles\n * - root: Function to find project root directory\n * - spawn: Function to start the LSP server process\n */\n\nimport { spawn, type ChildProcessWithoutNullStreams } from \"node:child_process\";\nimport { access, constants } from \"node:fs/promises\";\nimport { resolve, dirname } from \"node:path\";\nimport { homedir } from \"node:os\";\n\n// Mason bin path (Neovim plugin manager)\nconst MASON_BIN_PATH = resolve(homedir(), \".local/share/nvim/mason/bin\");\n\nexport interface LspHandle {\n process: ChildProcessWithoutNullStreams;\n initialization?: Record;\n}\n\nexport type RootFunction = (file: string, cwd: string) => Promise;\n\nexport interface LspServerInfo {\n id: string;\n extensions: string[];\n root: RootFunction;\n spawn(root: string, cwd: string): Promise;\n}\n\n// Language ID mapping for LSP\nexport const LANGUAGE_MAP: Record = {\n \".ts\": \"typescript\",\n \".tsx\": \"typescriptreact\",\n \".js\": \"javascript\",\n \".jsx\": \"javascriptreact\",\n \".mjs\": \"javascript\",\n \".cjs\": \"javascript\",\n \".mts\": \"typescript\",\n \".cts\": \"typescript\",\n \".lua\": \"lua\",\n \".py\": \"python\",\n \".pyi\": \"python\",\n \".rs\": \"rust\",\n \".php\": \"php\",\n \".svelte\": \"svelte\",\n \".astro\": \"astro\",\n \".vue\": \"vue\",\n \".css\": \"css\",\n \".scss\": \"scss\",\n \".less\": \"less\",\n \".html\": \"html\",\n \".json\": \"json\",\n \".jsonc\": \"json\",\n \".yaml\": \"yaml\",\n \".yml\": \"yaml\",\n \".md\": \"markdown\",\n \".typ\": \"typst\",\n \".typc\": \"typst\",\n \".go\": \"go\",\n \".zig\": \"zig\",\n \".zon\": \"zig\",\n \".c\": \"c\",\n \".cpp\": \"cpp\",\n \".cc\": \"cpp\",\n \".cxx\": \"cpp\",\n \".c++\": \"cpp\",\n \".h\": \"c\",\n \".hpp\": \"cpp\",\n \".hh\": \"cpp\",\n \".hxx\": \"cpp\",\n \".h++\": \"cpp\",\n \".ex\": \"elixir\",\n \".exs\": \"elixir\",\n \".cs\": \"csharp\",\n \".fs\": \"fsharp\",\n \".fsi\": \"fsharp\",\n \".fsx\": \"fsharp\",\n \".fsscript\": \"fsharp\",\n \".swift\": \"swift\",\n \".kt\": \"kotlin\",\n \".kts\": \"kotlin\",\n \".java\": \"java\",\n \".rb\": \"ruby\",\n \".rake\": \"ruby\",\n \".dart\": \"dart\",\n \".ml\": \"ocaml\",\n \".mli\": \"ocaml\",\n \".sh\": \"shellscript\",\n \".bash\": \"shellscript\",\n \".zsh\": \"shellscript\",\n \".ksh\": \"shellscript\",\n \".nix\": \"nix\",\n \".gleam\": \"gleam\",\n \".clj\": \"clojure\",\n \".cljs\": \"clojure\",\n \".cljc\": \"clojure\",\n \".edn\": \"clojure\",\n \".hs\": \"haskell\",\n \".lhs\": \"haskell\",\n \".jl\": \"julia\",\n \".tf\": \"terraform\",\n \".tfvars\": \"terraform\",\n \".tex\": \"latex\",\n \".bib\": \"latex\",\n \".prisma\": \"prisma\",\n};\n\n/**\n * Check if a path exists (async)\n */\nasync function pathExists(path: string): Promise {\n try {\n await access(path, constants.F_OK);\n return true;\n } catch {\n return false;\n }\n}\n\n/**\n * Find binary in PATH, checking Mason bin first\n */\nexport async function which(bin: string): Promise {\n // 1. Check Mason bin first (Neovim LSP servers)\n const masonPath = resolve(MASON_BIN_PATH, bin);\n if (await pathExists(masonPath)) return masonPath;\n\n // 2. Check PATH\n const pathEnv = process.env.PATH || \"\";\n for (const dir of pathEnv.split(\":\")) {\n if (!dir) continue;\n const fullPath = resolve(dir, bin);\n if (await pathExists(fullPath)) return fullPath;\n }\n\n return undefined;\n}\n\n/**\n * Helper to find nearest file upward in directory tree\n */\nexport function nearestRoot(includePatterns: string[], excludePatterns?: string[]): RootFunction {\n return async (file: string, cwd: string) => {\n let current = dirname(file);\n const stopAt = cwd;\n\n // Check for exclusions first\n if (excludePatterns) {\n while (current !== \"/\" && current !== dirname(current)) {\n for (const pattern of excludePatterns) {\n if (await pathExists(resolve(current, pattern))) {\n return undefined;\n }\n }\n if (current === stopAt) break;\n current = dirname(current);\n }\n }\n\n // Reset and check for inclusions\n current = dirname(file);\n while (current !== \"/\" && current !== dirname(current)) {\n for (const pattern of includePatterns) {\n if (await pathExists(resolve(current, pattern))) {\n return current;\n }\n }\n if (current === stopAt) break;\n current = dirname(current);\n }\n return undefined;\n };\n}\n\n/**\n * Create a simple spawn handle\n */\nfunction createHandle(\n bin: string,\n args: string[],\n root: string,\n initialization?: Record,\n): LspHandle | undefined {\n const proc = spawn(bin, args, { cwd: root }) as ChildProcessWithoutNullStreams;\n return { process: proc, initialization };\n}\n\n// ============================================================================\n// LSP Server Definitions\n// ============================================================================\n\nexport const LSP_SERVERS: LspServerInfo[] = [\n // TypeScript/JavaScript\n {\n id: \"typescript\",\n extensions: [\".ts\", \".tsx\", \".js\", \".jsx\", \".mjs\", \".cjs\", \".mts\", \".cts\"],\n root: nearestRoot(\n [\n \"package-lock.json\",\n \"bun.lockb\",\n \"bun.lock\",\n \"pnpm-lock.yaml\",\n \"yarn.lock\",\n \"package.json\",\n \"tsconfig.json\",\n ],\n [\"deno.json\", \"deno.jsonc\"],\n ),\n async spawn(root, cwd) {\n // Try to find local tsserver first\n let tsserver: string | undefined;\n const possiblePaths = [\n resolve(cwd, \"node_modules\", \"typescript\", \"lib\", \"tsserver.js\"),\n resolve(root, \"node_modules\", \"typescript\", \"lib\", \"tsserver.js\"),\n ];\n for (const p of possiblePaths) {\n if (await pathExists(p)) {\n tsserver = p;\n break;\n }\n }\n\n const bin = await which(\"typescript-language-server\");\n if (!bin) return undefined;\n\n return createHandle(\n bin,\n [\"--stdio\"],\n root,\n tsserver ? { tsserver: { path: tsserver } } : undefined,\n );\n },\n },\n\n // Deno\n {\n id: \"deno\",\n extensions: [\".ts\", \".tsx\", \".js\", \".jsx\", \".mjs\"],\n root: nearestRoot(\n [\"deno.json\", \"deno.jsonc\"],\n [\n \"package-lock.json\",\n \"bun.lockb\",\n \"bun.lock\",\n \"pnpm-lock.yaml\",\n \"yarn.lock\",\n \"package.json\",\n \"tsconfig.json\",\n ],\n ),\n async spawn(root) {\n const bin = await which(\"deno\");\n if (!bin) return undefined;\n return createHandle(bin, [\"lsp\"], root);\n },\n },\n\n // Oxlint\n {\n id: \"oxlint\",\n extensions: [\n \".ts\",\n \".tsx\",\n \".js\",\n \".jsx\",\n \".mjs\",\n \".cjs\",\n \".mts\",\n \".cts\",\n \".json\",\n \".jsonc\",\n \".vue\",\n \".astro\",\n \".svelte\",\n \".css\",\n ],\n root: nearestRoot([\n \".oxlintrc.json\",\n \"package-lock.json\",\n \"bun.lockb\",\n \"bun.lock\",\n \"pnpm-lock.yaml\",\n \"yarn.lock\",\n \"package.json\",\n ]),\n async spawn(root) {\n // Try local oxlint first\n let bin = resolve(root, \"node_modules\", \".bin\", \"oxlint\");\n if (!(await pathExists(bin))) {\n bin = (await which(\"oxlint\")) || \"\";\n }\n\n if (!bin || !(await pathExists(bin))) {\n // Try bun x oxlint\n const bunBin = (await which(\"bun\")) || \"bun\";\n const proc = spawn(bunBin, [\"x\", \"oxlint\", \"--lsp\"], {\n cwd: root,\n }) as ChildProcessWithoutNullStreams;\n return { process: proc };\n }\n\n return createHandle(bin, [\"--lsp\"], root);\n },\n },\n\n // Rust\n {\n id: \"rust\",\n extensions: [\".rs\"],\n root: nearestRoot([\"Cargo.toml\", \"Cargo.lock\"]),\n async spawn(root) {\n const bin = await which(\"rust-analyzer\");\n if (!bin) return undefined;\n return createHandle(bin, [], root);\n },\n },\n\n // Go\n {\n id: \"gopls\",\n extensions: [\".go\"],\n root: nearestRoot([\"go.work\", \"go.mod\", \"go.sum\"]),\n async spawn(root) {\n const bin = await which(\"gopls\");\n if (!bin) return undefined;\n return createHandle(bin, [], root);\n },\n },\n\n // Python (Pyright)\n {\n id: \"pyright\",\n extensions: [\".py\", \".pyi\"],\n root: nearestRoot([\n \"pyproject.toml\",\n \"setup.py\",\n \"setup.cfg\",\n \"requirements.txt\",\n \"Pipfile\",\n \"pyrightconfig.json\",\n ]),\n async spawn(root) {\n let bin = await which(\"pyright-langserver\");\n\n if (!bin) {\n // Try bun x\n const bunBin = (await which(\"bun\")) || \"bun\";\n const proc = spawn(bunBin, [\"x\", \"pyright\", \"--stdio\"], {\n cwd: root,\n }) as ChildProcessWithoutNullStreams;\n return { process: proc };\n }\n\n const initialization: Record = {};\n // Check for virtual env\n const venvPaths = [\n process.env.VIRTUAL_ENV,\n resolve(root, \".venv\"),\n resolve(root, \"venv\"),\n ].filter(Boolean) as string[];\n\n for (const venvPath of venvPaths) {\n const pythonPath =\n process.platform === \"win32\"\n ? resolve(venvPath, \"Scripts\", \"python.exe\")\n : resolve(venvPath, \"bin\", \"python\");\n if (await pathExists(pythonPath)) {\n initialization.pythonPath = pythonPath;\n break;\n }\n }\n\n return createHandle(bin, [\"--stdio\"], root, initialization);\n },\n },\n\n // Lua\n {\n id: \"lua\",\n extensions: [\".lua\"],\n root: nearestRoot([\n \".luarc.json\",\n \".luarc.jsonc\",\n \".luacheckrc\",\n \".stylua.toml\",\n \"stylua.toml\",\n \".git\",\n ]),\n async spawn(root) {\n const bin = await which(\"lua-language-server\");\n if (!bin) return undefined;\n return createHandle(bin, [], root, { Lua: { diagnostics: { globals: [\"vim\"] } } });\n },\n },\n\n // PHP\n {\n id: \"intelephense\",\n extensions: [\".php\"],\n root: nearestRoot([\"composer.json\", \"composer.lock\", \".php-version\"]),\n async spawn(root) {\n const bin = await which(\"intelephense\");\n if (!bin) return undefined;\n return createHandle(bin, [\"--stdio\"], root, { telemetry: { enabled: false } });\n },\n },\n\n // Svelte\n {\n id: \"svelte\",\n extensions: [\".svelte\"],\n root: nearestRoot([\n \"package-lock.json\",\n \"bun.lockb\",\n \"bun.lock\",\n \"pnpm-lock.yaml\",\n \"yarn.lock\",\n \"package.json\",\n ]),\n async spawn(root) {\n const bin = await which(\"svelteserver\");\n if (!bin) return undefined;\n return createHandle(bin, [\"--stdio\"], root);\n },\n },\n\n // Vue\n {\n id: \"vue\",\n extensions: [\".vue\"],\n root: nearestRoot([\n \"package-lock.json\",\n \"bun.lockb\",\n \"bun.lock\",\n \"pnpm-lock.yaml\",\n \"yarn.lock\",\n \"package.json\",\n ]),\n async spawn(root) {\n const bin = await which(\"vue-language-server\");\n if (!bin) return undefined;\n return createHandle(bin, [\"--stdio\"], root);\n },\n },\n\n // Astro\n {\n id: \"astro\",\n extensions: [\".astro\"],\n root: nearestRoot([\n \"package-lock.json\",\n \"bun.lockb\",\n \"bun.lock\",\n \"pnpm-lock.yaml\",\n \"yarn.lock\",\n \"package.json\",\n ]),\n async spawn(root, cwd) {\n const bin = await which(\"astro-ls\");\n if (!bin) return undefined;\n\n // Find typescript for astro\n let tsdk: string | undefined;\n const possiblePaths = [\n resolve(cwd, \"node_modules\", \"typescript\", \"lib\"),\n resolve(root, \"node_modules\", \"typescript\", \"lib\"),\n ];\n for (const p of possiblePaths) {\n if (await pathExists(p)) {\n tsdk = p;\n break;\n }\n }\n\n return createHandle(bin, [\"--stdio\"], root, tsdk ? { typescript: { tsdk } } : undefined);\n },\n },\n\n // Zig\n {\n id: \"zls\",\n extensions: [\".zig\", \".zon\"],\n root: nearestRoot([\"build.zig\", \"build.zig.zon\"]),\n async spawn(root) {\n const bin = await which(\"zls\");\n if (!bin) return undefined;\n return createHandle(bin, [], root);\n },\n },\n\n // C/C++\n {\n id: \"clangd\",\n extensions: [\".c\", \".cpp\", \".cc\", \".cxx\", \".c++\", \".h\", \".hpp\", \".hh\", \".hxx\", \".h++\"],\n root: nearestRoot([\n \"compile_commands.json\",\n \"compile_flags.txt\",\n \".clangd\",\n \"CMakeLists.txt\",\n \"Makefile\",\n ]),\n async spawn(root) {\n const bin = await which(\"clangd\");\n if (!bin) return undefined;\n return createHandle(bin, [\"--background-index\", \"--clang-tidy\"], root);\n },\n },\n\n // C#\n {\n id: \"csharp\",\n extensions: [\".cs\"],\n root: nearestRoot([\".slnx\", \".sln\", \".csproj\", \"global.json\"]),\n async spawn(root) {\n const bin = (await which(\"csharp-ls\")) || (await which(\"omnisharp\"));\n if (!bin) return undefined;\n return createHandle(bin, [\"-lsp\"], root);\n },\n },\n\n // Swift\n {\n id: \"sourcekit-lsp\",\n extensions: [\".swift\"],\n root: nearestRoot([\"Package.swift\", \"*.xcodeproj\", \"*.xcworkspace\"]),\n async spawn(root) {\n const bin = await which(\"sourcekit-lsp\");\n if (!bin) return undefined;\n return createHandle(bin, [], root);\n },\n },\n\n // Elixir\n {\n id: \"elixir-ls\",\n extensions: [\".ex\", \".exs\"],\n root: nearestRoot([\"mix.exs\", \"mix.lock\"]),\n async spawn(root) {\n const bin = (await which(\"elixir-ls\")) || (await which(\"language_server.sh\"));\n if (!bin) return undefined;\n return createHandle(bin, [], root);\n },\n },\n\n // Kotlin\n {\n id: \"kotlin-ls\",\n extensions: [\".kt\", \".kts\"],\n root: nearestRoot([\n \"settings.gradle.kts\",\n \"settings.gradle\",\n \"build.gradle.kts\",\n \"build.gradle\",\n \"pom.xml\",\n ]),\n async spawn(root) {\n const bin = await which(\"kotlin-lsp\");\n if (!bin) return undefined;\n return createHandle(bin, [\"--stdio\"], root);\n },\n },\n\n // Dart\n {\n id: \"dart\",\n extensions: [\".dart\"],\n root: nearestRoot([\"pubspec.yaml\", \"analysis_options.yaml\"]),\n async spawn(root) {\n const bin = await which(\"dart\");\n if (!bin) return undefined;\n return createHandle(bin, [\"language-server\", \"--lsp\"], root);\n },\n },\n\n // OCaml\n {\n id: \"ocaml-lsp\",\n extensions: [\".ml\", \".mli\"],\n root: nearestRoot([\"dune-project\", \"dune-workspace\", \".merlin\", \"opam\"]),\n async spawn(root) {\n const bin = await which(\"ocamllsp\");\n if (!bin) return undefined;\n return createHandle(bin, [], root);\n },\n },\n\n // Bash\n {\n id: \"bash\",\n extensions: [\".sh\", \".bash\", \".zsh\", \".ksh\"],\n root: () => undefined, // Will use cwd\n async spawn(root) {\n const bin = await which(\"bash-language-server\");\n if (!bin) return undefined;\n return createHandle(bin, [\"start\"], root);\n },\n },\n\n // Nix\n {\n id: \"nixd\",\n extensions: [\".nix\"],\n root: nearestRoot([\"flake.nix\", \"flake.lock\", \".git\"]),\n async spawn(root) {\n const bin = await which(\"nixd\");\n if (!bin) return undefined;\n return createHandle(bin, [], root);\n },\n },\n\n // YAML\n {\n id: \"yaml\",\n extensions: [\".yaml\", \".yml\"],\n root: nearestRoot([\"package.json\"]),\n async spawn(root) {\n const bin = await which(\"yaml-language-server\");\n if (!bin) return undefined;\n return createHandle(bin, [\"--stdio\"], root);\n },\n },\n\n // JSON\n {\n id: \"json\",\n extensions: [\".json\", \".jsonc\"],\n root: nearestRoot([\"package.json\"]),\n async spawn(root) {\n const bin = await which(\"vscode-json-language-server\");\n if (!bin) return undefined;\n return createHandle(bin, [\"--stdio\"], root);\n },\n },\n\n // HTML\n {\n id: \"html\",\n extensions: [\".html\"],\n root: nearestRoot([\"package.json\"]),\n async spawn(root) {\n const bin = await which(\"vscode-html-language-server\");\n if (!bin) return undefined;\n return createHandle(bin, [\"--stdio\"], root);\n },\n },\n\n // CSS\n {\n id: \"css\",\n extensions: [\".css\", \".scss\", \".less\"],\n root: nearestRoot([\"package.json\"]),\n async spawn(root) {\n const bin = await which(\"vscode-css-language-server\");\n if (!bin) return undefined;\n return createHandle(bin, [\"--stdio\"], root);\n },\n },\n\n // Typst\n {\n id: \"tinymist\",\n extensions: [\".typ\", \".typc\"],\n root: nearestRoot([\"typst.toml\"]),\n async spawn(root) {\n const bin = await which(\"tinymist\");\n if (!bin) return undefined;\n return createHandle(bin, [\"lsp\"], root);\n },\n },\n\n // Terraform\n {\n id: \"terraform\",\n extensions: [\".tf\", \".tfvars\"],\n root: nearestRoot([\".terraform.lock.hcl\", \"terraform.tfstate\", \"*.tf\"]),\n async spawn(root) {\n const bin = await which(\"terraform-ls\");\n if (!bin) return undefined;\n return createHandle(bin, [\"serve\"], root);\n },\n },\n\n // Gleam\n {\n id: \"gleam\",\n extensions: [\".gleam\"],\n root: nearestRoot([\"gleam.toml\", \"manifest.toml\"]),\n async spawn(root) {\n const bin = await which(\"gleam\");\n if (!bin) return undefined;\n return createHandle(bin, [\"lsp\"], root);\n },\n },\n\n // Clojure\n {\n id: \"clojure-lsp\",\n extensions: [\".clj\", \".cljs\", \".cljc\", \".edn\"],\n root: nearestRoot([\"deps.edn\", \"project.clj\", \"shadow-cljs.edn\", \"bb.edn\", \"build.boot\"]),\n async spawn(root) {\n const bin = await which(\"clojure-lsp\");\n if (!bin) return undefined;\n return createHandle(bin, [\"listen\"], root);\n },\n },\n\n // Haskell\n {\n id: \"haskell-language-server\",\n extensions: [\".hs\", \".lhs\"],\n root: nearestRoot([\"stack.yaml\", \"cabal.project\", \"hie.yaml\", \"*.cabal\"]),\n async spawn(root) {\n const bin = await which(\"haskell-language-server-wrapper\");\n if (!bin) return undefined;\n return createHandle(bin, [\"--lsp\"], root);\n },\n },\n\n // Julia\n {\n id: \"julials\",\n extensions: [\".jl\"],\n root: nearestRoot([\"Project.toml\", \"Manifest.toml\"]),\n async spawn(root) {\n const bin = await which(\"julia\");\n if (!bin) return undefined;\n const proc = spawn(\n bin,\n [\"--startup-file=no\", \"--history-file=no\", \"-e\", \"using LanguageServer; runserver()\"],\n { cwd: root },\n ) as ChildProcessWithoutNullStreams;\n return { process: proc };\n },\n },\n\n // Prisma\n {\n id: \"prisma\",\n extensions: [\".prisma\"],\n root: nearestRoot([\"schema.prisma\", \"prisma/schema.prisma\"]),\n async spawn(root) {\n const bin = await which(\"prisma\");\n if (!bin) return undefined;\n return createHandle(bin, [\"language-server\"], root);\n },\n },\n];\n" }, { "path": "agents/pi/extensions/notify.ts", "content": "/**\n * Pi Notify Extension\n *\n * Sends a native terminal notification when Pi agent is done and waiting for input.\n * Supports multiple terminal protocols:\n * - OSC 777: Ghostty, iTerm2, WezTerm, rxvt-unicode\n * - OSC 99: Kitty\n * - Windows toast: Windows Terminal (WSL)\n */\n\nimport type { ExtensionAPI } from \"@mariozechner/pi-coding-agent\";\n\nfunction windowsToastScript(title: string, body: string): string {\n\tconst type = \"Windows.UI.Notifications\";\n\tconst mgr = `[${type}.ToastNotificationManager, ${type}, ContentType = WindowsRuntime]`;\n\tconst template = `[${type}.ToastTemplateType]::ToastText01`;\n\tconst toast = `[${type}.ToastNotification]::new($xml)`;\n\treturn [\n\t\t`${mgr} > $null`,\n\t\t`$xml = [${type}.ToastNotificationManager]::GetTemplateContent(${template})`,\n\t\t`$xml.GetElementsByTagName('text')[0].AppendChild($xml.CreateTextNode('${body}')) > $null`,\n\t\t`[${type}.ToastNotificationManager]::CreateToastNotifier('${title}').Show(${toast})`,\n\t].join(\"; \");\n}\n\nfunction notifyOSC777(title: string, body: string): void {\n\tprocess.stdout.write(`\\x1b]777;notify;${title};${body}\\x07`);\n}\n\nfunction notifyOSC99(title: string, body: string): void {\n\t// Kitty OSC 99: i=notification id, d=0 means not done yet, p=body for second part\n\tprocess.stdout.write(`\\x1b]99;i=1:d=0;${title}\\x1b\\\\`);\n\tprocess.stdout.write(`\\x1b]99;i=1:p=body;${body}\\x1b\\\\`);\n}\n\nfunction notifyWindows(title: string, body: string): void {\n\tconst { execFile } = require(\"child_process\");\n\texecFile(\"powershell.exe\", [\"-NoProfile\", \"-Command\", windowsToastScript(title, body)]);\n}\n\nfunction notify(title: string, body: string): void {\n\tif (process.env.WT_SESSION) {\n\t\tnotifyWindows(title, body);\n\t} else if (process.env.KITTY_WINDOW_ID) {\n\t\tnotifyOSC99(title, body);\n\t} else {\n\t\tnotifyOSC777(title, body);\n\t}\n}\n\nexport default function (pi: ExtensionAPI) {\n\tpi.on(\"agent_end\", async () => {\n\t\tnotify(\"Pi\", \"Ready for input!\");\n\t});\n}\n" }, { "path": "agents/pi/extensions/pi-codemode/README.md", "content": "# pi-codemode\n\nExecutor plugins for codemode plus curated npm/jj commands and whitelisted bash.\n\n## Tools\n- `pi.*` builtins (filesystem, bash, webfetch)\n- `fff.*` search tools\n- `npm.run` run npm scripts\n- `npm.install` install packages via lockfile-aware package manager selection\n- `jj.status` / `jj.diff` / `jj.log` / `jj.new` / `jj.describe` / `jj.commit` for jj\n\n## Bash whitelist\n- Package managers: `npm`, `pnpm`, `bun`, `yarn`, `npx`, `node`\n- File operations: `mkdir`, `touch`, `cp`, `mv`, `rm`, `ln`, `chmod`, `chown`\n- Utilities: `pwd`, `echo`, `which`, `uname`, `date`, `sleep`\n- Everything else is blocked with guidance to use the equivalent `tools.pi.*` tool\n\n## Rules\n- no full bash access — whitelisted package managers only\n- use JS sandbox + named tools instead\n- repo.install picks pnpm if pnpm-lock.yaml exists, bun if bun.lock/bun.lockb exists, else npm" }, { "path": "agents/pi/extensions/pi-codemode/executor.jsonc", "content": "{\n \"sources\": [\n {\n \"kind\": \"mcp\",\n \"transport\": \"remote\",\n \"name\": \"mcp-typescript server on vercel\",\n \"endpoint\": \"https://mcp.exa.ai/mcp\",\n \"remoteTransport\": \"auto\",\n \"namespace\": \"mcp_typescript_server_on_vercel\"\n }\n ]\n}\n" }, { "path": "agents/pi/extensions/pi-codemode/index.ts", "content": "import type { ExtensionAPI } from \"@mariozechner/pi-coding-agent\";\nimport { createCodemodeTool } from \"./src/codemode.js\";\nimport { disposeAllExecutors, getExecutor } from \"./src/executor-cache.js\";\nimport { acquireSandbox, disposeAll as disposeAllSandboxes } from \"./src/sandbox-cache.js\";\nimport { initFinder } from \"./src/fff.js\";\n\nexport default function registerCodemode(pi: ExtensionAPI) {\n pi.registerTool(createCodemodeTool());\n\n const activate = () => pi.setActiveTools([\"codemode\"]);\n\n // Pre-warm sandbox, finder, and executor on session start\n pi.on(\"session_start\", async (event, ctx) => {\n if (event.reason === \"startup\" || event.reason === \"reload\" || event.reason === \"new\") {\n await acquireSandbox(ctx.cwd); // creates & caches sandbox\n initFinder(ctx.cwd).catch(() => {}); // fire-and-forget fff scan\n getExecutor(ctx.cwd).catch(() => {}); // fire-and-forget executor creation\n }\n activate();\n });\n\n pi.on(\"before_agent_start\", async () => {\n activate();\n return undefined;\n });\n\n pi.on(\"session_shutdown\", async () => {\n await Promise.allSettled([\n disposeAllExecutors(),\n disposeAllSandboxes(),\n ]);\n });\n}\n" }, { "path": "agents/pi/extensions/pi-codemode/package.json", "content": "{\n \"name\": \"pi-codemode\",\n \"version\": \"0.1.0\",\n \"private\": true,\n \"type\": \"module\",\n \"description\": \"pi codemode extension with executor SDK and secure-exec sandbox\",\n \"keywords\": [\n \"pi-package\"\n ],\n \"peerDependencies\": {\n \"@mariozechner/pi-ai\": \"*\",\n \"@mariozechner/pi-agent-core\": \"*\",\n \"@mariozechner/pi-coding-agent\": \"*\",\n \"@mariozechner/pi-tui\": \"*\",\n \"@sinclair/typebox\": \"*\"\n },\n \"dependencies\": {\n \"@executor-js/plugin-graphql\": \"^0.0.1-beta.2\",\n \"@executor-js/plugin-mcp\": \"^0.0.1-beta.2\",\n \"@executor-js/plugin-openapi\": \"^0.0.1-beta.2\",\n \"@executor-js/sdk\": \"^0.0.1-beta.2\",\n \"@ff-labs/fff-node\": \"^0.5.2\",\n \"jsonc-parser\": \"^3.3.1\",\n \"secure-exec\": \"^0.2.1\",\n \"turndown\": \"^7.2.4\"\n },\n \"devDependencies\": {},\n \"pi\": {\n \"extensions\": [\n \"./index.ts\"\n ]\n },\n \"packageManager\": \"bun@1.3.12\"\n}" }, { "path": "agents/pi/extensions/pi-codemode/src/builtins.ts", "content": "import {\n createBashTool,\n createEditTool,\n createFindTool,\n createGrepTool,\n createLsTool,\n createReadTool,\n createWriteTool,\n} from \"@mariozechner/pi-coding-agent\";\nimport { createCustomReadTool } from \"./read.js\";\nimport { webfetch } from \"./webfetch.js\";\nimport type { BuiltinToolName } from \"./types.js\";\nimport { Type } from \"@sinclair/typebox\";\n\nexport type BuiltinTool = {\n name: string;\n description: string;\n parameters: unknown;\n execute: (...args: any[]) => Promise;\n};\n\n// Only package managers — everything else has a codemode tool equivalent\nconst BASH_COMMAND_WHITELIST = new Set([\n // Package managers\n \"vp\",\n \"vpx\",\n \"npm\",\n \"pnpm\",\n \"bun\",\n \"yarn\",\n \"npx\",\n // File operations (no codemode tool equivalent)\n \"mkdir\",\n \"touch\",\n \"cp\",\n \"mv\",\n // Utilities\n \"pwd\",\n \"which\",\n \"type\",\n \"uname\",\n]);\n\nconst WHITELIST_HELP = () => [\n `Allowed commands: ${[...BASH_COMMAND_WHITELIST].sort().join(\", \")}`,\n \"Use tools.pi.* for reading, writing, searching, grepping, editing files.\",\n].join(\"\\n\");\n\nfunction extractCommandName(command: string): string | null {\n // Strip shell redirects, pipes, chaining, then grab first word\n const cleaned = command\n .replace(/\\\\s*[|&;<>]/g, \" \")\n .replace(/\\(/g, \" \")\n .trim();\n const first = cleaned.split(/\\s+/)[0];\n if (!first) return null;\n // Strip leading path (e.g., ./node_modules/.bin/npm) — not whitelisted\n if (first.includes(\"/\")) return null;\n return first;\n}\n\nfunction createWhitelistedBashTool(cwd: string): BuiltinTool {\n const bashTool = createBashTool(cwd) as BuiltinTool;\n\n return {\n name: bashTool.name,\n description:\n \"Run package manager commands (npm, pnpm, bun, yarn, npx, node). Other commands are blocked — use tools.pi.* instead.\",\n parameters: bashTool.parameters,\n async execute(toolCallId: string, args: any, signal: AbortSignal | undefined, onUpdate: any) {\n const command = String(args?.command ?? \"\").trim();\n if (!command) {\n return {\n content: [{ type: \"text\", text: \"No command provided.\\n\\n\" + WHITELIST_HELP() }],\n };\n }\n\n const cmdName = extractCommandName(command);\n\n if (!cmdName || !BASH_COMMAND_WHITELIST.has(cmdName)) {\n const blocked = cmdName ? `\"${cmdName}\" is not whitelisted` : \"Could not parse command\";\n return {\n content: [\n {\n type: \"text\",\n text: [`Error: ${blocked}`, \"\", WHITELIST_HELP()].join(\"\\n\"),\n },\n ],\n };\n }\n\n // Proxy: forward execute via original tool's execute\n const result = await bashTool.execute(toolCallId, args, signal, onUpdate);\n return result;\n },\n };\n}\n\nconst webfetchTool: BuiltinTool = {\n name: \"webfetch\",\n description:\n \"Fetch web content and convert to markdown, text, or html. Use when URLs are mentioned to retrieve content. HTTP URLs upgraded to HTTPS. Images and binary content return empty text.\",\n parameters: Type.Object({\n url: Type.String({ description: \"The URL to fetch content from\" }),\n format: Type.Optional(\n Type.Union([Type.Literal(\"markdown\"), Type.Literal(\"text\"), Type.Literal(\"html\")], {\n description: \"Output format: markdown (default), text, or html\",\n }),\n ),\n timeout: Type.Optional(\n Type.Number({ description: \"Timeout in seconds (max 120, default 30)\" }),\n ),\n }),\n execute: webfetch,\n};\n\nexport type BuiltinToolset = Record;\n\nconst PI_SIGNATURES = [\n \"tools.pi.read({ path, offset?, limit? })\",\n \"tools.pi.bash({ command, timeout? })\",\n \"tools.pi.edit({ path, edits: [{ oldText, newText }] })\",\n \"tools.pi.write({ path, content })\",\n \"tools.pi.grep({ pattern, path?, glob?, ignoreCase?, literal?, context?, limit? })\",\n \"tools.pi.find({ pattern, path?, limit? })\",\n \"tools.pi.ls({ path?, limit? })\",\n \"tools.pi.webfetch({ url, format?, timeout? })\",\n];\n\nconst FFF_SIGNATURES = [\n \"tools.fff.grep({ pattern, path?, mode?, smartCase?, glob?, maxMatchesPerFile?, context?, classifyDefinitions?, limit? })\",\n \"tools.fff.fileSearch({ query, path?, limit? })\",\n \"tools.fff.multiGrep({ patterns, path?, limit? })\",\n \"tools.fff.recentFiles({ path?, limit?, minFrecencyScore?, includeUntracked? })\",\n \"tools.fff.searchThenGrep({ pathQuery, contentQuery, path?, maxFiles?, limit? })\",\n];\n\nconst META_APIS = [\"tools.list()\", \"tools.schema(name)\", \"tools.definitions()\"];\n\nexport function createBuiltinToolset(cwd: string) {\n return {\n read: createCustomReadTool(cwd) as BuiltinTool,\n edit: createEditTool(cwd) as BuiltinTool,\n write: createWriteTool(cwd) as BuiltinTool,\n grep: createGrepTool(cwd) as BuiltinTool,\n find: createFindTool(cwd) as BuiltinTool,\n ls: createLsTool(cwd) as BuiltinTool,\n bash: createWhitelistedBashTool(cwd) as BuiltinTool,\n webfetch: webfetchTool,\n };\n}\n\nexport function buildCodemodeApiPrompt(): string {\n return [\n \"## Available APIs\",\n \"\",\n \"### pi tools\",\n ...PI_SIGNATURES,\n \"\",\n \"### fff tools\",\n ...FFF_SIGNATURES,\n \"\",\n \"### Discovery\",\n ...META_APIS,\n \"\",\n \"All pi and fff tools return plain text strings. Other tools (MCP, OpenAPI, GraphQL) return objects.\",\n \"If the user mentions an unknown tool, call tools.list() to get a list of available tools\",\n \"Before using any unfamiliar tool, call tools.schema('tool.name') to get its exact parameter and return types.\",\n \"Dynamically loaded tools are namespaced: tools.openapi.petstore.listPets, tools.mcp.myServer.search.\",\n \"Prefer one codemode call; batch work with JS and Promise.all.\",\n \"\",\n \"### Bash restrictions\",\n `tools.pi.bash only allows: ${[...BASH_COMMAND_WHITELIST].sort().join(\", \")}.`,\n \"Everything else is blocked — use the dedicated tools above instead.\",\n ].join(\"\\n\");\n}\n" }, { "path": "agents/pi/extensions/pi-codemode/src/codemode.ts", "content": "import { Type } from \"@sinclair/typebox\";\nimport { Text } from \"@mariozechner/pi-tui\";\nimport type { ExtensionContext, Theme, ToolDefinition } from \"@mariozechner/pi-coding-agent\";\nimport { buildCodemodeApiPrompt } from \"./builtins.js\";\nimport { getExecutor } from \"./executor-cache.js\";\nimport { renderCodemodeCall, renderCodemodeResult } from \"./render.js\";\nimport { runCodemode } from \"./runtime.js\";\nimport { formatTraceForAgent, summarizeTraceForContext } from \"./trace.js\";\nimport type { CodemodeResultDetails } from \"./types.js\";\nimport { buildPromptGuidelines, stripCodeFences } from \"./util.js\";\n\nconst codemodeSchema = Type.Object({\n code: Type.String({ description: \"JavaScript code with tools.pi.* access\" }),\n});\n\nexport function createCodemodeTool(): ToolDefinition {\n return {\n name: \"codemode\",\n label: \"codemode\",\n description: \"Execute JavaScript in a secure sandbox with access to pi filesystem tools, fff search tools, and dynamically loaded executor tools (MCP, OpenAPI, GraphQL).\",\n promptSnippet: buildCodemodeApiPrompt(),\n promptGuidelines: buildPromptGuidelines(),\n parameters: codemodeSchema,\n\n async execute(\n _toolCallId: string,\n params: { code: string },\n signal: AbortSignal | undefined,\n _onUpdate: unknown,\n ctx: ExtensionContext,\n ) {\n const code = stripCodeFences(params.code);\n const executor = await getExecutor(ctx.cwd);\n const result = await runCodemode({\n code,\n cwd: ctx.cwd,\n executor,\n signal,\n });\n const { text, images } = formatTraceForAgent(result.trace, result.value, result.logs);\n\n return {\n content: [\n { type: \"text\", text },\n ...images.map((img) => ({ type: \"image\" as const, data: img.data, mimeType: img.mimeType })),\n ],\n details: {\n trace: result.trace,\n value: result.value,\n logs: result.logs,\n summary: summarizeTraceForContext(result.trace),\n },\n };\n },\n\n renderCall(args: { code?: string }, theme: Theme) {\n return renderCodemodeCall(args.code ?? \"\", theme);\n },\n\n renderResult(result, options, theme) {\n const trace = result.details?.trace;\n if (!trace) return new Text(theme.fg(\"error\", \"Missing codemode trace\"), 0, 0);\n if (options.isPartial) return new Text(theme.fg(\"warning\", \"Executing...\"), 0, 0);\n return renderCodemodeResult(trace, options.expanded, theme);\n },\n };\n}\n" }, { "path": "agents/pi/extensions/pi-codemode/src/executor-cache.ts", "content": "import { createExecutor, type Executor } from \"@executor-js/sdk\";\nimport { mcpPlugin } from \"@executor-js/plugin-mcp\";\nimport { openApiPlugin } from \"@executor-js/plugin-openapi\";\nimport { graphqlPlugin } from \"@executor-js/plugin-graphql\";\nimport { piPlugin } from \"./pi-plugin.js\";\nimport { fffPlugin } from \"./fff-plugin.js\";\nimport { getExecutorConfigPath, loadSourcesFromConfig } from \"./source-config.js\";\nimport { hydrateExecutorSources } from \"./source-hydrate.js\";\nimport { stat } from \"node:fs/promises\";\n\ntype CachedExecutor = {\n executor: Executor;\n mtimeMs: number;\n};\n\nconst cache = new Map();\n\nconst configMtime = async (): Promise => {\n try {\n return (await stat(getExecutorConfigPath())).mtimeMs;\n } catch {\n return 0;\n }\n};\n\nexport const getExecutor = async (cwd: string): Promise => {\n const mtimeMs = await configMtime();\n const cached = cache.get(cwd);\n if (cached && cached.mtimeMs === mtimeMs) return cached.executor;\n\n if (cached) {\n await cached.executor.close();\n cache.delete(cwd);\n }\n\n const loaded = await loadSourcesFromConfig();\n\n const executor = await createExecutor({\n scope: { name: \"pi-codemode-\" + cwd },\n plugins: [\n piPlugin(cwd),\n fffPlugin(cwd),\n mcpPlugin(),\n openApiPlugin(),\n graphqlPlugin(),\n ] as const,\n });\n\n await hydrateExecutorSources(executor, loaded.sources, {\n configPath: loaded.configPath,\n unsupported: loaded.unsupported,\n });\n\n cache.set(cwd, { executor, mtimeMs: loaded.mtimeMs });\n return executor;\n};\n\nexport const disposeExecutor = async (cwd: string): Promise => {\n const cached = cache.get(cwd);\n if (!cached) return;\n await cached.executor.close();\n cache.delete(cwd);\n};\n\nexport const disposeAllExecutors = async (): Promise => {\n await Promise.allSettled(Array.from(cache.values()).map((entry) => entry.executor.close()));\n cache.clear();\n};" }, { "path": "agents/pi/extensions/pi-codemode/src/fff-plugin.ts", "content": "import {\n definePlugin,\n ToolRegistration,\n ToolId,\n ToolInvocationResult,\n type PluginContext,\n} from \"@executor-js/sdk\";\nimport { createFffBuiltinToolset, initFinder } from \"./fff.js\";\nimport { fffToolNames, type FffToolName } from \"./types.js\";\nimport { formatError } from \"./util.js\";\n\nexport const fffPlugin = (cwd: string) =>\n definePlugin({\n key: \"fff\",\n init: async (ctx: PluginContext) => {\n // Eagerly initialize finder on plugin load\n await initFinder(cwd);\n\n const tools = createFffBuiltinToolset(cwd);\n\n // Register fff.* SIMD-accelerated search tools\n await ctx.tools.registerInvoker(\"fff\", {\n invoke: async (toolId: string, args: unknown, _options: unknown) => {\n const name = toolId.split(\".\").pop() as FffToolName | undefined;\n if (!name || !(name in tools)) {\n return new ToolInvocationResult({ data: null, error: \"Unknown fff tool: \" + toolId });\n }\n\n const tool = tools[name];\n try {\n const data = await tool.execute(toolId, args ?? {}, undefined, () => {});\n return new ToolInvocationResult({ data, error: null });\n } catch (cause) {\n return new ToolInvocationResult({ data: null, error: formatError(cause) });\n }\n },\n });\n\n await ctx.tools.register(\n fffToolNames.map((name) => {\n const tool = tools[name];\n return new ToolRegistration({\n id: ToolId.make(\"fff.\" + name),\n pluginKey: \"fff\",\n sourceId: \"pi\",\n name,\n description: tool.description,\n inputSchema: tool.parameters as Record,\n });\n }),\n );\n\n return { extension: {} };\n },\n });" }, { "path": "agents/pi/extensions/pi-codemode/src/fff.ts", "content": "import { FileFinder } from \"@ff-labs/fff-node\";\nimport { Type } from \"@sinclair/typebox\";\nimport { resolve } from \"node:path\";\nimport type { BuiltinTool } from \"./builtins.js\";\nimport type { FffToolName } from \"./types.js\";\n\n// Global instance cache\nconst finderCache = new Map();\n\nasync function getFinder(cwd: string, searchPath?: string): Promise {\n const basePath = resolve(cwd, searchPath || \".\");\n if (!finderCache.has(basePath)) {\n const result = FileFinder.create({ basePath });\n if (!result.ok) throw new Error(result.error || \"unknown\");\n finderCache.set(basePath, result.value);\n result.value.waitForScan(5000).catch(() => console.log(\"fff scan timeout\"));\n }\n return finderCache.get(basePath)!;\n}\n\n// Eagerly initialize finder for a path (call on session start)\nexport async function initFinder(cwd: string, searchPath?: string): Promise {\n await getFinder(cwd, searchPath);\n}\n\nexport function destroyAllFinders(): void {\n for (const f of finderCache.values()) f.destroy();\n finderCache.clear();\n}\n\n// Grep tool\nexport const grepTool: BuiltinTool = {\n name: \"grep\",\n description: \"Search file contents using fff (SIMD-accelerated). Use as tools.fff.grep()\",\n parameters: Type.Object({\n pattern: Type.String(),\n path: Type.Optional(Type.String()),\n mode: Type.Optional(\n Type.Union([Type.Literal(\"plain\"), Type.Literal(\"regex\"), Type.Literal(\"fuzzy\")]),\n ),\n smartCase: Type.Optional(Type.Boolean()),\n glob: Type.Optional(Type.String()),\n maxMatchesPerFile: Type.Optional(Type.Number()),\n context: Type.Optional(Type.Number()),\n classifyDefinitions: Type.Optional(Type.Boolean()),\n limit: Type.Optional(Type.Number()),\n }),\n execute: async (_id: string, args: any, cwd: string) => {\n const finder = await getFinder(cwd, args.path);\n const query = args.glob ? args.glob + \" \" + args.pattern : args.pattern;\n const res = finder.grep(query, {\n mode: args.mode || \"plain\",\n maxFileSize: args.maxFileSize || 0,\n maxMatchesPerFile: args.maxMatchesPerFile || 0,\n smartCase: args.smartCase ?? true,\n beforeContext: args.context || 0,\n afterContext: args.context || 0,\n classifyDefinitions: args.classifyDefinitions || false,\n } as any);\n if (!res.ok) throw new Error(res.error);\n const items = args.limit ? res.value.items.slice(0, args.limit) : res.value.items;\n return {\n matches: items.map((m: any) => ({\n path: m.relativePath,\n line: m.lineNumber,\n column: m.col,\n content: m.lineContent,\n matchRanges: m.matchRanges,\n isDefinition: m.isDefinition ?? false,\n })),\n totalMatched: res.value.totalMatched,\n totalFilesSearched: res.value.totalFilesSearched,\n nextCursor: res.value.nextCursor,\n };\n },\n};\n\n// File search tool\nexport const fileSearchTool: BuiltinTool = {\n name: \"fileSearch\",\n description: \"Fuzzy search for files by path. Use as tools.fff.fileSearch()\",\n parameters: Type.Object({\n query: Type.String(),\n path: Type.Optional(Type.String()),\n limit: Type.Optional(Type.Number()),\n }),\n execute: async (_id: string, args: any, cwd: string) => {\n const finder = await getFinder(cwd, args.path);\n const res = finder.fileSearch(args.query, { pageSize: args.limit || 20 });\n if (!res.ok) throw new Error(res.error);\n return {\n files: res.value.items.map((item: any) => ({\n path: item.relativePath,\n name: item.fileName,\n gitStatus: item.gitStatus,\n frecencyScore: item.totalFrecencyScore,\n })),\n };\n },\n};\n\n// Multi-pattern grep\nexport const multiGrepTool: BuiltinTool = {\n name: \"multiGrep\",\n description: \"Multi-pattern search (OR logic). Use as tools.fff.multiGrep()\",\n parameters: Type.Object({\n patterns: Type.Array(Type.String()),\n path: Type.Optional(Type.String()),\n limit: Type.Optional(Type.Number()),\n }),\n execute: async (_id: string, args: any, cwd: string) => {\n const finder = await getFinder(cwd, args.path);\n const res = finder.multiGrep({\n patterns: args.patterns,\n smartCase: true,\n });\n if (!res.ok) throw new Error(res.error);\n const items = args.limit ? res.value.items.slice(0, args.limit) : res.value.items;\n return {\n matches: items.map((m: any) => ({\n path: m.relativePath,\n line: m.lineNumber,\n content: m.lineContent,\n })),\n };\n },\n};\n\n// Recent files\nexport const recentFilesTool: BuiltinTool = {\n name: \"recentFiles\",\n description: \"Get recently accessed files (frecency). Use as tools.fff.recentFiles()\",\n parameters: Type.Object({\n path: Type.Optional(Type.String()),\n limit: Type.Optional(Type.Number()),\n minFrecencyScore: Type.Optional(Type.Number()),\n includeUntracked: Type.Optional(Type.Boolean()),\n }),\n execute: async (_id: string, args: any, cwd: string) => {\n const finder = await getFinder(cwd, args.path);\n const res = finder.fileSearch(\"\", { pageSize: (args.limit || 20) * 2 });\n if (!res.ok) throw new Error(res.error);\n let files = res.value.items.map((item: any, i: number) => ({\n path: item.relativePath,\n name: item.fileName,\n gitStatus: item.gitStatus,\n frecencyScore: res.value.scores[i]?.baseScore || 0,\n }));\n if (args.minFrecencyScore)\n files = files.filter((f: any) => f.frecencyScore >= args.minFrecencyScore);\n if (args.includeUntracked === false) files = files.filter((f: any) => f.gitStatus !== \"??\");\n if (args.limit) files = files.slice(0, args.limit);\n return { files };\n },\n};\n\n// Search then grep\nexport const searchThenGrepTool: BuiltinTool = {\n name: \"searchThenGrep\",\n description: \"Fuzzy search files then grep within. Use as tools.fff.searchThenGrep()\",\n parameters: Type.Object({\n pathQuery: Type.String(),\n contentQuery: Type.String(),\n path: Type.Optional(Type.String()),\n maxFiles: Type.Optional(Type.Number()),\n limit: Type.Optional(Type.Number()),\n }),\n execute: async (_id: string, args: any, cwd: string) => {\n const finder = await getFinder(cwd, args.path);\n const fileRes = finder.fileSearch(args.pathQuery, { pageSize: args.maxFiles || 50 });\n if (!fileRes.ok) throw new Error(fileRes.error);\n if (fileRes.value.items.length === 0) return { matches: [], fileMatches: 0 };\n const paths = fileRes.value.items.map((item: any) => item.relativePath);\n const res = finder.grep(args.contentQuery + \" \" + paths.join(\" \"), { mode: \"plain\" });\n if (!res.ok) throw new Error(res.error);\n const items = args.limit ? res.value.items.slice(0, args.limit) : res.value.items;\n return {\n matches: items.map((m: any) => ({\n path: m.relativePath,\n line: m.lineNumber,\n content: m.lineContent,\n })),\n fileMatches: paths.length,\n totalMatched: res.value.totalMatched,\n };\n },\n};\n\nexport type FffBuiltinToolset = Record;\n\nexport function createFffBuiltinToolset(cwd: string): FffBuiltinToolset {\n const withCwd = (tool: BuiltinTool): BuiltinTool => ({\n ...tool,\n execute: async (_toolCallId: string, args: any, _signal: any, _onUpdate: any) =>\n tool.execute(_toolCallId, args, cwd),\n });\n\n return {\n grep: withCwd(grepTool),\n fileSearch: withCwd(fileSearchTool),\n multiGrep: withCwd(multiGrepTool),\n recentFiles: withCwd(recentFilesTool),\n searchThenGrep: withCwd(searchThenGrepTool),\n };\n}" }, { "path": "agents/pi/extensions/pi-codemode/src/jj-plugin.ts", "content": "import {\n definePlugin,\n ToolRegistration,\n ToolId,\n ToolInvocationResult,\n type PluginContext,\n} from \"@executor-js/sdk\";\nimport { spawn } from \"node:child_process\";\nimport { formatError } from \"./util.js\";\n\nconst run = async (args: string[], cwd: string, signal?: AbortSignal) =>\n await new Promise((resolve, reject) => {\n const child = spawn(\"jj\", args, { cwd, signal, stdio: [\"ignore\", \"pipe\", \"pipe\"] });\n let stdout = \"\";\n let stderr = \"\";\n child.stdout.on(\"data\", (d) => (stdout += d.toString()));\n child.stderr.on(\"data\", (d) => (stderr += d.toString()));\n child.on(\"error\", reject);\n child.on(\"close\", (code) =>\n resolve({ code: code ?? 0, stdout, stderr, command: [\"jj\", ...args] }),\n );\n });\nconst summarize = (r: any) =>\n [\n \"$ \" + r.command.join(\" \"),\n r.stdout?.trim(),\n r.stderr?.trim() ? \"stderr: \" + r.stderr.trim() : \"\",\n \"exit \" + r.code,\n ]\n .filter(Boolean)\n .join(\" \");\nconst text = (s: string) => [{ type: \"text\", text: s }];\n\nexport const jjPlugin = (cwd: string) =>\n definePlugin({\n key: \"jj\",\n init: async (ctx: PluginContext) => {\n const tools = {\n status: {\n description: \"Show jj status\",\n parameters: { type: \"object\", properties: {}, additionalProperties: false },\n execute: async () => {\n const r = await run([\"status\"], cwd);\n return { content: text(summarize(r)), details: { result: r } };\n },\n },\n diff: {\n description: \"Show jj diff\",\n parameters: { type: \"object\", properties: {}, additionalProperties: false },\n execute: async () => {\n const r = await run([\"diff\"], cwd);\n return { content: text(summarize(r)), details: { result: r } };\n },\n },\n log: {\n description: \"Show jj log\",\n parameters: { type: \"object\", properties: {}, additionalProperties: false },\n execute: async () => {\n const r = await run([\"log\"], cwd);\n return { content: text(summarize(r)), details: { result: r } };\n },\n },\n new: {\n description: \"Create a new jj change\",\n parameters: { type: \"object\", properties: {}, additionalProperties: false },\n execute: async () => {\n const r = await run([\"new\"], cwd);\n return { content: text(summarize(r)), details: { result: r } };\n },\n },\n describe: {\n description: \"Describe the current jj change\",\n parameters: {\n type: \"object\",\n properties: { description: { type: \"string\" } },\n required: [\"description\"],\n additionalProperties: false,\n },\n execute: async (_id: string, args: any) => {\n const description = String(args?.description ?? \"\");\n if (!description) throw new Error(\"Missing description\");\n const r = await run([\"describe\", \"-m\", description], cwd);\n return { content: text(summarize(r)), details: { result: r } };\n },\n },\n commit: {\n description: \"Commit with jj\",\n parameters: {\n type: \"object\",\n properties: { message: { type: \"string\" } },\n required: [\"message\"],\n additionalProperties: false,\n },\n execute: async (_id: string, args: any) => {\n const message = String(args?.message ?? \"\");\n if (!message) throw new Error(\"Missing message\");\n const r = await run([\"commit\", \"-m\", message], cwd);\n return { content: text(summarize(r)), details: { result: r } };\n },\n },\n } as const;\n await ctx.tools.registerInvoker(\"jj\", {\n invoke: async (toolId: string, args: unknown) => {\n const name = toolId.split(\".\").pop() as keyof typeof tools | undefined;\n if (!name || !(name in tools))\n return new ToolInvocationResult({ data: null, error: \"Unknown jj tool: \" + toolId });\n try {\n return new ToolInvocationResult({\n data: await tools[name].execute(toolId, args ?? {}),\n error: null,\n });\n } catch (cause) {\n return new ToolInvocationResult({ data: null, error: formatError(cause) });\n }\n },\n });\n await ctx.tools.register(\n Object.entries(tools).map(\n ([name, tool]) =>\n new ToolRegistration({\n id: ToolId.make(\"jj.\" + name),\n pluginKey: \"jj\",\n sourceId: \"pi\",\n name,\n description: tool.description,\n inputSchema: tool.parameters as Record,\n }),\n ),\n );\n return { extension: {} };\n },\n });\n" }, { "path": "agents/pi/extensions/pi-codemode/src/npm-plugin.ts", "content": "import {\n definePlugin,\n ToolRegistration,\n ToolId,\n ToolInvocationResult,\n type PluginContext,\n} from \"@executor-js/sdk\";\nimport { spawn } from \"node:child_process\";\nimport { promises as fs } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { formatError } from \"./util.js\";\n\nconst readMaybe = async (path: string) => {\n try {\n return await fs.readFile(path, \"utf8\");\n } catch {\n return null;\n }\n};\n\nconst pmCache = new Map();\n\nconst detectPackageManager = async (cwd: string) => {\n const cached = pmCache.get(cwd);\n if (cached) return cached;\n\n let result: { bin: string; args: readonly string[] };\n if ((await readMaybe(join(cwd, \"pnpm-lock.yaml\"))) !== null)\n result = { bin: \"pnpm\", args: [\"add\"] as const };\n else if ((await readMaybe(join(cwd, \"bun.lockb\"))) !== null)\n result = { bin: \"bun\", args: [\"add\"] as const };\n else if ((await readMaybe(join(cwd, \"bun.lock\"))) !== null)\n result = { bin: \"bun\", args: [\"add\"] as const };\n else if ((await readMaybe(join(cwd, \"package-lock.json\"))) !== null)\n result = { bin: \"npm\", args: [\"install\"] as const };\n else\n result = { bin: \"npm\", args: [\"install\"] as const };\n\n pmCache.set(cwd, result);\n return result;\n};\n\nconst run = async (cmd: string, args: string[], cwd: string, signal?: AbortSignal) =>\n await new Promise((resolve, reject) => {\n const child = spawn(cmd, args, { cwd, signal, stdio: [\"ignore\", \"pipe\", \"pipe\"] });\n let stdout = \"\";\n let stderr = \"\";\n child.stdout.on(\"data\", (d) => (stdout += d.toString()));\n child.stderr.on(\"data\", (d) => (stderr += d.toString()));\n child.on(\"error\", reject);\n child.on(\"close\", (code) =>\n resolve({ code: code ?? 0, stdout, stderr, command: [cmd, ...args] }),\n );\n });\n\nconst summarize = (r: any) =>\n [\n \"$ \" + r.command.join(\" \"),\n r.stdout?.trim(),\n r.stderr?.trim() ? \"stderr: \" + r.stderr.trim() : \"\",\n \"exit \" + r.code,\n ]\n .filter(Boolean)\n .join(\" \");\nconst text = (s: string) => [{ type: \"text\", text: s }];\n\nexport const npmPlugin = (cwd: string) =>\n definePlugin({\n key: \"npm\",\n init: async (ctx: PluginContext) => {\n const tools = {\n run: {\n description: \"Run npm scripts\",\n parameters: {\n type: \"object\",\n properties: { name: { type: \"string\" } },\n required: [\"name\"],\n additionalProperties: false,\n },\n execute: async (_id: string, args: any) => {\n const name = String(args?.name ?? \"\");\n if (!name) throw new Error(\"Missing script name\");\n const r = await run(\"npm\", [\"run\", name], cwd);\n return { content: text(summarize(r)), details: { result: r } };\n },\n },\n install: {\n description: \"Install packages with lockfile-aware package manager\",\n parameters: {\n type: \"object\",\n properties: { packages: { type: \"array\", items: { type: \"string\" } } },\n required: [\"packages\"],\n additionalProperties: false,\n },\n execute: async (_id: string, args: any) => {\n const packages = Array.isArray(args?.packages)\n ? args.packages.map(String).filter(Boolean)\n : [];\n if (!packages.length) throw new Error(\"Missing packages\");\n const pm = await detectPackageManager(cwd);\n const r = await run(pm.bin, [...pm.args, ...packages], cwd);\n return { content: text(summarize(r)), details: { result: r, packageManager: pm.bin } };\n },\n },\n } as const;\n await ctx.tools.registerInvoker(\"npm\", {\n invoke: async (toolId: string, args: unknown) => {\n const name = toolId.split(\".\").pop() as keyof typeof tools | undefined;\n if (!name || !(name in tools))\n return new ToolInvocationResult({ data: null, error: \"Unknown npm tool: \" + toolId });\n try {\n return new ToolInvocationResult({\n data: await tools[name].execute(toolId, args ?? {}),\n error: null,\n });\n } catch (cause) {\n return new ToolInvocationResult({ data: null, error: formatError(cause) });\n }\n },\n });\n await ctx.tools.register(\n Object.entries(tools).map(\n ([name, tool]) =>\n new ToolRegistration({\n id: ToolId.make(\"npm.\" + name),\n pluginKey: \"npm\",\n sourceId: \"pi\",\n name,\n description: tool.description,\n inputSchema: tool.parameters as Record,\n }),\n ),\n );\n return { extension: {} };\n },\n });" }, { "path": "agents/pi/extensions/pi-codemode/src/pi-plugin.ts", "content": "import {\n definePlugin,\n ToolRegistration,\n ToolId,\n ToolInvocationResult,\n type PluginContext,\n} from \"@executor-js/sdk\";\nimport { createBuiltinToolset } from \"./builtins.js\";\nimport { builtinToolNames, type BuiltinToolName } from \"./types.js\";\nimport { formatError } from \"./util.js\";\n\nexport const piPlugin = (cwd: string) =>\n definePlugin({\n key: \"pi\",\n init: async (ctx: PluginContext) => {\n const tools = createBuiltinToolset(cwd);\n\n await ctx.tools.registerInvoker(\"pi\", {\n invoke: async (toolId: string, args: unknown) => {\n const name = toolId.split(\".\").pop() as BuiltinToolName | undefined;\n if (!name || !(name in tools)) {\n return new ToolInvocationResult({ data: null, error: `Unknown pi tool: ${toolId}` });\n }\n\n const tool = tools[name];\n try {\n const result = await tool.execute(toolId, args ?? {}, undefined, () => {});\n return new ToolInvocationResult({ data: result, error: null });\n } catch (cause) {\n return new ToolInvocationResult({ data: null, error: formatError(cause) });\n }\n },\n });\n\n await ctx.tools.register(\n builtinToolNames.map((name) => {\n const tool = tools[name];\n return new ToolRegistration({\n id: ToolId.make(`pi.${name}`),\n pluginKey: \"pi\",\n sourceId: \"pi\",\n name,\n description: tool.description,\n inputSchema: tool.parameters as Record,\n });\n }),\n );\n\n return { extension: {} };\n },\n });" }, { "path": "agents/pi/extensions/pi-codemode/src/read.ts", "content": "import { access as fsAccess, readFile as fsReadFile } from \"fs/promises\";\nimport { constants } from \"fs\";\nimport { extname } from \"path\";\nimport type { ImageContent, TextContent } from \"@mariozechner/pi-ai\";\nimport { Type } from \"@sinclair/typebox\";\n\n// Much higher defaults than the built-in read tool (2000 lines / 50KB)\nexport const CUSTOM_MAX_LINES = 100_000;\nexport const CUSTOM_MAX_BYTES = 10 * 1024 * 1024; // 10MB\n\nconst IMAGE_MIME_TYPES: Record = {\n \".jpg\": \"image/jpeg\",\n \".jpeg\": \"image/jpeg\",\n \".png\": \"image/png\",\n \".gif\": \"image/gif\",\n \".webp\": \"image/webp\",\n};\n\nfunction isImageFile(filePath: string): string | null {\n const ext = extname(filePath).toLowerCase();\n return IMAGE_MIME_TYPES[ext] || null;\n}\n\nfunction formatSize(bytes: number): string {\n if (bytes < 1024) return `${bytes}B`;\n if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;\n return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;\n}\n\nconst readSchema = Type.Object({\n path: Type.String({ description: \"Path to the file to read (relative or absolute)\" }),\n offset: Type.Optional(\n Type.Number({ description: \"Line number to start reading from (1-indexed)\" }),\n ),\n limit: Type.Optional(Type.Number({ description: \"Maximum number of lines to read\" })),\n});\n\nexport interface ReadToolOptions {\n maxLines?: number;\n maxBytes?: number;\n}\n\nexport function createCustomReadTool(cwd: string, options?: ReadToolOptions) {\n const maxLines = options?.maxLines ?? CUSTOM_MAX_LINES;\n const maxBytes = options?.maxBytes ?? CUSTOM_MAX_BYTES;\n\n return {\n name: \"read\",\n label: \"read\",\n description: `Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to ${maxLines.toLocaleString()} lines or ${formatSize(maxBytes)} (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete.`,\n parameters: readSchema,\n execute: async (\n _toolCallId: string,\n { path, offset, limit }: { path: string; offset?: number; limit?: number },\n signal?: AbortSignal,\n ): Promise<{ content: (TextContent | ImageContent)[] }> => {\n if (signal?.aborted) throw new Error(\"Operation aborted\");\n\n const absolutePath = path.startsWith(\"/\") ? path : `${cwd}/${path}`;\n\n // Check accessibility\n try {\n await fsAccess(absolutePath, constants.R_OK);\n } catch {\n throw new Error(`File not readable: ${path}`);\n }\n\n const mimeType = isImageFile(absolutePath);\n if (mimeType) {\n // Read image as base64\n const buffer = await fsReadFile(absolutePath);\n const base64 = buffer.toString(\"base64\");\n return {\n content: [\n { type: \"text\", text: `Read image file [${mimeType}]` },\n { type: \"image\", data: base64, mimeType },\n ],\n };\n }\n\n // Read text file\n const buffer = await fsReadFile(absolutePath);\n const textContent = buffer.toString(\"utf-8\");\n const allLines = textContent.split(\"\\n\");\n const totalFileLines = allLines.length;\n\n // Apply offset (1-indexed)\n const startLine = offset ? Math.max(0, offset - 1) : 0;\n const startLineDisplay = startLine + 1;\n\n if (startLine >= allLines.length) {\n throw new Error(`Offset ${offset} is beyond end of file (${allLines.length} lines total)`);\n }\n\n // Slice content based on offset/limit\n let selectedLines: string[];\n let userLimitApplied = false;\n\n if (limit !== undefined) {\n const endLine = Math.min(startLine + limit, allLines.length);\n selectedLines = allLines.slice(startLine, endLine);\n userLimitApplied = endLine - startLine < allLines.length - startLine;\n } else {\n selectedLines = allLines.slice(startLine);\n }\n\n // Apply our own truncation (much higher limits)\n const result = truncateHead(selectedLines.join(\"\\n\"), { maxLines, maxBytes });\n\n let outputText: string;\n\n if (result.firstLineExceedsLimit) {\n const firstLineSize = formatSize(Buffer.byteLength(selectedLines[0] || \"\", \"utf-8\"));\n outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(maxBytes)} limit. Use bash: sed -n '${startLineDisplay}p' ${path} | head -c ${maxBytes}]`;\n } else if (result.truncated) {\n const endLineDisplay = startLineDisplay + result.outputLines - 1;\n const nextOffset = endLineDisplay + 1;\n outputText = result.content;\n if (result.truncatedBy === \"lines\") {\n outputText += `\\n\\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue.]`;\n } else {\n outputText += `\\n\\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(maxBytes)} limit). Use offset=${nextOffset} to continue.]`;\n }\n } else if (userLimitApplied) {\n const endLine = startLine + (limit ?? 0);\n const remaining = totalFileLines - endLine;\n const nextOffset = endLine + 1;\n outputText = result.content;\n outputText += `\\n\\n[${remaining} more lines in file. Use offset=${nextOffset} to continue.]`;\n } else {\n outputText = result.content;\n }\n\n return {\n content: [{ type: \"text\", text: outputText }],\n };\n },\n };\n}\n\ninterface TruncationResult {\n content: string;\n truncated: boolean;\n truncatedBy: \"lines\" | \"bytes\" | null;\n outputLines: number;\n firstLineExceedsLimit: boolean;\n}\n\ninterface TruncationOptions {\n maxLines: number;\n maxBytes: number;\n}\n\nfunction truncateHead(content: string, options: TruncationOptions): TruncationResult {\n const { maxLines, maxBytes } = options;\n const totalBytes = Buffer.byteLength(content, \"utf-8\");\n const lines = content.split(\"\\n\");\n const totalLines = lines.length;\n\n if (totalLines <= maxLines && totalBytes <= maxBytes) {\n return {\n content,\n truncated: false,\n truncatedBy: null,\n outputLines: totalLines,\n firstLineExceedsLimit: false,\n };\n }\n\n // Check if first line alone exceeds limit\n const firstLineBytes = Buffer.byteLength(lines[0], \"utf-8\");\n if (firstLineBytes > maxBytes) {\n return {\n content: \"\",\n truncated: true,\n truncatedBy: \"bytes\",\n outputLines: 0,\n firstLineExceedsLimit: true,\n };\n }\n\n const outputLinesArr: string[] = [];\n let outputBytesCount = 0;\n let truncatedBy: \"lines\" | \"bytes\" = \"lines\";\n\n for (let i = 0; i < lines.length && i < maxLines; i++) {\n const line = lines[i];\n const lineBytes = Buffer.byteLength(line, \"utf-8\") + (i > 0 ? 1 : 0);\n if (outputBytesCount + lineBytes > maxBytes) {\n truncatedBy = \"bytes\";\n break;\n }\n outputLinesArr.push(line);\n outputBytesCount += lineBytes;\n }\n\n if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {\n truncatedBy = \"lines\";\n }\n\n return {\n content: outputLinesArr.join(\"\\n\"),\n truncated: true,\n truncatedBy,\n outputLines: outputLinesArr.length,\n firstLineExceedsLimit: false,\n };\n}\n" }, { "path": "agents/pi/extensions/pi-codemode/src/render.ts", "content": "import { Text } from \"@mariozechner/pi-tui\";\nimport type { Theme } from \"@mariozechner/pi-coding-agent\";\nimport type { CodemodeTrace, TraceStep } from \"./types.js\";\n\nconst truncate = (value: string, max: number): string => (value.length <= max ? value : `${value.slice(0, max - 1)}…`);\n\nconst formatDuration = (ms: number): string => {\n if (ms < 1000) return `${ms}ms`;\n return `${(ms / 1000).toFixed(ms < 10_000 ? 1 : 0)}s`;\n};\n\nconst summarizeStep = (step: TraceStep): string => {\n if (step.error) return truncate(step.error, 80);\n if (!step.output?.text) return \"\";\n return truncate(step.output.text.split(/\\r?\\n/)[0] ?? \"\", 80);\n};\n\nexport function renderCodemodeCall(code: string, theme: Theme): Text {\n const lines = code.trim().split(/\\r?\\n/);\n const suffix = lines.length > 1 ? theme.fg(\"muted\", ` (${lines.length} lines)`) : \"\";\n const shown = lines.slice(0, 12).map((line) => theme.fg(\"accent\", line)).join(\"\\n\");\n\n let content = `${theme.fg(\"toolTitle\", theme.bold(\"codemode\"))}${suffix}\\n${shown}`;\n if (lines.length > 12) content += theme.fg(\"muted\", `\\n… (${lines.length - 12} more lines)`);\n\n return new Text(content, 0, 0);\n}\n\nexport function renderCodemodeResult(trace: CodemodeTrace, expanded: boolean, theme: Theme): Text {\n const duration = trace.endedAt ? formatDuration(trace.endedAt - trace.startedAt) : \"running\";\n const isError = trace.status === \"error\" || trace.steps.some((step) => step.status === \"error\");\n const statusColor = isError ? \"error\" : trace.status === \"ok\" ? \"success\" : \"accent\";\n\n if (!expanded) {\n const lines: string[] = [\n `${theme.fg(\"toolTitle\", theme.bold(\"codemode\"))} ${theme.fg(statusColor, trace.status)} ${theme.fg(\"muted\", duration)}`,\n ];\n\n for (const step of trace.steps) {\n const icon = step.status === \"error\" ? \"✗\" : step.status === \"ok\" ? \"✓\" : \"○\";\n const iconColor = step.status === \"error\" ? \"error\" : step.status === \"ok\" ? \"success\" : \"muted\";\n const summary = summarizeStep(step);\n lines.push(`${theme.fg(iconColor, icon)} ${step.label}${summary ? ` — ${theme.fg(\"muted\", summary)}` : \"\"}`);\n }\n\n if (trace.value !== undefined) {\n const value = typeof trace.value === \"string\" ? trace.value : JSON.stringify(trace.value);\n lines.push(`→ ${theme.fg(\"success\", truncate(value, 120))}`);\n }\n\n if (trace.error) lines.push(`→ ${theme.fg(\"error\", truncate(trace.error, 120))}`);\n\n return new Text(lines.join(\"\\n\"), 0, 0);\n }\n\n const lines: string[] = [\n theme.fg(\"toolTitle\", theme.bold(\"codemode execution\")),\n `status: ${theme.fg(statusColor, trace.status)} · ${duration} · ${trace.steps.length} step${trace.steps.length === 1 ? \"\" : \"s\"}`,\n \"\",\n theme.fg(\"muted\", \"// executed code:\"),\n ...trace.code.trim().split(/\\r?\\n/).map((line) => theme.fg(\"accent\", line)),\n ];\n\n if (trace.steps.length > 0) {\n lines.push(\"\", theme.bold(\"steps:\"));\n for (const step of trace.steps) {\n const color = step.status === \"error\" ? \"error\" : step.status === \"ok\" ? \"success\" : \"warning\";\n lines.push(`${theme.fg(color, step.status === \"error\" ? \"✗\" : \"✓\")} ${step.label}`);\n lines.push(theme.fg(\"muted\", ` input: ${truncate(typeof step.input === \"string\" ? step.input : JSON.stringify(step.input), 240)}`));\n if (step.output?.text) {\n for (const line of step.output.text.split(/\\r?\\n/).slice(0, 100)) lines.push(theme.fg(\"toolOutput\", ` ${line}`));\n }\n if (step.error) lines.push(theme.fg(\"error\", ` ${step.error}`));\n }\n }\n\n if (trace.logs.length > 0) {\n lines.push(\"\", theme.bold(`logs (${trace.logs.length}):`));\n for (const log of trace.logs.slice(0, 200)) lines.push(theme.fg(\"muted\", ` ${log}`));\n if (trace.logs.length > 200) lines.push(theme.fg(\"muted\", ` … (${trace.logs.length - 200} more)`));\n }\n\n if (trace.value !== undefined) {\n lines.push(\"\", theme.bold(\"result:\"));\n const value = typeof trace.value === \"string\" ? trace.value : JSON.stringify(trace.value, null, 2);\n for (const line of value.split(/\\r?\\n/).slice(0, 200)) lines.push(theme.fg(\"success\", line));\n }\n\n if (trace.error) {\n lines.push(\"\", theme.bold(\"error:\"), theme.fg(\"error\", trace.error));\n }\n\n return new Text(lines.join(\"\\n\"), 0, 0);\n}" }, { "path": "agents/pi/extensions/pi-codemode/src/runtime.ts", "content": "import type { Executor } from \"@executor-js/sdk\";\nimport { acquireSandbox, type SandboxDelegates } from \"./sandbox-cache.js\";\nimport { CodemodeTraceRecorder } from \"./trace.js\";\nimport type { ImageContent } from \"@mariozechner/pi-ai\";\nimport type { CodemodeTrace, ToolResultSnapshot } from \"./types.js\";\n\nconst DEFAULT_TIMEOUT_MS = 30_000;\nconst MAX_CODE_SIZE = 100_000;\n\ntype RuntimeOptions = {\n code: string;\n cwd: string;\n executor: Executor;\n timeoutMs?: number;\n signal?: AbortSignal;\n onUpdate?: () => void;\n};\n\nexport type CodemodeExecutionResult = {\n value?: unknown;\n trace: CodemodeTrace;\n logs: string[];\n};\n\nconst formatError = (cause: unknown): string => {\n if (cause instanceof Error) {\n const message = cause.message.trim();\n return message.length > 0 ? message : cause.name;\n }\n if (typeof cause === \"string\") return cause;\n if (typeof cause === \"object\" && cause !== null) {\n if (\"message\" in cause && typeof cause.message === \"string\") {\n const message = cause.message.trim();\n if (message.length > 0) return message;\n }\n try {\n return JSON.stringify(cause);\n } catch {\n return String(cause);\n }\n }\n return String(cause);\n};\n\nconst isToolResult = (value: unknown): value is { content: unknown[] } =>\n typeof value === \"object\" &&\n value !== null &&\n \"content\" in value &&\n Array.isArray((value as { content?: unknown[] }).content);\n\nconst extractText = (value: unknown): string => {\n if (typeof value === \"string\") return value;\n if (typeof value === \"undefined\") return \"\";\n if (value === null) return \"null\";\n\n if (isToolResult(value)) {\n return value.content\n .filter(\n (entry): entry is { type?: unknown; text?: unknown } =>\n typeof entry === \"object\" && entry !== null,\n )\n .map((entry) => {\n if (entry.type === \"text\" && typeof entry.text === \"string\") return entry.text;\n return \"\";\n })\n .filter((line) => line.length > 0)\n .join(\" \")\n .trim();\n }\n\n return \"\";\n};\n\nconst extractImages = (value: unknown): ImageContent[] => {\n if (!isToolResult(value)) return [];\n return value.content.filter(\n (entry): entry is ImageContent =>\n typeof entry === \"object\" &&\n entry !== null &&\n (entry as Record).type === \"image\" &&\n typeof (entry as Record).data === \"string\" &&\n typeof (entry as Record).mimeType === \"string\",\n );\n};\n\nconst toSnapshot = (value: unknown, isError = false): ToolResultSnapshot => ({\n value,\n text: extractText(value),\n images: extractImages(value),\n isError,\n});\n\nconst CODE_PREFIX = [\n '\"use strict\";',\n \"\",\n \"const __invokeTool = SecureExec.bindings.invokeTool;\",\n \"const __emitLog = SecureExec.bindings.emitLog;\",\n \"const __emitResult = SecureExec.bindings.emitResult;\",\n 'const __formatArg = (value) => typeof value === \"string\" ? value : JSON.stringify(value);',\n 'const __formatLine = (args) => args.map(__formatArg).join(\" \");',\n \"\",\n \"const __makeToolsProxy = (path = []) => new Proxy(() => undefined, {\",\n \" get(_target, prop) {\",\n ' if (prop === \"then\" || typeof prop === \"symbol\") return undefined;',\n \" return __makeToolsProxy([...path, String(prop)]);\",\n \" },\",\n \" apply(_target, _thisArg, args) {\",\n ' const toolPath = path.join(\".\");',\n ' if (!toolPath) throw new Error(\"Tool path missing in invocation\");',\n \" return Promise.resolve(__invokeTool(toolPath, args[0])).catch((err) => {\",\n ' throw new Error(err?.error || err?.message || \"Tool invocation failed\");',\n \" });\",\n \" },\",\n \"});\",\n \"const tools = __makeToolsProxy();\",\n \"\",\n \"const console = {\",\n ' log: (...args) => __emitLog(\"log\", __formatLine(args)),',\n ' warn: (...args) => __emitLog(\"warn\", __formatLine(args)),',\n ' error: (...args) => __emitLog(\"error\", __formatLine(args)),',\n ' info: (...args) => __emitLog(\"info\", __formatLine(args)),',\n ' debug: (...args) => __emitLog(\"debug\", __formatLine(args)),',\n \"};\",\n \"\",\n \"(async () => {\",\n \"try {\",\n \"const value = await (async () => {\",\n].join(\"\\n\");\n\nconst CODE_POSTFIX = [\n \"})();\",\n \"__emitResult(value);\",\n \"} catch (error) {\",\n 'const message = error && typeof error === \"object\" ? (error.stack || error.message || String(error)) : String(error);',\n 'process.stderr.write(message + \"\\\\n\");',\n \"process.exitCode = 1;\",\n \"}\",\n \"})();\",\n].join(\"\\n\");\n\nconst buildExecutionSource = (code: string): string =>\n CODE_PREFIX + \"\\n\" + code + \"\\n\" + CODE_POSTFIX;\n\nconst invokeExecutorApi = async (\n executor: Executor,\n path: string,\n args: unknown,\n): Promise<{ handled: true; data: unknown } | { handled: false }> => {\n switch (path) {\n case \"list\":\n case \"tools.list\":\n return { handled: true, data: await executor.tools.list(args ?? {}) };\n case \"schema\":\n case \"tools.schema\":\n return { handled: true, data: await executor.tools.schema(String(args)) };\n case \"definitions\":\n case \"tools.definitions\":\n return { handled: true, data: await executor.tools.definitions() };\n\n case \"sources.list\":\n return { handled: true, data: await executor.sources.list() };\n case \"sources.remove\":\n return { handled: true, data: await executor.sources.remove(String(args)) };\n case \"sources.refresh\":\n return { handled: true, data: await executor.sources.refresh(String(args)) };\n case \"sources.detect\":\n return { handled: true, data: await executor.sources.detect(String(args)) };\n\n case \"policies.list\":\n return { handled: true, data: await executor.policies.list() };\n case \"policies.add\":\n return { handled: true, data: await executor.policies.add(args as any) };\n case \"policies.remove\":\n return { handled: true, data: await executor.policies.remove(String(args)) };\n\n case \"secrets.list\":\n return { handled: true, data: await executor.secrets.list() };\n case \"secrets.resolve\":\n return { handled: true, data: await executor.secrets.resolve(String(args)) };\n case \"secrets.status\":\n return { handled: true, data: await executor.secrets.status(String(args)) };\n case \"secrets.set\":\n return { handled: true, data: await executor.secrets.set(args as any) };\n case \"secrets.remove\":\n return { handled: true, data: await executor.secrets.remove(String(args)) };\n case \"secrets.addProvider\":\n return { handled: true, data: await executor.secrets.addProvider(args as any) };\n case \"secrets.providers\":\n return { handled: true, data: await executor.secrets.providers() };\n\n default:\n return { handled: false };\n }\n};\n\n// --- Tool invocation bridge (host side) ---\n// Uses structured clone via secure-exec bindings — no JSON serialization.\n\nconst createInvokeTool =\n (executor: Executor, recorder: CodemodeTraceRecorder, onStep?: () => void) =>\n async (path: unknown, args: unknown): Promise => {\n const toolPath = String(path);\n const step = recorder.startStep({ label: `tools.${toolPath}`, toolPath, input: args });\n\n try {\n const direct = await invokeExecutorApi(executor, toolPath, args);\n let data: unknown;\n\n if (direct.handled) {\n data = direct.data;\n } else {\n const invoked = await executor.tools.invoke(toolPath, args, {\n onElicitation: \"accept-all\",\n });\n if (invoked.error != null) {\n const message = formatError(invoked.error);\n recorder.finishStep(step, undefined, message);\n onStep?.();\n throw { error: message };\n }\n data = invoked.data;\n }\n\n const snapshot = toSnapshot(data);\n recorder.finishStep(step, snapshot);\n onStep?.();\n\n // pi and fff tools return ToolResult objects ({ content: [...] }) — extract text\n // for backwards compat. Other tools (MCP, OpenAPI, GraphQL) return objects as-is.\n if ((toolPath.startsWith(\"pi.\") || toolPath.startsWith(\"fff.\")) && isToolResult(data)) {\n return extractText(data);\n }\n return data;\n } catch (cause) {\n const message = formatError(cause);\n recorder.finishStep(step, undefined, message);\n onStep?.();\n throw { error: message };\n }\n };\n\n// --- Sequential per-cwd execution queue ---\n\nconst executionQueues = new Map>();\n\nexport const runCodemode = async (options: RuntimeOptions): Promise => {\n const key = options.cwd;\n const prev = executionQueues.get(key);\n const next = (async (): Promise => {\n if (prev) {\n try {\n await prev;\n } catch {\n /* ignore previous execution errors */\n }\n }\n return _runCodemode(options);\n })();\n executionQueues.set(key, next);\n try {\n return await next;\n } finally {\n if (executionQueues.get(key) === next) {\n executionQueues.delete(key);\n }\n }\n};\n\n// --- Core execution ---\n\nconst noopDelegates: SandboxDelegates = {\n invokeTool: async () => undefined,\n emitLog: () => { },\n emitResult: () => {},\n};\n\nconst _runCodemode = async (options: RuntimeOptions): Promise => {\n const code = options.code;\n const timeoutMs = Math.max(100, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);\n const recorder = new CodemodeTraceRecorder({ cwd: options.cwd, code });\n const logs: string[] = [];\n\n if (code.length > MAX_CODE_SIZE) {\n const message = `Code exceeds ${MAX_CODE_SIZE} bytes`;\n const trace = recorder.finish({ status: \"error\", error: message });\n return { trace, logs };\n }\n\n const sandbox = await acquireSandbox(options.cwd);\n\n // Wire up delegates for this execution\n sandbox.delegates.invokeTool = createInvokeTool(options.executor, recorder, options.onUpdate);\n sandbox.delegates.emitResult = (value: unknown) => {\n capturedResult = value;\n };\n sandbox.delegates.emitLog = (level: unknown, line: unknown) => {\n const entry = `[${String(level)}] ${String(line)}`;\n logs.push(entry);\n recorder.log(entry);\n };\n\n let capturedResult: unknown = undefined;\n\n try {\n let aborted = false;\n let timedOut = false;\n\n const source = buildExecutionSource(code);\n\n const stdoutDecoder = new TextDecoder();\n const stderrDecoder = new TextDecoder();\n let stdout = \"\";\n let stderr = \"\";\n\n const proc = sandbox.kernel.spawn(\"node\", [\"-e\", source], {\n cwd: options.cwd,\n onStdout: (data) => {\n stdout += stdoutDecoder.decode(data, { stream: true });\n },\n onStderr: (data) => {\n stderr += stderrDecoder.decode(data, { stream: true });\n },\n });\n\n const timeoutId = setTimeout(() => {\n timedOut = true;\n proc.kill(9);\n }, timeoutMs);\n\n let abortHandler: (() => void) | undefined;\n if (options.signal) {\n abortHandler = () => {\n aborted = true;\n proc.kill(9);\n };\n if (options.signal.aborted) abortHandler();\n else options.signal.addEventListener(\"abort\", abortHandler, { once: true });\n }\n\n let exitCode: number;\n try {\n exitCode = await proc.wait();\n } finally {\n clearTimeout(timeoutId);\n if (options.signal && abortHandler) options.signal.removeEventListener(\"abort\", abortHandler);\n stdout += stdoutDecoder.decode();\n stderr += stderrDecoder.decode();\n }\n\n const value = capturedResult;\n\n if (timedOut) {\n const trace = recorder.finish({\n status: \"error\",\n error: `Execution timed out after ${timeoutMs}ms`,\n });\n return { trace, logs };\n }\n\n if (aborted || options.signal?.aborted) {\n const trace = recorder.finish({ status: \"aborted\", value, error: \"Execution aborted\" });\n return { value, trace, logs };\n }\n\n if (exitCode !== 0) {\n const adjustedStderr = stderr.trim();\n const error = adjustedStderr || stdout.trim() || `Process exited with code ${exitCode}`;\n const trace = recorder.finish({ status: \"error\", value, error });\n return { value, trace, logs };\n }\n\n const trace = recorder.finish({ status: \"ok\", value });\n return { value, trace, logs };\n } catch (cause) {\n const message = formatError(cause);\n const trace = recorder.finish({\n status: options.signal?.aborted ? \"aborted\" : \"error\",\n error: message,\n });\n return { trace, logs };\n } finally {\n // Reset delegates to no-ops so next execution starts clean\n sandbox.delegates.invokeTool = noopDelegates.invokeTool;\n sandbox.delegates.emitLog = noopDelegates.emitLog;\n sandbox.delegates.emitResult = noopDelegates.emitResult;\n }\n};\n" }, { "path": "agents/pi/extensions/pi-codemode/src/sandbox-cache.ts", "content": "import { createInMemoryFileSystem, createKernel, createNodeRuntime, type Kernel } from \"secure-exec\";\n\n// Bound once into secure-exec. Mutable delegates allow per-execution handler swap\n// without recreating the kernel.\nexport type SandboxDelegates = {\n invokeTool: (path: unknown, args: unknown) => Promise;\n emitLog: (level: unknown, line: unknown) => void;\n emitResult: (value: unknown) => void;\n};\n\nexport type SandboxEntry = {\n kernel: Kernel;\n delegates: SandboxDelegates;\n};\n\nconst noopDelegates: SandboxDelegates = {\n invokeTool: async () => undefined,\n emitLog: () => {},\n emitResult: () => {},\n};\n\nconst cache = new Map();\n\nexport const acquireSandbox = async (cwd: string): Promise => {\n const existing = cache.get(cwd);\n if (existing) return existing;\n\n const delegates: SandboxDelegates = { ...noopDelegates };\n\n // Fixed bindings that forward through mutable delegates\n const bindings = {\n invokeTool: (path: unknown, args: unknown) => delegates.invokeTool(path, args),\n emitLog: (level: unknown, line: unknown) => delegates.emitLog(level, line),\n emitResult: (value: unknown) => delegates.emitResult(value),\n };\n\n const kernel = createKernel({ filesystem: createInMemoryFileSystem(), cwd });\n await kernel.mount(createNodeRuntime({ bindings }));\n\n const entry: SandboxEntry = { kernel, delegates };\n cache.set(cwd, entry);\n return entry;\n};\n\nexport const disposeAll = async (): Promise => {\n await Promise.allSettled(\n Array.from(cache.values()).map((entry) => entry.kernel.dispose()),\n );\n cache.clear();\n};" }, { "path": "agents/pi/extensions/pi-codemode/src/source-config.ts", "content": "import { readFile, stat } from \"node:fs/promises\";\nimport { homedir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { parse, printParseErrorCode, type ParseError } from \"jsonc-parser\";\n\nconst SECRET_REF_PREFIX = \"secret-public-ref:\";\n\ntype UnknownRecord = Record;\n\ntype HeaderSecretRef = { secretId: string; prefix?: string };\ntype PluginHeaderValue = string | HeaderSecretRef;\n\nexport type OpenApiSourceConfig = {\n kind: \"openapi\";\n spec: string;\n baseUrl?: string;\n namespace?: string;\n headers?: Record;\n};\n\nexport type GraphqlSourceConfig = {\n kind: \"graphql\";\n endpoint: string;\n introspectionJson?: string;\n namespace?: string;\n headers?: Record;\n};\n\nexport type McpRemoteSourceConfig = {\n kind: \"mcp\";\n transport: \"remote\";\n name: string;\n endpoint: string;\n remoteTransport?: \"streamable-http\" | \"sse\" | \"auto\";\n namespace?: string;\n queryParams?: Record;\n headers?: Record;\n};\n\nexport type McpStdioSourceConfig = {\n kind: \"mcp\";\n transport: \"stdio\";\n name: string;\n command: string;\n args?: string[];\n env?: Record;\n cwd?: string;\n namespace?: string;\n};\n\nexport type SupportedSourceConfig =\n | OpenApiSourceConfig\n | GraphqlSourceConfig\n | McpRemoteSourceConfig\n | McpStdioSourceConfig;\n\nexport type UnsupportedSourceConfig = {\n index: number;\n reason: string;\n value: unknown;\n kind?: string;\n};\n\nexport type LoadedSourceConfig = {\n configPath: string;\n mtimeMs: number;\n sources: SupportedSourceConfig[];\n unsupported: UnsupportedSourceConfig[];\n};\n\nconst isRecord = (value: unknown): value is UnknownRecord =>\n typeof value === \"object\" && value !== null && !Array.isArray(value);\n\nconst parseStringMap = (value: unknown): Record | null => {\n if (!isRecord(value)) return null;\n const output: Record = {};\n for (const [key, item] of Object.entries(value)) {\n if (typeof item !== \"string\") return null;\n output[key] = item;\n }\n return output;\n};\n\nconst parseStringArray = (value: unknown): string[] | null => {\n if (!Array.isArray(value)) return null;\n if (value.some((item) => typeof item !== \"string\")) return null;\n return [...value] as string[];\n};\n\nconst parseHeaderValue = (value: unknown): PluginHeaderValue | null => {\n if (typeof value === \"string\") {\n if (value?.startsWith(SECRET_REF_PREFIX)) {\n return { secretId: value.slice(SECRET_REF_PREFIX.length) };\n }\n return value;\n }\n\n if (!isRecord(value) || typeof value.value !== \"string\") return null;\n\n const prefix = typeof value.prefix === \"string\" ? value.prefix : undefined;\n const raw = value.value;\n\n if (raw?.startsWith(SECRET_REF_PREFIX)) {\n const secretId = raw.slice(SECRET_REF_PREFIX.length);\n return prefix ? { secretId, prefix } : { secretId };\n }\n\n return prefix ? prefix + raw : raw;\n};\n\nconst parseHeaderMap = (value: unknown): Record | null => {\n if (!isRecord(value)) return null;\n const output: Record = {};\n for (const [key, item] of Object.entries(value)) {\n const parsed = parseHeaderValue(item);\n if (parsed == null) return null;\n output[key] = parsed;\n }\n return output;\n};\n\nconst parseMcpSource = (entry: UnknownRecord): { source?: SupportedSourceConfig; reason?: string } => {\n const transport = entry.transport;\n if (transport !== \"remote\" && transport !== \"stdio\") {\n return { reason: \"mcp.transport must be \\\"remote\\\" or \\\"stdio\\\"\" };\n }\n\n if (typeof entry.name !== \"string\" || entry.name.trim().length === 0) {\n return { reason: \"mcp.name must be a non-empty string\" };\n }\n\n if (entry.namespace !== undefined && typeof entry.namespace !== \"string\") {\n return { reason: \"mcp.namespace must be a string\" };\n }\n\n if (transport === \"remote\") {\n if (typeof entry.endpoint !== \"string\" || entry.endpoint.trim().length === 0) {\n return { reason: \"mcp(remote).endpoint must be a non-empty string\" };\n }\n\n if (\n entry.remoteTransport !== undefined &&\n entry.remoteTransport !== \"streamable-http\" &&\n entry.remoteTransport !== \"sse\" &&\n entry.remoteTransport !== \"auto\"\n ) {\n return { reason: \"mcp(remote).remoteTransport must be streamable-http|sse|auto\" };\n }\n\n if (entry.queryParams !== undefined && parseStringMap(entry.queryParams) == null) {\n return { reason: \"mcp(remote).queryParams must be a string map\" };\n }\n\n if (entry.headers !== undefined && parseStringMap(entry.headers) == null) {\n return { reason: \"mcp(remote).headers must be a string map\" };\n }\n\n return {\n source: {\n kind: \"mcp\",\n transport: \"remote\",\n name: entry.name,\n endpoint: entry.endpoint,\n remoteTransport: entry.remoteTransport,\n namespace: entry.namespace,\n queryParams: entry.queryParams as Record | undefined,\n headers: entry.headers as Record | undefined,\n },\n };\n }\n\n if (typeof entry.command !== \"string\" || entry.command.trim().length === 0) {\n return { reason: \"mcp(stdio).command must be a non-empty string\" };\n }\n\n if (entry.args !== undefined && parseStringArray(entry.args) == null) {\n return { reason: \"mcp(stdio).args must be a string array\" };\n }\n\n if (entry.env !== undefined && parseStringMap(entry.env) == null) {\n return { reason: \"mcp(stdio).env must be a string map\" };\n }\n\n if (entry.cwd !== undefined && typeof entry.cwd !== \"string\") {\n return { reason: \"mcp(stdio).cwd must be a string\" };\n }\n\n return {\n source: {\n kind: \"mcp\",\n transport: \"stdio\",\n name: entry.name,\n command: entry.command,\n args: entry.args as string[] | undefined,\n env: entry.env as Record | undefined,\n cwd: entry.cwd as string | undefined,\n namespace: entry.namespace,\n },\n };\n};\n\nconst parseOpenApiSource = (entry: UnknownRecord): { source?: SupportedSourceConfig; reason?: string } => {\n if (typeof entry.spec !== \"string\" || entry.spec.trim().length === 0) {\n return { reason: \"openapi.spec must be a non-empty string\" };\n }\n\n if (entry.baseUrl !== undefined && typeof entry.baseUrl !== \"string\") {\n return { reason: \"openapi.baseUrl must be a string\" };\n }\n\n if (entry.namespace !== undefined && typeof entry.namespace !== \"string\") {\n return { reason: \"openapi.namespace must be a string\" };\n }\n\n const headers = entry.headers === undefined ? undefined : parseHeaderMap(entry.headers);\n if (entry.headers !== undefined && headers == null) {\n return { reason: \"openapi.headers must map to string or secret refs\" };\n }\n\n return {\n source: {\n kind: \"openapi\",\n spec: entry.spec,\n baseUrl: entry.baseUrl as string | undefined,\n namespace: entry.namespace as string | undefined,\n headers: headers ?? undefined,\n },\n };\n};\n\nconst parseGraphqlSource = (entry: UnknownRecord): { source?: SupportedSourceConfig; reason?: string } => {\n if (typeof entry.endpoint !== \"string\" || entry.endpoint.trim().length === 0) {\n return { reason: \"graphql.endpoint must be a non-empty string\" };\n }\n\n if (entry.introspectionJson !== undefined && typeof entry.introspectionJson !== \"string\") {\n return { reason: \"graphql.introspectionJson must be a string\" };\n }\n\n if (entry.namespace !== undefined && typeof entry.namespace !== \"string\") {\n return { reason: \"graphql.namespace must be a string\" };\n }\n\n const headers = entry.headers === undefined ? undefined : parseHeaderMap(entry.headers);\n if (entry.headers !== undefined && headers == null) {\n return { reason: \"graphql.headers must map to string or secret refs\" };\n }\n\n return {\n source: {\n kind: \"graphql\",\n endpoint: entry.endpoint,\n introspectionJson: entry.introspectionJson as string | undefined,\n namespace: entry.namespace as string | undefined,\n headers: headers ?? undefined,\n },\n };\n};\n\nconst parseErrorsToMessage = (errors: ParseError[]): string =>\n errors.map((error) => \"offset \" + error.offset + \": \" + printParseErrorCode(error.error)).join(\"; \");\n\nexport const getExecutorConfigPath = (): string => join(homedir(), \".pi\", \"agent\", \"executor.jsonc\");\n\nexport const loadSourcesFromConfig = async (): Promise => {\n const configPath = getExecutorConfigPath();\n\n let raw: string;\n let mtimeMs: number;\n try {\n mtimeMs = (await stat(configPath)).mtimeMs;\n raw = await readFile(configPath, \"utf8\");\n } catch (cause) {\n const error = cause as NodeJS.ErrnoException;\n if (error?.code === \"ENOENT\") {\n return {\n configPath,\n mtimeMs: 0,\n sources: [],\n unsupported: [],\n };\n }\n throw new Error(\"Failed reading \" + configPath + \": \" + (error?.message ?? String(cause)));\n }\n\n const parseErrors: ParseError[] = [];\n const parsed = parse(raw, parseErrors);\n if (parseErrors.length > 0) {\n throw new Error(\"Invalid JSONC in \" + configPath + \": \" + parseErrorsToMessage(parseErrors));\n }\n\n if (!isRecord(parsed)) {\n throw new Error(\"Invalid config at \" + configPath + \": root must be an object\");\n }\n\n const rawSources = parsed.sources;\n\n if (rawSources === undefined) {\n return { configPath, mtimeMs, sources: [], unsupported: [] };\n }\n\n if (!Array.isArray(rawSources)) {\n throw new Error(\"Invalid config at \" + configPath + \": \\\"sources\\\" must be an array\");\n }\n\n const sources: SupportedSourceConfig[] = [];\n const unsupported: UnsupportedSourceConfig[] = [];\n\n for (let index = 0; index < rawSources.length; index++) {\n const rawSource = rawSources[index];\n if (!isRecord(rawSource)) {\n unsupported.push({ index, reason: \"source entry must be an object\", value: rawSource });\n continue;\n }\n\n const kind = typeof rawSource.kind === \"string\" ? rawSource.kind : undefined;\n\n if (kind === \"mcp\") {\n const parsedSource = parseMcpSource(rawSource);\n if (!parsedSource.source) {\n unsupported.push({ index, kind, reason: parsedSource.reason ?? \"invalid mcp source\", value: rawSource });\n continue;\n }\n sources.push(parsedSource.source);\n continue;\n }\n\n if (kind === \"openapi\") {\n const parsedSource = parseOpenApiSource(rawSource);\n if (!parsedSource.source) {\n unsupported.push({ index, kind, reason: parsedSource.reason ?? \"invalid openapi source\", value: rawSource });\n continue;\n }\n sources.push(parsedSource.source);\n continue;\n }\n\n if (kind === \"graphql\") {\n const parsedSource = parseGraphqlSource(rawSource);\n if (!parsedSource.source) {\n unsupported.push({ index, kind, reason: parsedSource.reason ?? \"invalid graphql source\", value: rawSource });\n continue;\n }\n sources.push(parsedSource.source);\n continue;\n }\n\n unsupported.push({\n index,\n kind,\n reason: kind ? \"unsupported source kind: \" + kind : \"source.kind is required\",\n value: rawSource,\n });\n }\n\n return { configPath, mtimeMs, sources, unsupported };\n};" }, { "path": "agents/pi/extensions/pi-codemode/src/source-hydrate.ts", "content": "import type { Executor } from \"@executor-js/sdk\";\nimport type { SupportedSourceConfig, UnsupportedSourceConfig } from \"./source-config.js\";\n\ntype ExecutorWithPlugins = Executor & {\n mcp?: { addSource: (source: unknown) => Promise };\n openapi?: { addSpec: (source: unknown) => Promise };\n graphql?: { addSource: (source: unknown) => Promise };\n};\n\ntype HydrateOptions = {\n configPath: string;\n unsupported: UnsupportedSourceConfig[];\n};\n\nconst sourceKey = (source: SupportedSourceConfig): string => {\n if (source.namespace) return source.kind + \":\" + source.namespace;\n\n if (source.kind === \"mcp\") {\n if (source.transport === \"remote\") return \"mcp:remote:\" + source.endpoint;\n return \"mcp:stdio:\" + source.command + \":\" + (source.args ?? []).join(\"\\u0000\") + \":\" + (source.cwd ?? \"\");\n }\n\n if (source.kind === \"openapi\") return \"openapi:\" + source.spec;\n return \"graphql:\" + source.endpoint;\n};\n\nconst summarize = (source: SupportedSourceConfig): string => {\n if (source.namespace) return source.kind + \":\" + source.namespace;\n if (source.kind === \"mcp\") return source.transport === \"remote\" ? \"mcp:\" + source.endpoint : \"mcp:\" + source.command;\n if (source.kind === \"openapi\") return \"openapi:\" + source.spec;\n return \"graphql:\" + source.endpoint;\n};\n\nexport const hydrateExecutorSources = async (\n executor: Executor,\n sources: SupportedSourceConfig[],\n options: HydrateOptions,\n): Promise => {\n if (options.unsupported.length > 0) {\n for (const entry of options.unsupported) {\n console.warn(\n \"[codemode] Skipping unsupported source in \" +\n options.configPath +\n \" (#\" +\n entry.index +\n \"): \" +\n entry.reason,\n );\n }\n }\n\n if (sources.length === 0) return;\n\n const ext = executor as ExecutorWithPlugins;\n const existing = await executor.sources.list();\n const existingIds = new Set(existing.map((source: { id: string }) => source.id));\n const seen = new Set();\n\n for (const source of sources) {\n const key = sourceKey(source);\n if (seen.has(key)) continue;\n seen.add(key);\n\n if (source.namespace && existingIds.has(source.namespace)) continue;\n\n if (source.kind === \"mcp\") {\n if (!ext.mcp?.addSource) {\n throw new Error(\"Missing MCP plugin while hydrating \" + summarize(source) + \" from \" + options.configPath);\n }\n await ext.mcp.addSource(source);\n continue;\n }\n\n if (source.kind === \"openapi\") {\n if (!ext.openapi?.addSpec) {\n throw new Error(\"Missing OpenAPI plugin while hydrating \" + summarize(source) + \" from \" + options.configPath);\n }\n await ext.openapi.addSpec(source);\n continue;\n }\n\n if (!ext.graphql?.addSource) {\n throw new Error(\"Missing GraphQL plugin while hydrating \" + summarize(source) + \" from \" + options.configPath);\n }\n await ext.graphql.addSource(source);\n }\n};\n" }, { "path": "agents/pi/extensions/pi-codemode/src/trace.ts", "content": "import type { ImageContent } from \"@mariozechner/pi-ai\";\nimport type { CodemodeTrace, ToolResultSnapshot, TraceStep } from \"./types.js\";\n\nconst clone = (value: T): T => {\n if (typeof structuredClone === \"function\") return structuredClone(value);\n return JSON.parse(JSON.stringify(value)) as T;\n};\n\nconst formatDuration = (ms: number): string => {\n if (ms < 1000) return `${ms}ms`;\n return `${(ms / 1000).toFixed(ms < 10_000 ? 1 : 0)}s`;\n};\n\nconst summarizeText = (text: string, max = 140): string => {\n const first = text.split(/\\r?\\n/).find((line) => line.trim().length > 0) ?? \"\";\n if (first.length <= max) return first;\n return `${first.slice(0, max - 1)}…`;\n};\n\nconst summarizeValue = (value: unknown): string => {\n if (value === undefined) return \"undefined\";\n if (value === null) return \"null\";\n if (typeof value === \"string\") return JSON.stringify(value.length > 80 ? `${value.slice(0, 77)}…` : value);\n if (typeof value === \"number\" || typeof value === \"boolean\") return String(value);\n if (Array.isArray(value)) return `[${value.length} items]`;\n if (typeof value === \"object\") return `{${Object.keys(value as Record).slice(0, 4).join(\", \")}}`;\n return String(value);\n};\n\nexport class CodemodeTraceRecorder {\n private readonly trace: CodemodeTrace;\n private readonly steps = new Map();\n private id = 0;\n\n constructor(input: { cwd: string; code: string }) {\n this.trace = {\n cwd: input.cwd,\n code: input.code,\n startedAt: Date.now(),\n status: \"running\",\n logs: [],\n steps: [],\n };\n }\n\n log(line: string): void {\n this.trace.logs.push(line);\n }\n\n startStep(input: { label: string; toolPath: string; input: unknown }): string {\n const id = `step_${++this.id}`;\n const step: TraceStep = {\n id,\n label: input.label,\n toolPath: input.toolPath,\n input: clone(input.input),\n startedAt: Date.now(),\n status: \"running\",\n };\n this.steps.set(id, step);\n this.trace.steps.push(step);\n return id;\n }\n\n finishStep(id: string, output?: ToolResultSnapshot, error?: string): void {\n const step = this.steps.get(id);\n if (!step) return;\n step.endedAt = Date.now();\n\n if (error) {\n step.status = \"error\";\n step.error = error;\n return;\n }\n\n if (output) {\n step.output = clone(output);\n step.status = output.isError ? \"error\" : \"ok\";\n if (output.isError) step.error = output.text;\n return;\n }\n\n step.status = \"ok\";\n }\n\n finish(input: { status: CodemodeTrace[\"status\"]; value?: unknown; error?: string }): CodemodeTrace {\n this.trace.endedAt = Date.now();\n this.trace.status = input.status;\n this.trace.value = input.value;\n this.trace.error = input.error;\n return clone(this.trace);\n }\n}\n\nexport const summarizeTraceForContext = (trace: CodemodeTrace): string => {\n const duration = trace.endedAt ? formatDuration(trace.endedAt - trace.startedAt) : undefined;\n const errors = trace.steps.filter((s) => s.status === \"error\").length;\n\n return [\n `codemode ${trace.status}`,\n duration,\n `${trace.steps.length} step${trace.steps.length === 1 ? \"\" : \"s\"}`,\n errors > 0 ? `${errors} err` : undefined,\n trace.logs.length > 0 ? `${trace.logs.length} log${trace.logs.length === 1 ? \"\" : \"s\"}` : undefined,\n trace.value !== undefined ? `value=${summarizeValue(trace.value)}` : undefined,\n trace.error ? `error=${summarizeText(trace.error, 120)}` : undefined,\n ]\n .filter((v): v is string => Boolean(v))\n .join(\" · \");\n};\n\nexport const formatTraceForAgent = (trace: CodemodeTrace, value: unknown, logs: string[]): { text: string; images: ImageContent[] } => {\n const durationMs = trace.endedAt ? trace.endedAt - trace.startedAt : 0;\n const duration = formatDuration(durationMs);\n\n const result: string[] = [`status:${trace.status} duration:${duration}`];\n\n if (trace.steps.length > 0) {\n result.push(\"\", \"steps:\");\n for (const step of trace.steps) {\n const stepDuration = step.endedAt ? formatDuration(step.endedAt - step.startedAt) : \"\";\n const prefix = step.status === \"error\" ? \"[ERR]\" : step.status === \"ok\" ? \"[OK]\" : \"[...]\";\n result.push(`${prefix} ${step.label} ${stepDuration}`);\n if (step.error) {\n result.push(` error: ${step.error}`);\n } else if (step.output?.text) {\n const lines = step.output.text.split(/\\r?\\n/).filter((l) => l.trim().length > 0);\n const preview = lines.slice(0, 8).join(\"\\n \");\n result.push(` output: ${preview}${lines.length > 8 ? `\\n ... (${lines.length - 8} more lines)` : \"\"}`);\n }\n }\n }\n\n if (trace.error) {\n result.push(\"\", `execution error: ${trace.error}`);\n }\n\n if (value !== undefined) {\n const raw = typeof value === \"string\" ? value : JSON.stringify(value);\n result.push(\"\", `return value: ${raw}`);\n }\n\n if (logs.length > 0) {\n result.push(\"\", \"logs:\");\n for (const log of logs) {\n result.push(log.replace(/^\\[\\w+\\] /, \"\"));\n }\n }\n\n const images = trace.steps.flatMap((s) => s.output?.images ?? []);\n\n return { text: result.join(\"\\n\"), images };\n};\n" }, { "path": "agents/pi/extensions/pi-codemode/src/turndown.d.ts", "content": "declare module \"turndown\" {\n export default class TurndownService {\n turndown(html: string): string;\n }\n}\n" }, { "path": "agents/pi/extensions/pi-codemode/src/types.ts", "content": "import type { ImageContent } from \"@mariozechner/pi-ai\";\n\nexport const builtinToolNames = [\"read\", \"bash\", \"edit\", \"write\", \"grep\", \"find\", \"ls\", \"webfetch\"] as const;\nexport type BuiltinToolName = (typeof builtinToolNames)[number];\n\nexport const fffToolNames = [\n \"grep\",\n \"fileSearch\",\n \"multiGrep\",\n \"recentFiles\",\n \"searchThenGrep\",\n] as const;\nexport type FffToolName = (typeof fffToolNames)[number];\n\nexport type ToolResultSnapshot = {\n value: unknown;\n text: string;\n images?: ImageContent[];\n isError: boolean;\n};\n\nexport type TraceStep = {\n id: string;\n label: string;\n toolPath: string;\n input: unknown;\n startedAt: number;\n endedAt?: number;\n status: \"running\" | \"ok\" | \"error\";\n output?: ToolResultSnapshot;\n error?: string;\n};\n\nexport type CodemodeTrace = {\n cwd: string;\n code: string;\n startedAt: number;\n endedAt?: number;\n status: \"running\" | \"ok\" | \"error\" | \"aborted\";\n value?: unknown;\n logs: string[];\n steps: TraceStep[];\n error?: string;\n};\n\nexport type CodemodeResultDetails = {\n trace: CodemodeTrace;\n value?: unknown;\n logs: string[];\n summary: string;\n};" }, { "path": "agents/pi/extensions/pi-codemode/src/util.ts", "content": "export const stripCodeFences = (code: string): string => {\n const trimmed = code.trim();\n const match = trimmed.match(/^(```|~~~)(?:\\w+)?\\r?\\n([\\s\\S]+)\\r?\\n\\1$/);\n if (match) return match[2].trim();\n return trimmed;\n};\n\nexport const buildPromptGuidelines = () => [\n \"Write plain JavaScript body only. No imports/exports. No markdown fences\",\n \"Use things from tools.* namespace to access tools\",\n \"Only do filesystem related operations using tools.pi.*\",\n \"Never rely on bash if it can be done in JavaScript\",\n \"Batch related work in one codemode call\",\n \"Prefer tools.pi.read over shell commands: read({ offset, limit }) gives line ranges\",\n \"Prefer tools.pi.grep over grep: it returns structured results with line numbers\",\n \"Output visibility: use `return value` to show output visibly, use `console.log(value)` for logs. Bare expressions like `result;` or string tricks like `'' + result` are silently swallowed.\",\n \"Bash is available for package managers (npm, pnpm, bun, yarn, npx, node), file operations (mkdir, cp, mv, rm, ln, chmod), and utilities (pwd, echo, which, uname, date). Use tools.pi.* for reading/writing/searching/grepping/editing files.\",\n];\n\nexport const formatError = (cause: unknown): string => {\n if (cause instanceof Error) return cause.message || cause.name;\n if (typeof cause === \"string\") return cause;\n try {\n return JSON.stringify(cause);\n } catch {\n return String(cause);\n }\n};" }, { "path": "agents/pi/extensions/pi-codemode/src/webfetch.ts", "content": "import TurndownService from \"turndown\";\n\nexport type WebfetchInput = {\n url: string;\n format?: \"markdown\" | \"text\" | \"html\";\n timeout?: number;\n};\n\nconst MAX_RESPONSE_SIZE = 5 * 1024 * 1024;\nconst DEFAULT_TIMEOUT = 30 * 1000;\nconst MAX_TIMEOUT = 120 * 1000;\n\nconst turndownService = new TurndownService();\n\n// Simple HTML to text conversion\nfunction htmlToText(html: string): string {\n return (\n html\n .replace(/]*>[\\s\\S]*?<\\/script>/gi, \"\")\n .replace(/]*>[\\s\\S]*?<\\/style>/gi, \"\")\n .replace(/<\\/p>/gi, \"\\n\\n\")\n .replace(//gi, \"\\n\")\n .replace(/<\\/div>/gi, \"\\n\")\n .replace(/<\\/h[1-6]>/gi, \"\\n\\n\")\n .replace(/<\\/li>/gi, \"\\n\")\n .replace(/<[^>]+>/g, \"\")\n .replace(/ /g, \" \")\n .replace(/&/g, \"&\")\n .replace(/</g, \"<\")\n .replace(/>/g, \">\")\n .replace(/"/g, '\"')\n .replace(/'/g, \"'\")\n .replace(/\\n{3,}/g, \"\\n\\n\")\n .trim()\n );\n}\n\nfunction htmlToMarkdown(html: string): string {\n try {\n return turndownService.turndown(html);\n } catch {\n return htmlToText(html);\n }\n}\n\nexport async function webfetch(\n _toolId: string,\n args: WebfetchInput,\n _signal: AbortSignal | undefined,\n _onUpdate: () => void,\n): Promise<{ content: Array<{ type: \"text\"; text: string }>; details?: Record }> {\n const format = args.format ?? \"markdown\";\n let url = args.url;\n\n if (url.startsWith(\"http://\")) {\n try {\n const parsed = new URL(url);\n const isLocalhost = parsed.hostname === \"localhost\" || parsed.hostname === \"127.0.0.1\" || parsed.hostname === \"::1\";\n if (!isLocalhost) {\n url = url.replace(\"http://\", \"https://\");\n }\n } catch {\n return {\n content: [{ type: \"text\", text: \"\" }],\n details: { url: args.url, format, error: \"Invalid URL\" },\n };\n }\n }\n if (!url.startsWith(\"https://\")) {\n return {\n content: [{ type: \"text\", text: \"\" }],\n details: { url: args.url, format, error: \"Invalid URL\" },\n };\n }\n\n const timeout = Math.min((args.timeout ?? DEFAULT_TIMEOUT / 1000) * 1000, MAX_TIMEOUT);\n const controller = new AbortController();\n const timeoutId = setTimeout(() => controller.abort(), timeout);\n\n try {\n const response = await fetch(url, {\n signal: controller.signal,\n headers: {\n \"User-Agent\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36\",\n Accept: \"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8\",\n \"Accept-Language\": \"en-US,en;q=0.9\",\n },\n });\n\n clearTimeout(timeoutId);\n\n if (!response.ok) {\n return {\n content: [{ type: \"text\", text: \"\" }],\n details: { url, format, error: `HTTP ${response.status}` },\n };\n }\n\n const contentLength = response.headers.get(\"content-length\");\n if (contentLength && parseInt(contentLength) > MAX_RESPONSE_SIZE) {\n return {\n content: [{ type: \"text\", text: \"\" }],\n details: { url, format, error: \"Response too large\" },\n };\n }\n\n const contentType = response.headers.get(\"content-type\") || \"\";\n const mime = contentType.split(\";\")[0]?.trim().toLowerCase() || \"\";\n\n if (\n mime.startsWith(\"image/\") ||\n mime.startsWith(\"video/\") ||\n mime.startsWith(\"audio/\") ||\n mime.startsWith(\"application/pdf\") ||\n mime.startsWith(\"application/zip\") ||\n mime.startsWith(\"application/octet-stream\")\n ) {\n return {\n content: [{ type: \"text\", text: \"\" }],\n details: { url, format, contentType: mime, skipped: true },\n };\n }\n\n const arrayBuffer = await response.arrayBuffer();\n\n if (arrayBuffer.byteLength > MAX_RESPONSE_SIZE) {\n return {\n content: [{ type: \"text\", text: \"\" }],\n details: { url, format, error: \"Response too large\" },\n };\n }\n\n let text = new TextDecoder().decode(arrayBuffer);\n let output = \"\";\n\n switch (format) {\n case \"markdown\":\n output = mime.includes(\"text/html\") ? htmlToMarkdown(text) : text;\n break;\n case \"text\":\n output = mime.includes(\"text/html\") ? htmlToText(text) : text;\n break;\n case \"html\":\n output = text;\n break;\n }\n\n return {\n content: [{ type: \"text\", text: output.trim() }],\n details: { url, format, contentType: mime },\n };\n } catch (error) {\n clearTimeout(timeoutId);\n const errorMsg = error instanceof Error ? error.message : \"Unknown error\";\n return {\n content: [{ type: \"text\", text: \"\" }],\n details: { url, format, error: errorMsg },\n };\n }\n}" }, { "path": "agents/pi/extensions/pi-codemode/tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"target\": \"ES2022\",\n \"module\": \"NodeNext\",\n \"moduleResolution\": \"NodeNext\",\n \"strict\": true,\n \"esModuleInterop\": true,\n \"skipLibCheck\": true,\n \"forceConsistentCasingInFileNames\": true,\n \"resolveJsonModule\": true,\n \"declaration\": true,\n \"declarationMap\": true,\n \"noEmit\": true,\n \"paths\": {\n \"@executor/codemode-core\": [\"./node_modules/@executor/codemode-core/src/index.ts\"]\n }\n },\n \"include\": [\"./src/**/*.ts\", \"./index.ts\"],\n \"exclude\": [\"node_modules\", \"examples\"]\n}\n" }, { "path": "agents/pi/extensions/prompt-timer.ts", "content": "import type { AssistantMessage } from \"@mariozechner/pi-ai\";\nimport type { ExtensionAPI } from \"@mariozechner/pi-coding-agent\";\n\nfunction isAssistantMessage(message: unknown): message is AssistantMessage {\n if (!message || typeof message !== \"object\") return false;\n const role = (message as { role?: unknown }).role;\n return role === \"assistant\";\n}\n\nfunction formatDuration(ms: number): string {\n const seconds = Math.floor(ms / 1000);\n const mins = Math.floor(seconds / 60);\n const secs = seconds % 60;\n\n if (mins > 0) {\n return `${mins}m ${secs}s`;\n }\n return `${secs}s`;\n}\n\nexport default function (pi: ExtensionAPI) {\n let agentStartMs: number | null = null;\n\n pi.on(\"agent_start\", () => {\n agentStartMs = Date.now();\n });\n\n pi.on(\"agent_end\", (event, ctx) => {\n if (!ctx.hasUI) return;\n if (agentStartMs === null) return;\n\n const elapsedMs = Date.now() - agentStartMs;\n agentStartMs = null;\n if (elapsedMs <= 0) return;\n\n let input = 0;\n let output = 0;\n let cacheRead = 0;\n let cacheWrite = 0;\n let totalTokens = 0;\n\n for (const message of event.messages) {\n if (!isAssistantMessage(message)) continue;\n input += message.usage.input || 0;\n output += message.usage.output || 0;\n cacheRead += message.usage.cacheRead || 0;\n cacheWrite += message.usage.cacheWrite || 0;\n totalTokens += message.usage.totalTokens || 0;\n }\n\n if (output <= 0) return;\n\n const elapsedSeconds = elapsedMs / 1000;\n const tokensPerSecond = output / elapsedSeconds;\n const message = `TPS: ${tokensPerSecond.toFixed(1)} tok/s · took ${formatDuration(elapsedMs)}`;\n ctx.ui.notify(message, \"info\");\n });\n}\n" }, { "path": "agents/pi/extensions/session-breakdown.ts", "content": "/**\n * /session-breakdown\n *\n * Interactive TUI that analyzes ~/.pi/agent/sessions (recursively, *.jsonl) and shows\n * last 7/30/90 days of:\n * - sessions/day\n * - messages/day\n * - tokens/day (if available)\n * - cost/day (if available)\n * - model breakdown (sessions/messages/tokens + cost)\n *\n * Graph:\n * - GitHub-contributions-style calendar (weeks x weekdays)\n * - Hue: weighted mix of popular model colors (weighted by the selected metric)\n * - Brightness: selected metric per day (log-scaled)\n */\n\nimport type { ExtensionAPI, ExtensionContext } from \"@mariozechner/pi-coding-agent\";\nimport { BorderedLoader } from \"@mariozechner/pi-coding-agent\";\nimport {\n\tKey,\n\tmatchesKey,\n\tsliceByColumn,\n\ttype Component,\n\ttype TUI,\n\ttruncateToWidth,\n\tvisibleWidth,\n} from \"@mariozechner/pi-tui\";\nimport os from \"node:os\";\nimport path from \"node:path\";\nimport fs from \"node:fs/promises\";\nimport { createReadStream, type Dirent } from \"node:fs\";\nimport readline from \"node:readline\";\n\ntype ModelKey = string; // `${provider}/${model}`\n\ninterface ParsedSession {\n\tfilePath: string;\n\tstartedAt: Date;\n\tdayKeyLocal: string; // YYYY-MM-DD (local)\n\tmodelsUsed: Set;\n\tmessages: number;\n\ttokens: number;\n\ttotalCost: number;\n\tcostByModel: Map;\n\tmessagesByModel: Map;\n\ttokensByModel: Map;\n}\n\ninterface DayAgg {\n\tdate: Date; // local midnight\n\tdayKeyLocal: string;\n\tsessions: number;\n\tmessages: number;\n\ttokens: number;\n\ttotalCost: number;\n\tcostByModel: Map;\n\tsessionsByModel: Map;\n\tmessagesByModel: Map;\n\ttokensByModel: Map;\n}\n\ninterface RangeAgg {\n\tdays: DayAgg[];\n\tdayByKey: Map;\n\tsessions: number;\n\ttotalMessages: number;\n\ttotalTokens: number;\n\ttotalCost: number;\n\tmodelCost: Map;\n\tmodelSessions: Map; // number of sessions where model was used\n\tmodelMessages: Map;\n\tmodelTokens: Map;\n}\n\ninterface RGB {\n\tr: number;\n\tg: number;\n\tb: number;\n}\n\ninterface BreakdownData {\n\tgeneratedAt: Date;\n\tranges: Map;\n\tpalette: {\n\t\tmodelColors: Map;\n\t\totherColor: RGB;\n\t\torderedModels: ModelKey[];\n\t};\n}\n\nconst SESSION_ROOT = path.join(os.homedir(), \".pi\", \"agent\", \"sessions\");\nconst RANGE_DAYS = [7, 30, 90] as const;\n\ntype MeasurementMode = \"sessions\" | \"messages\" | \"tokens\";\n\ntype BreakdownProgressPhase = \"scan\" | \"parse\" | \"finalize\";\n\ninterface BreakdownProgressState {\n\tphase: BreakdownProgressPhase;\n\tfoundFiles: number;\n\tparsedFiles: number;\n\ttotalFiles: number;\n\tcurrentFile?: string;\n}\n\nfunction setBorderedLoaderMessage(loader: BorderedLoader, message: string) {\n\t// BorderedLoader wraps a (Cancellable)Loader which supports setMessage(),\n\t// but it doesn't expose it publicly. Access the inner loader for progress updates.\n\tconst inner = (loader as any)[\"loader\"]; // eslint-disable-line @typescript-eslint/no-explicit-any\n\tif (inner && typeof inner.setMessage === \"function\") {\n\t\tinner.setMessage(message);\n\t}\n}\n\n// Dark-ish background and empty cell color (close to GitHub dark)\nconst DEFAULT_BG: RGB = { r: 13, g: 17, b: 23 };\nconst EMPTY_CELL_BG: RGB = { r: 22, g: 27, b: 34 };\n\n// Default palette (assigned to top models)\nconst PALETTE: RGB[] = [\n\t{ r: 64, g: 196, b: 99 }, // green\n\t{ r: 47, g: 129, b: 247 }, // blue\n\t{ r: 163, g: 113, b: 247 }, // purple\n\t{ r: 255, g: 159, b: 10 }, // orange\n\t{ r: 244, g: 67, b: 54 }, // red\n];\n\nfunction clamp01(x: number): number {\n\treturn Math.max(0, Math.min(1, x));\n}\n\nfunction lerp(a: number, b: number, t: number): number {\n\treturn a + (b - a) * t;\n}\n\nfunction mixRgb(a: RGB, b: RGB, t: number): RGB {\n\treturn {\n\t\tr: Math.round(lerp(a.r, b.r, t)),\n\t\tg: Math.round(lerp(a.g, b.g, t)),\n\t\tb: Math.round(lerp(a.b, b.b, t)),\n\t};\n}\n\nfunction weightedMix(colors: Array<{ color: RGB; weight: number }>): RGB {\n\tlet total = 0;\n\tlet r = 0;\n\tlet g = 0;\n\tlet b = 0;\n\tfor (const c of colors) {\n\t\tif (!Number.isFinite(c.weight) || c.weight <= 0) continue;\n\t\ttotal += c.weight;\n\t\tr += c.color.r * c.weight;\n\t\tg += c.color.g * c.weight;\n\t\tb += c.color.b * c.weight;\n\t}\n\tif (total <= 0) return EMPTY_CELL_BG;\n\treturn { r: Math.round(r / total), g: Math.round(g / total), b: Math.round(b / total) };\n}\n\nfunction ansiBg(rgb: RGB, text: string): string {\n\treturn `\\x1b[48;2;${rgb.r};${rgb.g};${rgb.b}m${text}\\x1b[0m`;\n}\n\nfunction ansiFg(rgb: RGB, text: string): string {\n\treturn `\\x1b[38;2;${rgb.r};${rgb.g};${rgb.b}m${text}\\x1b[0m`;\n}\n\nfunction dim(text: string): string {\n\treturn `\\x1b[2m${text}\\x1b[0m`;\n}\n\nfunction bold(text: string): string {\n\treturn `\\x1b[1m${text}\\x1b[0m`;\n}\n\nfunction formatCount(n: number): string {\n\tif (!Number.isFinite(n) || n === 0) return \"0\";\n\tif (n >= 1_000_000_000) return `${(n / 1_000_000_000).toFixed(1)}B`;\n\tif (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;\n\tif (n >= 10_000) return `${(n / 1_000).toFixed(1)}K`;\n\treturn n.toLocaleString(\"en-US\");\n}\n\nfunction formatUsd(cost: number): string {\n\tif (!Number.isFinite(cost)) return \"$0.00\";\n\tif (cost >= 1) return `$${cost.toFixed(2)}`;\n\tif (cost >= 0.1) return `$${cost.toFixed(3)}`;\n\treturn `$${cost.toFixed(4)}`;\n}\n\nfunction padRight(s: string, n: number): string {\n\tconst delta = n - s.length;\n\treturn delta > 0 ? s + \" \".repeat(delta) : s;\n}\n\nfunction padLeft(s: string, n: number): string {\n\tconst delta = n - s.length;\n\treturn delta > 0 ? \" \".repeat(delta) + s : s;\n}\n\nfunction toLocalDayKey(d: Date): string {\n\tconst yyyy = d.getFullYear();\n\tconst mm = String(d.getMonth() + 1).padStart(2, \"0\");\n\tconst dd = String(d.getDate()).padStart(2, \"0\");\n\treturn `${yyyy}-${mm}-${dd}`;\n}\n\nfunction localMidnight(d: Date): Date {\n\treturn new Date(d.getFullYear(), d.getMonth(), d.getDate(), 0, 0, 0, 0);\n}\n\nfunction addDaysLocal(d: Date, days: number): Date {\n\tconst x = new Date(d);\n\tx.setDate(x.getDate() + days);\n\treturn x;\n}\n\nfunction countDaysInclusiveLocal(start: Date, end: Date): number {\n\t// Avoid ms-based day math because DST transitions can make a “day” 23/25h in local time.\n\tlet n = 0;\n\tfor (let d = new Date(start); d <= end; d = addDaysLocal(d, 1)) n++;\n\treturn n;\n}\n\nfunction mondayIndex(date: Date): number {\n\t// Mon=0 .. Sun=6\n\treturn (date.getDay() + 6) % 7;\n}\n\nfunction modelKeyFromParts(provider?: unknown, model?: unknown): ModelKey | null {\n\tconst p = typeof provider === \"string\" ? provider.trim() : \"\";\n\tconst m = typeof model === \"string\" ? model.trim() : \"\";\n\tif (!p && !m) return null;\n\tif (!p) return m;\n\tif (!m) return p;\n\treturn `${p}/${m}`;\n}\n\nfunction parseSessionStartFromFilename(name: string): Date | null {\n\t// Example: 2026-02-02T21-52-28-774Z_.jsonl\n\tconst m = name.match(/^(\\d{4}-\\d{2}-\\d{2})T(\\d{2})-(\\d{2})-(\\d{2})-(\\d{3})Z_/);\n\tif (!m) return null;\n\tconst iso = `${m[1]}T${m[2]}:${m[3]}:${m[4]}.${m[5]}Z`;\n\tconst d = new Date(iso);\n\treturn Number.isFinite(d.getTime()) ? d : null;\n}\n\nfunction extractProviderModelAndUsage(obj: any): { provider?: any; model?: any; modelId?: any; usage?: any } {\n\t// Session format varies across versions.\n\t// - Newer: { provider, model, usage } on the message wrapper\n\t// - Older: { message: { provider, model, usage } }\n\tconst msg = obj?.message;\n\treturn {\n\t\tprovider: obj?.provider ?? msg?.provider,\n\t\tmodel: obj?.model ?? msg?.model,\n\t\tmodelId: obj?.modelId ?? msg?.modelId,\n\t\tusage: obj?.usage ?? msg?.usage,\n\t};\n}\n\nfunction extractCostTotal(usage: any): number {\n\tif (!usage) return 0;\n\tconst c = usage?.cost;\n\tif (typeof c === \"number\") return Number.isFinite(c) ? c : 0;\n\tif (typeof c === \"string\") {\n\t\tconst n = Number(c);\n\t\treturn Number.isFinite(n) ? n : 0;\n\t}\n\tconst t = c?.total;\n\tif (typeof t === \"number\") return Number.isFinite(t) ? t : 0;\n\tif (typeof t === \"string\") {\n\t\tconst n = Number(t);\n\t\treturn Number.isFinite(n) ? n : 0;\n\t}\n\treturn 0;\n}\n\nfunction extractTokensTotal(usage: any): number {\n\t// Usage format varies across providers and pi versions.\n\t// We try a few common shapes:\n\t// - { totalTokens }\n\t// - { total_tokens }\n\t// - { promptTokens, completionTokens }\n\t// - { prompt_tokens, completion_tokens }\n\t// - { input_tokens, output_tokens }\n\t// - { inputTokens, outputTokens }\n\t// - { tokens: number | { total } }\n\tif (!usage) return 0;\n\n\tconst readNum = (v: any): number => {\n\t\tif (typeof v === \"number\") return Number.isFinite(v) ? v : 0;\n\t\tif (typeof v === \"string\") {\n\t\t\tconst n = Number(v);\n\t\t\treturn Number.isFinite(n) ? n : 0;\n\t\t}\n\t\treturn 0;\n\t};\n\n\tlet total = 0;\n\t// direct totals\n\ttotal =\n\t\treadNum(usage?.totalTokens) ||\n\t\treadNum(usage?.total_tokens) ||\n\t\treadNum(usage?.tokens) ||\n\t\treadNum(usage?.tokenCount) ||\n\t\treadNum(usage?.token_count);\n\tif (total > 0) return total;\n\n\t// nested tokens object\n\ttotal = readNum(usage?.tokens?.total) || readNum(usage?.tokens?.totalTokens) || readNum(usage?.tokens?.total_tokens);\n\tif (total > 0) return total;\n\n\t// sum of parts\n\tconst a =\n\t\treadNum(usage?.promptTokens) ||\n\t\treadNum(usage?.prompt_tokens) ||\n\t\treadNum(usage?.inputTokens) ||\n\t\treadNum(usage?.input_tokens);\n\tconst b =\n\t\treadNum(usage?.completionTokens) ||\n\t\treadNum(usage?.completion_tokens) ||\n\t\treadNum(usage?.outputTokens) ||\n\t\treadNum(usage?.output_tokens);\n\tconst sum = a + b;\n\treturn sum > 0 ? sum : 0;\n}\n\nasync function walkSessionFiles(\n\troot: string,\n\tstartCutoffLocal: Date,\n\tsignal?: AbortSignal,\n\tonFound?: (found: number) => void,\n): Promise {\n\tconst out: string[] = [];\n\tconst stack: string[] = [root];\n\twhile (stack.length) {\n\t\tif (signal?.aborted) break;\n\t\tconst dir = stack.pop()!;\n\t\tlet entries: Dirent[] = [];\n\t\ttry {\n\t\t\tentries = await fs.readdir(dir, { withFileTypes: true });\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\n\t\tfor (const ent of entries) {\n\t\t\tif (signal?.aborted) break;\n\t\t\tconst p = path.join(dir, ent.name);\n\t\t\tif (ent.isDirectory()) {\n\t\t\t\tstack.push(p);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!ent.isFile() || !ent.name.endsWith(\".jsonl\")) continue;\n\n\t\t\t// Prefer filename timestamp, else fall back to mtime.\n\t\t\tconst startedAt = parseSessionStartFromFilename(ent.name);\n\t\t\tif (startedAt) {\n\t\t\t\tif (localMidnight(startedAt) >= startCutoffLocal) {\n\t\t\t\t\tout.push(p);\n\t\t\t\t\tif (onFound && out.length % 10 === 0) onFound(out.length);\n\t\t\t\t}\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\ttry {\n\t\t\t\tconst st = await fs.stat(p);\n\t\t\t\tconst approx = new Date(st.mtimeMs);\n\t\t\t\tif (localMidnight(approx) >= startCutoffLocal) {\n\t\t\t\t\tout.push(p);\n\t\t\t\t\tif (onFound && out.length % 10 === 0) onFound(out.length);\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\t// ignore\n\t\t\t}\n\t\t}\n\t}\n\tonFound?.(out.length);\n\treturn out;\n}\n\nasync function parseSessionFile(filePath: string, signal?: AbortSignal): Promise {\n\tconst fileName = path.basename(filePath);\n\tlet startedAt = parseSessionStartFromFilename(fileName);\n\tlet currentModel: ModelKey | null = null;\n\n\tconst modelsUsed = new Set();\n\tlet messages = 0;\n\tlet tokens = 0;\n\tlet totalCost = 0;\n\tconst costByModel = new Map();\n\tconst messagesByModel = new Map();\n\tconst tokensByModel = new Map();\n\n\tconst stream = createReadStream(filePath, { encoding: \"utf8\" });\n\tconst rl = readline.createInterface({ input: stream, crlfDelay: Infinity });\n\n\ttry {\n\t\tfor await (const line of rl) {\n\t\t\tif (signal?.aborted) {\n\t\t\t\trl.close();\n\t\t\t\tstream.destroy();\n\t\t\t\treturn null;\n\t\t\t}\n\t\t\tif (!line) continue;\n\t\t\tlet obj: any;\n\t\t\ttry {\n\t\t\t\tobj = JSON.parse(line);\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tif (!startedAt && obj?.type === \"session\" && typeof obj?.timestamp === \"string\") {\n\t\t\t\tconst d = new Date(obj.timestamp);\n\t\t\t\tif (Number.isFinite(d.getTime())) startedAt = d;\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tif (obj?.type === \"model_change\") {\n\t\t\t\tconst mk = modelKeyFromParts(obj.provider, obj.modelId);\n\t\t\t\tif (mk) {\n\t\t\t\t\tcurrentModel = mk;\n\t\t\t\t\tmodelsUsed.add(mk);\n\t\t\t\t}\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tif (obj?.type !== \"message\") continue;\n\n\t\t\tconst { provider, model, modelId, usage } = extractProviderModelAndUsage(obj);\n\t\t\tconst mk =\n\t\t\t\tmodelKeyFromParts(provider, model) ??\n\t\t\t\tmodelKeyFromParts(provider, modelId) ??\n\t\t\t\tcurrentModel ??\n\t\t\t\t\"unknown\";\n\t\t\tmodelsUsed.add(mk);\n\n\t\t\tmessages += 1;\n\t\t\tmessagesByModel.set(mk, (messagesByModel.get(mk) ?? 0) + 1);\n\n\t\t\tconst tok = extractTokensTotal(usage);\n\t\t\tif (tok > 0) {\n\t\t\t\ttokens += tok;\n\t\t\t\ttokensByModel.set(mk, (tokensByModel.get(mk) ?? 0) + tok);\n\t\t\t}\n\n\t\t\tconst cost = extractCostTotal(usage);\n\t\t\tif (cost > 0) {\n\t\t\t\ttotalCost += cost;\n\t\t\t\tcostByModel.set(mk, (costByModel.get(mk) ?? 0) + cost);\n\t\t\t}\n\t\t}\n\t} finally {\n\t\trl.close();\n\t\tstream.destroy();\n\t}\n\n\tif (!startedAt) return null;\n\tconst dayKeyLocal = toLocalDayKey(startedAt);\n\treturn {\n\t\tfilePath,\n\t\tstartedAt,\n\t\tdayKeyLocal,\n\t\tmodelsUsed,\n\t\tmessages,\n\t\ttokens,\n\t\ttotalCost,\n\t\tcostByModel,\n\t\tmessagesByModel,\n\t\ttokensByModel,\n\t};\n}\n\nfunction buildRangeAgg(days: number, now: Date): RangeAgg {\n\tconst end = localMidnight(now);\n\tconst start = addDaysLocal(end, -(days - 1));\n\tconst outDays: DayAgg[] = [];\n\tconst dayByKey = new Map();\n\n\tfor (let i = 0; i < days; i++) {\n\t\tconst d = addDaysLocal(start, i);\n\t\tconst dayKeyLocal = toLocalDayKey(d);\n\t\tconst day: DayAgg = {\n\t\t\tdate: d,\n\t\t\tdayKeyLocal,\n\t\t\tsessions: 0,\n\t\t\tmessages: 0,\n\t\t\ttokens: 0,\n\t\t\ttotalCost: 0,\n\t\t\tcostByModel: new Map(),\n\t\t\tsessionsByModel: new Map(),\n\t\t\tmessagesByModel: new Map(),\n\t\t\ttokensByModel: new Map(),\n\t\t};\n\t\toutDays.push(day);\n\t\tdayByKey.set(dayKeyLocal, day);\n\t}\n\n\treturn {\n\t\tdays: outDays,\n\t\tdayByKey,\n\t\tsessions: 0,\n\t\ttotalMessages: 0,\n\t\ttotalTokens: 0,\n\t\ttotalCost: 0,\n\t\tmodelCost: new Map(),\n\t\tmodelSessions: new Map(),\n\t\tmodelMessages: new Map(),\n\t\tmodelTokens: new Map(),\n\t};\n}\n\nfunction addSessionToRange(range: RangeAgg, session: ParsedSession): void {\n\tconst day = range.dayByKey.get(session.dayKeyLocal);\n\tif (!day) return;\n\n\trange.sessions += 1;\n\trange.totalMessages += session.messages;\n\trange.totalTokens += session.tokens;\n\trange.totalCost += session.totalCost;\n\tday.sessions += 1;\n\tday.messages += session.messages;\n\tday.tokens += session.tokens;\n\tday.totalCost += session.totalCost;\n\n\t// Sessions-per-model (presence)\n\tfor (const mk of session.modelsUsed) {\n\t\tday.sessionsByModel.set(mk, (day.sessionsByModel.get(mk) ?? 0) + 1);\n\t\trange.modelSessions.set(mk, (range.modelSessions.get(mk) ?? 0) + 1);\n\t}\n\n\t// Messages-per-model\n\tfor (const [mk, n] of session.messagesByModel.entries()) {\n\t\tday.messagesByModel.set(mk, (day.messagesByModel.get(mk) ?? 0) + n);\n\t\trange.modelMessages.set(mk, (range.modelMessages.get(mk) ?? 0) + n);\n\t}\n\n\t// Tokens-per-model\n\tfor (const [mk, n] of session.tokensByModel.entries()) {\n\t\tday.tokensByModel.set(mk, (day.tokensByModel.get(mk) ?? 0) + n);\n\t\trange.modelTokens.set(mk, (range.modelTokens.get(mk) ?? 0) + n);\n\t}\n\n\t// Cost-per-model\n\tfor (const [mk, cost] of session.costByModel.entries()) {\n\t\tday.costByModel.set(mk, (day.costByModel.get(mk) ?? 0) + cost);\n\t\trange.modelCost.set(mk, (range.modelCost.get(mk) ?? 0) + cost);\n\t}\n}\n\nfunction sortMapByValueDesc(m: Map): Array<{ key: K; value: number }> {\n\treturn [...m.entries()]\n\t\t.map(([key, value]) => ({ key, value }))\n\t\t.sort((a, b) => b.value - a.value);\n}\n\nfunction choosePaletteFromLast30Days(range30: RangeAgg, topN = 4): {\n\tmodelColors: Map;\n\totherColor: RGB;\n\torderedModels: ModelKey[];\n} {\n\t// Prefer cost if any cost exists, else tokens, else messages, else sessions.\n\tconst costSum = [...range30.modelCost.values()].reduce((a, b) => a + b, 0);\n\tconst popularity =\n\t\tcostSum > 0\n\t\t\t? range30.modelCost\n\t\t\t: range30.totalTokens > 0\n\t\t\t\t? range30.modelTokens\n\t\t\t\t: range30.totalMessages > 0\n\t\t\t\t\t? range30.modelMessages\n\t\t\t\t\t: range30.modelSessions;\n\n\tconst sorted = sortMapByValueDesc(popularity);\n\tconst orderedModels = sorted.slice(0, topN).map((x) => x.key);\n\tconst modelColors = new Map();\n\tfor (let i = 0; i < orderedModels.length; i++) {\n\t\tmodelColors.set(orderedModels[i], PALETTE[i % PALETTE.length]);\n\t}\n\treturn {\n\t\tmodelColors,\n\t\totherColor: { r: 160, g: 160, b: 160 },\n\t\torderedModels,\n\t};\n}\n\nfunction dayMixedColor(\n\tday: DayAgg,\n\tmodelColors: Map,\n\totherColor: RGB,\n\tmode: MeasurementMode,\n): RGB {\n\tconst parts: Array<{ color: RGB; weight: number }> = [];\n\tlet otherWeight = 0;\n\n\tlet map: Map;\n\tif (mode === \"tokens\") {\n\t\tmap = day.tokens > 0 ? day.tokensByModel : day.messages > 0 ? day.messagesByModel : day.sessionsByModel;\n\t} else if (mode === \"messages\") {\n\t\tmap = day.messages > 0 ? day.messagesByModel : day.sessionsByModel;\n\t} else {\n\t\tmap = day.sessionsByModel;\n\t}\n\n\tfor (const [mk, w] of map.entries()) {\n\t\tconst c = modelColors.get(mk);\n\t\tif (c) parts.push({ color: c, weight: w });\n\t\telse otherWeight += w;\n\t}\n\tif (otherWeight > 0) parts.push({ color: otherColor, weight: otherWeight });\n\treturn weightedMix(parts);\n}\n\nfunction graphMetricForRange(\n\trange: RangeAgg,\n\tmode: MeasurementMode,\n): { kind: \"sessions\" | \"messages\" | \"tokens\"; max: number; denom: number } {\n\tif (mode === \"tokens\") {\n\t\tconst maxTokens = Math.max(0, ...range.days.map((d) => d.tokens));\n\t\tif (maxTokens > 0) return { kind: \"tokens\", max: maxTokens, denom: Math.log1p(maxTokens) };\n\t\t// fall back if tokens aren't available\n\t\tmode = \"messages\";\n\t}\n\n\tif (mode === \"messages\") {\n\t\tconst maxMessages = Math.max(0, ...range.days.map((d) => d.messages));\n\t\tif (maxMessages > 0) return { kind: \"messages\", max: maxMessages, denom: Math.log1p(maxMessages) };\n\t\t// fall back if messages aren't available\n\t\tmode = \"sessions\";\n\t}\n\n\tconst maxSessions = Math.max(0, ...range.days.map((d) => d.sessions));\n\treturn { kind: \"sessions\", max: maxSessions, denom: Math.log1p(maxSessions) };\n}\n\nfunction weeksForRange(range: RangeAgg): number {\n\tconst days = range.days;\n\tconst start = days[0].date;\n\tconst end = days[days.length - 1].date;\n\tconst gridStart = addDaysLocal(start, -mondayIndex(start));\n\tconst gridEnd = addDaysLocal(end, 6 - mondayIndex(end));\n\tconst totalGridDays = countDaysInclusiveLocal(gridStart, gridEnd);\n\treturn Math.ceil(totalGridDays / 7);\n}\n\nfunction renderGraphLines(\n\trange: RangeAgg,\n\tmodelColors: Map,\n\totherColor: RGB,\n\tmode: MeasurementMode,\n\toptions?: { cellWidth?: number; gap?: number },\n): string[] {\n\tconst days = range.days;\n\tconst start = days[0].date;\n\tconst end = days[days.length - 1].date;\n\n\tconst gridStart = addDaysLocal(start, -mondayIndex(start));\n\tconst gridEnd = addDaysLocal(end, 6 - mondayIndex(end));\n\tconst totalGridDays = countDaysInclusiveLocal(gridStart, gridEnd);\n\tconst weeks = Math.ceil(totalGridDays / 7);\n\n\tconst cellWidth = Math.max(1, Math.floor(options?.cellWidth ?? 1));\n\tconst gap = Math.max(0, Math.floor(options?.gap ?? 1));\n\tconst block = \"█\".repeat(cellWidth);\n\tconst gapStr = \" \".repeat(gap);\n\n\tconst metric = graphMetricForRange(range, mode);\n\tconst denom = metric.denom;\n\n\t// Label only Mon/Wed/Fri like GitHub (saves space)\n\tconst labelByRow = new Map([\n\t\t[0, \"Mon\"],\n\t\t[2, \"Wed\"],\n\t\t[4, \"Fri\"],\n\t]);\n\n\tconst lines: string[] = [];\n\tfor (let row = 0; row < 7; row++) {\n\t\tconst label = labelByRow.get(row);\n\t\tlet line = label ? padRight(label, 3) + \" \" : \" \";\n\n\t\tfor (let w = 0; w < weeks; w++) {\n\t\t\tconst cellDate = addDaysLocal(gridStart, w * 7 + row);\n\t\t\tconst inRange = cellDate >= start && cellDate <= end;\n\t\t\tconst colGap = w < weeks - 1 ? gapStr : \"\";\n\t\t\tif (!inRange) {\n\t\t\t\tline += \" \".repeat(cellWidth) + colGap;\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tconst key = toLocalDayKey(cellDate);\n\t\t\tconst day = range.dayByKey.get(key);\n\t\t\tconst value =\n\t\t\t\tmetric.kind === \"tokens\"\n\t\t\t\t\t? (day?.tokens ?? 0)\n\t\t\t\t\t: metric.kind === \"messages\"\n\t\t\t\t\t\t? (day?.messages ?? 0)\n\t\t\t\t\t\t: (day?.sessions ?? 0);\n\n\t\t\tif (!day || value <= 0) {\n\t\t\t\tline += ansiFg(EMPTY_CELL_BG, block) + colGap;\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tconst hue = dayMixedColor(day, modelColors, otherColor, mode);\n\t\t\tlet t = denom > 0 ? Math.log1p(value) / denom : 0;\n\t\t\tt = clamp01(t);\n\t\t\tconst minVisible = 0.2;\n\t\t\tconst intensity = minVisible + (1 - minVisible) * t;\n\t\t\tconst rgb = mixRgb(DEFAULT_BG, hue, intensity);\n\t\t\tline += ansiFg(rgb, block) + colGap;\n\t\t}\n\n\t\tlines.push(line);\n\t}\n\n\treturn lines;\n}\n\nfunction displayModelName(modelKey: string): string {\n\tconst idx = modelKey.indexOf(\"/\");\n\treturn idx === -1 ? modelKey : modelKey.slice(idx + 1);\n}\n\nfunction renderLegendItems(modelColors: Map, orderedModels: ModelKey[], otherColor: RGB): string[] {\n\tconst items: string[] = [];\n\tfor (const mk of orderedModels) {\n\t\tconst c = modelColors.get(mk);\n\t\tif (!c) continue;\n\t\titems.push(`${ansiFg(c, \"█\")} ${displayModelName(mk)}`);\n\t}\n\titems.push(`${ansiFg(otherColor, \"█\")} other`);\n\treturn items;\n}\n\nfunction fitRight(text: string, width: number): string {\n\tif (width <= 0) return \"\";\n\tlet w = visibleWidth(text);\n\tlet t = text;\n\tif (w > width) {\n\t\tt = sliceByColumn(t, w - width, width, true);\n\t\tw = visibleWidth(t);\n\t}\n\treturn \" \".repeat(Math.max(0, width - w)) + t;\n}\n\nfunction renderLegendBlock(leftLabel: string, items: string[], width: number): string[] {\n\tif (width <= 0) return [];\n\tif (items.length === 0) return [truncateToWidth(leftLabel, width)];\n\n\tconst lines: string[] = [];\n\t// First line: label on left, first item right-aligned into remaining space.\n\tconst leftW = visibleWidth(leftLabel);\n\tif (leftW >= width) {\n\t\tlines.push(truncateToWidth(leftLabel, width));\n\t\t// Put all items on their own lines right-aligned.\n\t\tfor (const it of items) lines.push(fitRight(it, width));\n\t\treturn lines;\n\t}\n\n\tconst remaining = Math.max(0, width - leftW);\n\tlines.push(leftLabel + fitRight(items[0], remaining));\n\n\tfor (let i = 1; i < items.length; i++) {\n\t\tlines.push(fitRight(items[i], width));\n\t}\n\treturn lines;\n}\n\nfunction renderModelTable(range: RangeAgg, mode: MeasurementMode, maxRows = 8): string[] {\n\t// Keep this relatively narrow: model + selected metric + cost + share.\n\tconst metric = graphMetricForRange(range, mode);\n\tconst kind = metric.kind;\n\n\tlet perModel: Map;\n\tlet total = 0;\n\tlet label = kind;\n\n\tif (kind === \"tokens\") {\n\t\tperModel = range.modelTokens;\n\t\ttotal = range.totalTokens;\n\t} else if (kind === \"messages\") {\n\t\tperModel = range.modelMessages;\n\t\ttotal = range.totalMessages;\n\t} else {\n\t\tperModel = range.modelSessions;\n\t\ttotal = range.sessions;\n\t}\n\n\tconst sorted = sortMapByValueDesc(perModel);\n\tconst rows = sorted.slice(0, maxRows);\n\n\tconst valueWidth = kind === \"tokens\" ? 10 : 8;\n\tconst modelWidth = Math.min(52, Math.max(\"model\".length, ...rows.map((r) => r.key.length)));\n\n\tconst lines: string[] = [];\n\tlines.push(`${padRight(\"model\", modelWidth)} ${padLeft(label, valueWidth)} ${padLeft(\"cost\", 10)} ${padLeft(\"share\", 6)}`);\n\tlines.push(`${\"-\".repeat(modelWidth)} ${\"-\".repeat(valueWidth)} ${\"-\".repeat(10)} ${\"-\".repeat(6)}`);\n\n\tfor (const r of rows) {\n\t\tconst value = perModel.get(r.key) ?? 0;\n\t\tconst cost = range.modelCost.get(r.key) ?? 0;\n\t\tconst share = total > 0 ? `${Math.round((value / total) * 100)}%` : \"0%\";\n\t\tlines.push(\n\t\t\t`${padRight(r.key.slice(0, modelWidth), modelWidth)} ${padLeft(formatCount(value), valueWidth)} ${padLeft(formatUsd(cost), 10)} ${padLeft(share, 6)}`,\n\t\t);\n\t}\n\n\tif (sorted.length === 0) {\n\t\tlines.push(dim(\"(no model data found)\"));\n\t}\n\n\treturn lines;\n}\n\nfunction renderLeftRight(left: string, right: string, width: number): string {\n\tconst leftW = visibleWidth(left);\n\tif (width <= 0) return \"\";\n\tif (leftW >= width) return truncateToWidth(left, width);\n\n\tconst remaining = width - leftW;\n\tlet rightText = right;\n\tconst rightW = visibleWidth(rightText);\n\tif (rightW > remaining) {\n\t\t// Keep the *rightmost* part visible.\n\t\trightText = sliceByColumn(rightText, rightW - remaining, remaining, true);\n\t}\n\tconst pad = Math.max(0, remaining - visibleWidth(rightText));\n\treturn left + \" \".repeat(pad) + rightText;\n}\n\nfunction rangeSummary(range: RangeAgg, days: number, mode: MeasurementMode): string {\n\tconst avg = range.sessions > 0 ? range.totalCost / range.sessions : 0;\n\tconst costPart = range.totalCost > 0 ? `${formatUsd(range.totalCost)} · avg ${formatUsd(avg)}/session` : `$0.0000`;\n\n\tif (mode === \"tokens\") {\n\t\treturn `Last ${days} days: ${formatCount(range.sessions)} sessions · ${formatCount(range.totalTokens)} tokens · ${costPart}`;\n\t}\n\tif (mode === \"messages\") {\n\t\treturn `Last ${days} days: ${formatCount(range.sessions)} sessions · ${formatCount(range.totalMessages)} messages · ${costPart}`;\n\t}\n\treturn `Last ${days} days: ${formatCount(range.sessions)} sessions · ${costPart}`;\n}\n\nasync function computeBreakdown(\n\tsignal?: AbortSignal,\n\tonProgress?: (update: Partial) => void,\n): Promise {\n\tconst now = new Date();\n\tconst ranges = new Map();\n\tfor (const d of RANGE_DAYS) ranges.set(d, buildRangeAgg(d, now));\n\tconst range90 = ranges.get(90)!;\n\tconst start90 = range90.days[0].date;\n\n\tonProgress?.({ phase: \"scan\", foundFiles: 0, parsedFiles: 0, totalFiles: 0, currentFile: undefined });\n\n\tconst candidates = await walkSessionFiles(SESSION_ROOT, start90, signal, (found) => {\n\t\tonProgress?.({ phase: \"scan\", foundFiles: found });\n\t});\n\n\tconst totalFiles = candidates.length;\n\tonProgress?.({\n\t\tphase: \"parse\",\n\t\tfoundFiles: totalFiles,\n\t\ttotalFiles,\n\t\tparsedFiles: 0,\n\t\tcurrentFile: totalFiles > 0 ? path.basename(candidates[0]!) : undefined,\n\t});\n\n\tlet parsedFiles = 0;\n\tfor (const filePath of candidates) {\n\t\tif (signal?.aborted) break;\n\t\tparsedFiles += 1;\n\t\tonProgress?.({ phase: \"parse\", parsedFiles, totalFiles, currentFile: path.basename(filePath) });\n\n\t\tconst session = await parseSessionFile(filePath, signal);\n\t\tif (!session) continue;\n\n\t\tconst sessionDay = localMidnight(session.startedAt);\n\t\tfor (const d of RANGE_DAYS) {\n\t\t\tconst range = ranges.get(d)!;\n\t\t\tconst start = range.days[0].date;\n\t\t\tconst end = range.days[range.days.length - 1].date;\n\t\t\tif (sessionDay < start || sessionDay > end) continue;\n\t\t\taddSessionToRange(range, session);\n\t\t}\n\t}\n\n\tonProgress?.({ phase: \"finalize\", currentFile: undefined });\n\n\tconst palette = choosePaletteFromLast30Days(ranges.get(30)!, 4);\n\treturn { generatedAt: now, ranges, palette };\n}\n\nclass BreakdownComponent implements Component {\n\tprivate data: BreakdownData;\n\tprivate tui: TUI;\n\tprivate onDone: () => void;\n\tprivate rangeIndex = 1; // default 30d\n\tprivate measurement: MeasurementMode = \"sessions\";\n\tprivate cachedWidth?: number;\n\tprivate cachedLines?: string[];\n\n\tconstructor(data: BreakdownData, tui: TUI, onDone: () => void) {\n\t\tthis.data = data;\n\t\tthis.tui = tui;\n\t\tthis.onDone = onDone;\n\t}\n\n\tinvalidate(): void {\n\t\tthis.cachedWidth = undefined;\n\t\tthis.cachedLines = undefined;\n\t}\n\n\thandleInput(data: string): void {\n\t\tif (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl(\"c\")) || data.toLowerCase() === \"q\") {\n\t\t\tthis.onDone();\n\t\t\treturn;\n\t\t}\n\n\t\tif (matchesKey(data, Key.tab) || matchesKey(data, Key.shift(\"tab\")) || data.toLowerCase() === \"t\") {\n\t\t\tconst order: MeasurementMode[] = [\"sessions\", \"messages\", \"tokens\"];\n\t\t\tconst idx = Math.max(0, order.indexOf(this.measurement));\n\t\t\tconst dir = matchesKey(data, Key.shift(\"tab\")) ? -1 : 1;\n\t\t\tthis.measurement = order[(idx + order.length + dir) % order.length] ?? \"sessions\";\n\t\t\tthis.invalidate();\n\t\t\tthis.tui.requestRender();\n\t\t\treturn;\n\t\t}\n\n\t\tconst prev = () => {\n\t\t\tthis.rangeIndex = (this.rangeIndex + RANGE_DAYS.length - 1) % RANGE_DAYS.length;\n\t\t\tthis.invalidate();\n\t\t\tthis.tui.requestRender();\n\t\t};\n\t\tconst next = () => {\n\t\t\tthis.rangeIndex = (this.rangeIndex + 1) % RANGE_DAYS.length;\n\t\t\tthis.invalidate();\n\t\t\tthis.tui.requestRender();\n\t\t};\n\n\t\tif (matchesKey(data, Key.left) || data.toLowerCase() === \"h\") prev();\n\t\tif (matchesKey(data, Key.right) || data.toLowerCase() === \"l\") next();\n\n\t\tif (data === \"1\") {\n\t\t\tthis.rangeIndex = 0;\n\t\t\tthis.invalidate();\n\t\t\tthis.tui.requestRender();\n\t\t}\n\t\tif (data === \"2\") {\n\t\t\tthis.rangeIndex = 1;\n\t\t\tthis.invalidate();\n\t\t\tthis.tui.requestRender();\n\t\t}\n\t\tif (data === \"3\") {\n\t\t\tthis.rangeIndex = 2;\n\t\t\tthis.invalidate();\n\t\t\tthis.tui.requestRender();\n\t\t}\n\t}\n\n\trender(width: number): string[] {\n\t\tif (this.cachedWidth === width && this.cachedLines) return this.cachedLines;\n\n\t\tconst selectedDays = RANGE_DAYS[this.rangeIndex];\n\t\tconst range = this.data.ranges.get(selectedDays)!;\n\t\tconst metric = graphMetricForRange(range, this.measurement);\n\n\t\tconst tab = (days: number, idx: number): string => {\n\t\t\tconst selected = idx === this.rangeIndex;\n\t\t\tconst label = `${days}d`;\n\t\t\treturn selected ? bold(`[${label}]`) : dim(` ${label} `);\n\t\t};\n\n\t\tconst metricTab = (mode: MeasurementMode, label: string): string => {\n\t\t\tconst selected = mode === this.measurement;\n\t\t\treturn selected ? bold(`[${label}]`) : dim(` ${label} `);\n\t\t};\n\n\t\tconst header =\n\t\t\t`${bold(\"Session breakdown\")} ${tab(7, 0)} ${tab(30, 1)} ${tab(90, 2)} ` +\n\t\t\t`${metricTab(\"sessions\", \"sess\")} ${metricTab(\"messages\", \"msg\")} ${metricTab(\"tokens\", \"tok\")}`;\n\n\t\tconst legendItems = renderLegendItems(\n\t\t\tthis.data.palette.modelColors,\n\t\t\tthis.data.palette.orderedModels,\n\t\t\tthis.data.palette.otherColor,\n\t\t);\n\n\t\tconst summary = rangeSummary(range, selectedDays, metric.kind) + dim(` (graph: ${metric.kind}/day)`);\n\n\t\tconst maxScale = selectedDays === 7 ? 4 : selectedDays === 30 ? 3 : 2;\n\t\tconst weeks = weeksForRange(range);\n\t\tconst leftMargin = 4; // \"Mon \" (or 4 spaces)\n\t\tconst gap = 1;\n\t\tconst graphArea = Math.max(1, width - leftMargin);\n\t\t// Each week column uses: cellWidth + gap. Last column also gets gap (fine; we truncate anyway).\n\t\tconst idealCellWidth = Math.floor((graphArea + gap) / Math.max(1, weeks)) - gap;\n\t\tconst cellWidth = Math.min(maxScale, Math.max(1, idealCellWidth));\n\n\t\tconst graphLines = renderGraphLines(\n\t\t\trange,\n\t\t\tthis.data.palette.modelColors,\n\t\t\tthis.data.palette.otherColor,\n\t\t\tthis.measurement,\n\t\t\t{ cellWidth, gap },\n\t\t);\n\t\tconst tableLines = renderModelTable(range, metric.kind, 8);\n\n\t\tconst lines: string[] = [];\n\t\tlines.push(truncateToWidth(header, width));\n\t\tlines.push(truncateToWidth(dim(\"←/→ range · tab metric · q to close\"), width));\n\t\tlines.push(\"\");\n\t\tlines.push(truncateToWidth(summary, width));\n\t\tlines.push(\"\");\n\n\t\t// Render legend on the RIGHT of the graph if there is space.\n\t\tconst graphWidth = Math.max(0, ...graphLines.map((l) => visibleWidth(l)));\n\t\tconst sep = 2;\n\t\tconst legendWidth = width - graphWidth - sep;\n\t\tconst showSideLegend = legendWidth >= 22;\n\n\t\tif (showSideLegend) {\n\t\t\tconst legendBlock: string[] = [];\n\t\t\tlegendBlock.push(dim(\"Top models (30d palette):\"));\n\t\t\tlegendBlock.push(...legendItems);\n\t\t\t// Fit into 7 rows (same as graph). If too many, show a final \"+N more\" line.\n\t\t\tconst maxLegendRows = graphLines.length;\n\t\t\tlet legendLines = legendBlock.slice(0, maxLegendRows);\n\t\t\tif (legendBlock.length > maxLegendRows) {\n\t\t\t\tconst remaining = legendBlock.length - (maxLegendRows - 1);\n\t\t\t\tlegendLines = [...legendBlock.slice(0, maxLegendRows - 1), dim(`+${remaining} more`)];\n\t\t\t}\n\t\t\twhile (legendLines.length < graphLines.length) legendLines.push(\"\");\n\n\t\t\tconst padRightAnsi = (s: string, target: number): string => {\n\t\t\t\tconst w = visibleWidth(s);\n\t\t\t\treturn w >= target ? s : s + \" \".repeat(target - w);\n\t\t\t};\n\n\t\t\tfor (let i = 0; i < graphLines.length; i++) {\n\t\t\t\tconst left = padRightAnsi(graphLines[i] ?? \"\", graphWidth);\n\t\t\t\tconst right = truncateToWidth(legendLines[i] ?? \"\", Math.max(0, legendWidth));\n\t\t\t\tlines.push(truncateToWidth(left + \" \".repeat(sep) + right, width));\n\t\t\t}\n\t\t} else {\n\t\t\t// Fallback: graph only (legend will be shown below).\n\t\t\tfor (const gl of graphLines) lines.push(truncateToWidth(gl, width));\n\t\t\tlines.push(\"\");\n\t\t\t// Compact legend below, left-aligned.\n\t\t\tlines.push(truncateToWidth(dim(\"Top models (30d palette):\"), width));\n\t\t\tfor (const it of legendItems) lines.push(truncateToWidth(it, width));\n\t\t}\n\n\t\tlines.push(\"\");\n\t\tfor (const tl of tableLines) lines.push(truncateToWidth(tl, width));\n\n\t\t// Ensure no overly long lines (truncateToWidth already), but keep at least 1 line.\n\t\tthis.cachedWidth = width;\n\t\tthis.cachedLines = lines.map((l) => (visibleWidth(l) > width ? truncateToWidth(l, width) : l));\n\t\treturn this.cachedLines;\n\t}\n}\n\nexport default function sessionBreakdownExtension(pi: ExtensionAPI) {\n\tpi.registerCommand(\"session-breakdown\", {\n\t\tdescription: \"Interactive breakdown of last 7/30/90 days of ~/.pi session usage (sessions/messages/tokens + cost by model)\",\n\t\thandler: async (_args, ctx: ExtensionContext) => {\n\t\t\tif (!ctx.hasUI) {\n\t\t\t\t// Non-interactive fallback: just notify.\n\t\t\t\tconst data = await computeBreakdown(undefined);\n\t\t\t\tconst range = data.ranges.get(30)!;\n\t\t\t\tpi.sendMessage(\n\t\t\t\t\t{\n\t\t\t\t\t\tcustomType: \"session-breakdown\",\n\t\t\t\t\t\tcontent: `Session breakdown (non-interactive)\\n${rangeSummary(range, 30, \"sessions\")}`,\n\t\t\t\t\t\tdisplay: true,\n\t\t\t\t\t},\n\t\t\t\t\t{ triggerTurn: false },\n\t\t\t\t);\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tlet aborted = false;\n\t\t\tconst data = await ctx.ui.custom((tui, theme, _kb, done) => {\n\t\t\t\tconst baseMessage = \"Analyzing sessions (last 90 days)…\";\n\t\t\t\tconst loader = new BorderedLoader(tui, theme, baseMessage);\n\n\t\t\t\tconst startedAt = Date.now();\n\t\t\t\tconst progress: BreakdownProgressState = {\n\t\t\t\t\tphase: \"scan\",\n\t\t\t\t\tfoundFiles: 0,\n\t\t\t\t\tparsedFiles: 0,\n\t\t\t\t\ttotalFiles: 0,\n\t\t\t\t\tcurrentFile: undefined,\n\t\t\t\t};\n\n\t\t\t\tconst renderMessage = (): string => {\n\t\t\t\t\tconst elapsed = ((Date.now() - startedAt) / 1000).toFixed(1);\n\t\t\t\t\tif (progress.phase === \"scan\") {\n\t\t\t\t\t\treturn `${baseMessage} scanning (${formatCount(progress.foundFiles)} files) · ${elapsed}s`;\n\t\t\t\t\t}\n\t\t\t\t\tif (progress.phase === \"parse\") {\n\t\t\t\t\t\treturn `${baseMessage} parsing (${formatCount(progress.parsedFiles)}/${formatCount(progress.totalFiles)}) · ${elapsed}s`;\n\t\t\t\t\t}\n\t\t\t\t\treturn `${baseMessage} finalizing · ${elapsed}s`;\n\t\t\t\t};\n\n\t\t\t\tlet intervalId: NodeJS.Timeout | null = null;\n\t\t\t\tconst stopTicker = () => {\n\t\t\t\t\tif (intervalId) {\n\t\t\t\t\t\tclearInterval(intervalId);\n\t\t\t\t\t\tintervalId = null;\n\t\t\t\t\t}\n\t\t\t\t};\n\n\t\t\t\t// Update every 0.5s so long-running scans show some visible progress.\n\t\t\t\tsetBorderedLoaderMessage(loader, renderMessage());\n\t\t\t\tintervalId = setInterval(() => {\n\t\t\t\t\tsetBorderedLoaderMessage(loader, renderMessage());\n\t\t\t\t}, 500);\n\n\t\t\t\tloader.onAbort = () => {\n\t\t\t\t\taborted = true;\n\t\t\t\t\tstopTicker();\n\t\t\t\t\tdone(null);\n\t\t\t\t};\n\n\t\t\t\tcomputeBreakdown(loader.signal, (update) => Object.assign(progress, update))\n\t\t\t\t\t.then((d) => {\n\t\t\t\t\t\tstopTicker();\n\t\t\t\t\t\tif (!aborted) done(d);\n\t\t\t\t\t})\n\t\t\t\t\t.catch((err) => {\n\t\t\t\t\t\tstopTicker();\n\t\t\t\t\t\tconsole.error(\"session-breakdown: failed to analyze sessions\", err);\n\t\t\t\t\t\tif (!aborted) done(null);\n\t\t\t\t\t});\n\n\t\t\t\treturn loader;\n\t\t\t});\n\n\t\t\tif (!data) {\n\t\t\t\tctx.ui.notify(aborted ? \"Cancelled\" : \"Failed to analyze sessions\", aborted ? \"info\" : \"error\");\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tawait ctx.ui.custom((tui, _theme, _kb, done) => {\n\t\t\t\treturn new BreakdownComponent(data, tui, done);\n\t\t\t});\n\t\t},\n\t});\n}\n" }, { "path": "agents/pi/extensions/webfetch.ts", "content": "/**\n * WebFetch Extension\n *\n * Fetches web content and converts to markdown, text, or HTML for agent consumption.\n * Use when URLs are mentioned in conversation to retrieve their content.\n */\n\nimport type { ExtensionAPI } from \"@mariozechner/pi-coding-agent\";\nimport { Type } from \"@sinclair/typebox\";\nimport { StringEnum } from \"@mariozechner/pi-ai\";\nimport TurndownService from \"turndown\";\n\nconst MAX_RESPONSE_SIZE = 5 * 1024 * 1024; // 5MB\nconst DEFAULT_TIMEOUT = 30 * 1000; // 30 seconds\nconst MAX_TIMEOUT = 120 * 1000; // 2 minutes\n\n// Turndown instance for HTML to Markdown conversion\nconst turndownService = new TurndownService({\n headingStyle: \"atx\",\n hr: \"---\",\n bulletListMarker: \"-\",\n codeBlockStyle: \"fenced\",\n emDelimiter: \"*\",\n});\n\n// Remove script/style/meta/link/media tags\nturndownService.remove([\n \"script\", \"style\", \"meta\", \"link\", \"noscript\",\n \"img\", \"svg\", \"picture\", \"figure\", \"canvas\",\n \"video\", \"audio\", \"source\", \"track\", \"embed\", \"object\", \"iframe\",\n]);\n\nexport default function (pi: ExtensionAPI) {\n pi.registerTool({\n name: \"webfetch\",\n label: \"WebFetch\",\n description:\n \"Fetch web content and convert to markdown, text, or HTML for analysis. \" +\n \"Use when URLs are mentioned in conversation to retrieve their content. \" +\n \"HTTP URLs are automatically upgraded to HTTPS. \" +\n \"Images and binary content return empty text.\",\n\n parameters: Type.Object({\n url: Type.String({ description: \"The URL to fetch content from\" }),\n format: Type.Optional(\n StringEnum([\"markdown\", \"text\", \"html\"] as const, {\n description: \"Output format: markdown (default), text, or html\",\n }),\n ),\n timeout: Type.Optional(\n Type.Number({\n description: \"Timeout in seconds (max 120, default 30)\",\n }),\n ),\n }),\n\n async execute(_toolCallId, params, signal, _onUpdate, ctx) {\n const format = params.format ?? \"markdown\";\n let url = params.url;\n\n // Validate and normalize URL\n if (url.startsWith(\"http://\")) {\n url = url.replace(\"http://\", \"https://\");\n }\n if (!url.startsWith(\"https://\")) {\n ctx.ui.notify(\"Invalid URL: must start with http:// or https://\", \"error\");\n return {\n content: [{ type: \"text\", text: \"\" }],\n details: { url: params.url, format, error: \"Invalid URL\" },\n };\n }\n\n const timeout = Math.min(\n (params.timeout ?? DEFAULT_TIMEOUT / 1000) * 1000,\n MAX_TIMEOUT,\n );\n\n // Create abort controller that combines signal and timeout\n const controller = new AbortController();\n const timeoutId = setTimeout(() => controller.abort(), timeout);\n\n // Link external signal if provided\n if (signal) {\n signal.addEventListener(\"abort\", () => controller.abort());\n }\n\n try {\n const response = await fetch(url, {\n signal: controller.signal,\n headers: {\n \"User-Agent\":\n \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36\",\n Accept:\n \"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8\",\n \"Accept-Language\": \"en-US,en;q=0.9\",\n },\n });\n\n clearTimeout(timeoutId);\n\n if (!response.ok) {\n ctx.ui.notify(`HTTP error ${response.status}: ${response.statusText}`, \"error\");\n return {\n content: [{ type: \"text\", text: \"\" }],\n details: {\n url,\n format,\n error: `HTTP ${response.status}`,\n },\n };\n }\n\n // Check content length header\n const contentLength = response.headers.get(\"content-length\");\n if (contentLength && parseInt(contentLength) > MAX_RESPONSE_SIZE) {\n ctx.ui.notify(\"Response too large (>5MB)\", \"error\");\n return {\n content: [{ type: \"text\", text: \"\" }],\n details: { url, format, error: \"Response too large\" },\n };\n }\n\n const contentType = response.headers.get(\"content-type\") || \"\";\n const mime = contentType.split(\";\")[0]?.trim().toLowerCase() || \"\";\n\n // Skip binary/image content - return empty for agent\n if (\n mime.startsWith(\"image/\") ||\n mime.startsWith(\"video/\") ||\n mime.startsWith(\"audio/\") ||\n mime.startsWith(\"application/pdf\") ||\n mime.startsWith(\"application/zip\") ||\n mime.startsWith(\"application/octet-stream\")\n ) {\n return {\n content: [{ type: \"text\", text: \"\" }],\n details: { url, format, contentType: mime, skipped: true },\n };\n }\n\n const arrayBuffer = await response.arrayBuffer();\n\n if (arrayBuffer.byteLength > MAX_RESPONSE_SIZE) {\n ctx.ui.notify(\"Response too large (>5MB)\", \"error\");\n return {\n content: [{ type: \"text\", text: \"\" }],\n details: { url, format, error: \"Response too large\" },\n };\n }\n\n let text = new TextDecoder().decode(arrayBuffer);\n\n if (mime.includes(\"text/html\")) {\n text = stripMediaTags(text);\n }\n\n // Process based on format\n let output = \"\";\n switch (format) {\n case \"markdown\": {\n if (mime.includes(\"text/html\")) {\n output = turndownService.turndown(text);\n } else {\n output = text;\n }\n break;\n }\n case \"text\": {\n if (mime.includes(\"text/html\")) {\n output = htmlToText(text);\n } else {\n output = text;\n }\n break;\n }\n case \"html\": {\n output = text;\n break;\n }\n }\n\n // Clean up whitespace\n output = output.trim();\n\n return {\n content: [{ type: \"text\", text: output }],\n details: { url, format, contentType: mime },\n };\n } catch (error) {\n clearTimeout(timeoutId);\n\n if (error instanceof Error) {\n if (error.name === \"AbortError\") {\n ctx.ui.notify(\"Request timed out or was cancelled\", \"error\");\n return {\n content: [{ type: \"text\", text: \"\" }],\n details: { url, format, error: \"Timeout or cancelled\" },\n };\n }\n ctx.ui.notify(`Fetch error: ${error.message}`, \"error\");\n return {\n content: [{ type: \"text\", text: \"\" }],\n details: { url, format, error: error.message },\n };\n }\n\n ctx.ui.notify(\"Unknown error occurred\", \"error\");\n return {\n content: [{ type: \"text\", text: \"\" }],\n details: { url, format, error: \"Unknown error\" },\n };\n }\n },\n });\n}\n\n// Strip media and embed tags from raw HTML before conversion\nfunction stripMediaTags(html: string): string {\n return (\n html\n .replace(/]*>[\\s\\S]*?<\\/script>/gi, \"\")\n .replace(/]*>[\\s\\S]*?<\\/style>/gi, \"\")\n .replace(//gi, \"\")\n .replace(/]*>/gi, \"\")\n .replace(//gi, \"\")\n .replace(//gi, \"\")\n .replace(//gi, \"\")\n .replace(//gi, \"\")\n .replace(//gi, \"\")\n .replace(//gi, \"\")\n .replace(//gi, \"\")\n .replace(/]*>/gi, \"\")\n .replace(/]*>/gi, \"\")\n .replace(/]*>/gi, \"\")\n );\n}\n\n// Simple HTML to text conversion (no turndown for text format)\nfunction htmlToText(html: string): string {\n return (\n html\n // Replace common block elements with newlines\n .replace(/<\\/p>/gi, \"\\n\\n\")\n .replace(//gi, \"\\n\")\n .replace(/<\\/div>/gi, \"\\n\")\n .replace(/<\\/h[1-6]>/gi, \"\\n\\n\")\n .replace(/<\\/li>/gi, \"\\n\")\n // Remove all remaining tags\n .replace(/<[^>]+>/g, \"\")\n // Decode common HTML entities\n .replace(/ /g, \" \")\n .replace(/&/g, \"&\")\n .replace(/</g, \"<\")\n .replace(/>/g, \">\")\n .replace(/"/g, '\"')\n .replace(/'/g, \"'\")\n // Clean up whitespace\n .replace(/\\n{3,}/g, \"\\n\\n\")\n .trim()\n );\n}\n" }, { "path": "agents/pi/extensions/whimsical-timer.ts", "content": "import type { AssistantMessage } from \"@mariozechner/pi-ai\";\nimport type { ExtensionAPI } from \"@mariozechner/pi-coding-agent\";\n\nconst messages = [\n \"Schlepping...\",\n \"Combobulating...\",\n \"Doing...\",\n \"Channelling...\",\n \"Vibing...\",\n \"Concocting...\",\n \"Spelunking...\",\n \"Transmuting...\",\n \"Imagining...\",\n \"Pontificating...\",\n \"Whirring...\",\n \"Cogitating...\",\n \"Honking...\",\n \"Noodling...\",\n \"Percolating...\",\n \"Ruminating...\",\n \"Simmering...\",\n \"Marinating...\",\n \"Fermenting...\",\n \"Gestating...\",\n \"Hatching...\",\n \"Brewing...\",\n \"Steeping...\",\n \"Contemplating...\",\n \"Musing...\",\n \"Pondering...\",\n \"Dithering...\",\n \"Faffing...\",\n \"Puttering...\",\n \"Tinkering...\",\n \"Wrangling...\",\n \"Discombobulating...\",\n \"Recombobulating...\",\n \"Befuddling...\",\n \"Snorkeling...\",\n \"Yodeling...\",\n \"Zigzagging...\",\n \"Somersaulting...\",\n \"Canoodling...\",\n \"Schmoozing...\",\n \"Skedaddling...\",\n \"Scampering...\",\n \"Swashbuckling...\",\n \"Effervescing...\",\n \"Bubbling...\",\n \"Enchanting...\",\n \"Mesmerizing...\",\n \"Sparkling...\",\n \"Scintillating...\",\n \"Synthesizing...\",\n \"Procrastinating...\",\n \"Dillydallying...\",\n \"Lollygagging...\",\n \"Sleuthing...\",\n \"Rummaging...\",\n \"Foraging...\",\n \"Vamoosing...\",\n \"Absconding...\",\n \"Jamming...\",\n \"Freestyling...\",\n \"Frolicking...\",\n \"Wibbling...\",\n \"Wobbling...\",\n \"Bonking...\",\n \"Squelching...\",\n \"Burbling...\",\n \"Whooshing...\",\n \"Clunking...\",\n \"Rustling...\",\n \"Bustling...\",\n \"Doodling...\",\n \"Squiggling...\",\n \"Slithering...\",\n \"Bouldering...\",\n \"Tottering...\",\n \"Jittering...\",\n \"Twittering...\",\n \"Chattering...\",\n \"Splattering...\",\n \"Hammering...\",\n \"Stammering...\",\n \"Shimmering...\",\n \"Glimmering...\",\n \"Skimming...\",\n \"Drumming...\",\n \"Fumbling...\",\n \"Grumbling...\",\n \"Mumbling...\",\n \"Rumbling...\",\n \"Stumbling...\",\n \"Crumbling...\",\n \"Tangling...\",\n \"Jangling...\",\n \"Mingling...\",\n \"Jingling...\",\n \"Bribing the compiler...\",\n \"Tickling the stack...\",\n \"Massaging the heap...\",\n \"Summoning semicolons...\",\n \"Herding pointers...\",\n \"Untangling spaghetti...\",\n \"Polishing the algorithms...\",\n \"Waxing philosophical...\",\n \"Reading tea leaves...\",\n \"Warming up the hamsters...\",\n \"Caffeinating...\",\n \"Squinting at the problem...\",\n \"Staring into the abyss...\",\n \"Communing with the machine spirit...\",\n \"Reticulating splines...\",\n \"Calibrating the flux capacitor...\",\n];\n\nlet agentStartMs: number | null = null;\nlet intervalMs: number | null = null;\nlet timerInterval: ReturnType | null = null;\nlet currentMessage: string | null = null;\n\nfunction pickRandom(): string {\n return messages[Math.floor(Math.random() * messages.length)];\n}\n\nfunction formatDuration(ms: number): string {\n const seconds = Math.floor(ms / 1000);\n const mins = Math.floor(seconds / 60);\n const secs = seconds % 60;\n if (mins > 0) return String(mins) + \"m \" + String(secs) + \"s\";\n return String(secs) + \"s\";\n}\n\nfunction isAssistantMessage(message: unknown): message is AssistantMessage {\n if (!message || typeof message !== \"object\") return false;\n return (message as { role?: unknown }).role === \"assistant\";\n}\n\nexport default function (pi: ExtensionAPI) {\n pi.on(\"agent_start\", () => {\n agentStartMs = Date.now();\n });\n\n pi.on(\"turn_start\", async (_event, ctx) => {\n intervalMs = Date.now();\n currentMessage = pickRandom();\n\n ctx.ui.setWorkingMessage(currentMessage);\n\n timerInterval = setInterval(() => {\n if (intervalMs === null || currentMessage === null) return;\n const elapsedMs = Date.now() - intervalMs;\n ctx.ui.setWorkingMessage(currentMessage + \" (\" + formatDuration(elapsedMs) + \")\");\n }, 1000);\n });\n\n pi.on(\"turn_end\", async (_event, ctx) => {\n currentMessage = null;\n ctx.ui.setWorkingMessage();\n });\n\n pi.on(\"agent_end\", (event, ctx) => {\n if (!ctx.hasUI) return;\n if (agentStartMs === null) return;\n\n intervalMs = null;\n if (timerInterval !== null) {\n clearInterval(timerInterval);\n timerInterval = null;\n }\n\n const elapsedMs = Date.now() - agentStartMs;\n agentStartMs = null;\n if (elapsedMs <= 0) return;\n\n let output = 0;\n for (const msg of event.messages) {\n if (!isAssistantMessage(msg)) continue;\n output += msg.usage.output || 0;\n }\n\n if (output <= 0) return;\n\n const tps = (output / (elapsedMs / 1000)).toFixed(1);\n const msg = \"TPS: \" + tps + \" tok/s took \" + formatDuration(elapsedMs);\n ctx.ui.notify(msg, \"info\");\n });\n}\n" }, { "path": "agents/pi/mcp.json", "content": "{\n \"mcpServers\": {\n \"exa\": {\n \"url\": \"https://mcp.exa.ai/mcp\"\n },\n \"fff\": {\n \"command\": \"fff-mcp\",\n \"directTools\": true,\n \"lifecycle\": \"keep-alive\"\n }\n }\n}\n" }, { "path": "agents/pi/models.json", "content": "{\n \"providers\": {\n \"openrouter\": {\n \"modelOverrides\": {\n \"minimax/minimax-m2.5\": {\n \"name\": \"Minimax M2.5 RR\",\n \"compat\": {\n \"openRouterRouting\": {\n \"only\": [\"sambanova\", \"fireworks\", \"friendli\"]\n }\n }\n },\n \"moonshotai/kimi-k2.5\": {\n \"name\": \"Kimi K2.5 RR\",\n \"compat\": {\n \"openRouterRouting\": {\n \"only\": [\"fireworks\", \"together\"]\n }\n }\n },\n \"z-ai/glm-5\": {\n \"name\": \"GLM 5 RR\",\n \"compat\": {\n \"openRouterRouting\": {\n \"only\": [\"together\", \"friendli\"]\n }\n }\n }\n }\n },\n \"opencode-go\": {\n \"apiKey\": \"!pass show opencode-go\",\n \"baseUrl\": \"https://opencode.ai/zen/go/v1\",\n \"models\": [\n {\n \"id\": \"minimax-m2.7\",\n \"name\": \"MiniMax M2.7\",\n \"api\": \"anthropic-messages\",\n \"provider\": \"opencode-go\",\n \"baseUrl\": \"https://opencode.ai/zen/go\",\n \"reasoning\": true,\n \"input\": [\"text\"],\n \"cost\": {\n \"input\": 0.3,\n \"output\": 1.2,\n \"cacheRead\": 0.03,\n \"cacheWrite\": 0\n },\n \"contextWindow\": 204800,\n \"maxTokens\": 131072\n },\n {\n \"id\": \"glm-5\",\n \"name\": \"GLM 5\",\n \"api\": \"openai-completions\",\n \"provider\": \"opencode-go\",\n \"reasoning\": true,\n \"input\": [\"text\"],\n \"cost\": {\n \"input\": 1,\n \"output\": 3.2,\n \"cacheRead\": 0.2,\n \"cacheWrite\": 0\n },\n \"contextWindow\": 204800,\n \"maxTokens\": 131072\n },\n {\n \"id\": \"kimi-k2.5\",\n \"name\": \"Kimi K2.5\",\n \"api\": \"openai-completions\",\n \"provider\": \"opencode-go\",\n \"reasoning\": true,\n \"input\": [\"text\", \"image\"],\n \"cost\": {\n \"input\": 0.6,\n \"output\": 3.0,\n \"cacheRead\": 0.1,\n \"cacheWrite\": 0\n },\n \"contextWindow\": 256000,\n \"maxTokens\": 256000\n }\n ]\n }\n }\n}\n" }, { "path": "agents/pi/package.json", "content": "{\n \"name\": \"nil\",\n \"peerDependencies\": {\n \"@mariozechner/pi-ai\": \"*\",\n \"@mariozechner/pi-coding-agent\": \"*\",\n \"@mariozechner/pi-tui\": \"*\",\n \"@sinclair/typebox\": \"*\",\n \"turndown\": \"^7.2.2\",\n \"koffi\": \"^2.11.0\"\n },\n \"private\": true,\n \"type\": \"module\"\n}\n" }, { "path": "agents/pi/settings.json", "content": "{\n \"lastChangelogVersion\": \"0.70.6\",\n \"defaultProvider\": \"deepseek\",\n \"defaultModel\": \"deepseek-v4-flash\",\n \"defaultThinkingLevel\": \"minimal\",\n \"theme\": \"rose-pine-dawn\",\n \"quietStartup\": true,\n \"packages\": [\n \"./extensions/pi-codemode\",\n \"npm:@plannotator/pi-extension\",\n \"git:github.com/SamuelLHuber/pi-fff\",\n \"npm:pi-boomerang\"\n ],\n \"editorPaddingX\": 0,\n \"autocompleteMaxVisible\": 10,\n \"transport\": \"auto\",\n \"doubleEscapeAction\": \"tree\",\n \"enabledModels\": [],\n \"hideThinkingBlock\": false\n}" }, { "path": "agents/pi/themes/rose-pine-dawn.json", "content": "{\n \"$schema\": \"https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json\",\n \"name\": \"rose-pine-dawn\",\n \"vars\": {\n \"base\": \"#faf4ed\",\n \"surface\": \"#fffaf3\",\n \"overlay\": \"#f2e9e1\",\n \"muted\": \"#9893a5\",\n \"subtle\": \"#797593\",\n \"text\": \"#575279\",\n \"love\": \"#b4637a\",\n \"gold\": \"#ea9d34\",\n \"rose\": \"#d7827e\",\n \"pine\": \"#286983\",\n \"foam\": \"#56949f\",\n \"iris\": \"#907aa9\"\n },\n \"colors\": {\n \"accent\": \"iris\",\n \"border\": \"subtle\",\n \"borderAccent\": \"pine\",\n \"borderMuted\": \"overlay\",\n \"success\": \"pine\",\n \"error\": \"love\",\n \"warning\": \"gold\",\n \"muted\": \"muted\",\n \"dim\": \"subtle\",\n \"text\": \"text\",\n \"thinkingText\": \"muted\",\n\n \"selectedBg\": \"overlay\",\n \"userMessageBg\": \"surface\",\n \"userMessageText\": \"text\",\n \"customMessageBg\": \"overlay\",\n \"customMessageText\": \"text\",\n \"customMessageLabel\": \"iris\",\n \"toolPendingBg\": \"overlay\",\n \"toolSuccessBg\": \"surface\",\n \"toolErrorBg\": \"overlay\",\n \"toolTitle\": \"iris\",\n \"toolOutput\": \"muted\",\n\n \"mdHeading\": \"rose\",\n \"mdLink\": \"foam\",\n \"mdLinkUrl\": \"subtle\",\n \"mdCode\": \"iris\",\n \"mdCodeBlock\": \"text\",\n \"mdCodeBlockBorder\": \"overlay\",\n \"mdQuote\": \"muted\",\n \"mdQuoteBorder\": \"subtle\",\n \"mdHr\": \"overlay\",\n \"mdListBullet\": \"rose\",\n\n \"toolDiffAdded\": \"pine\",\n \"toolDiffRemoved\": \"love\",\n \"toolDiffContext\": \"muted\",\n\n \"syntaxComment\": \"muted\",\n \"syntaxKeyword\": \"pine\",\n \"syntaxFunction\": \"rose\",\n \"syntaxVariable\": \"gold\",\n \"syntaxString\": \"foam\",\n \"syntaxNumber\": \"gold\",\n \"syntaxType\": \"iris\",\n \"syntaxOperator\": \"pine\",\n \"syntaxPunctuation\": \"subtle\",\n\n \"thinkingOff\": \"muted\",\n \"thinkingMinimal\": \"subtle\",\n \"thinkingLow\": \"pine\",\n \"thinkingMedium\": \"foam\",\n \"thinkingHigh\": \"iris\",\n \"thinkingXhigh\": \"love\",\n\n \"bashMode\": \"pine\"\n }\n}\n" }, { "path": "agents/pi/treesitter.ts", "content": "import path from \"node:path\";\nimport fs from \"node:fs/promises\";\nimport { createWriteStream } from \"node:fs\";\nimport os from \"node:os\";\nimport https from \"node:https\";\nimport Parser from \"tree-sitter\";\nimport { createPicker } from \"../create-picker\";\nimport type { PickerContext } from \"../types\";\n\ninterface ParserConfig {\n /** Language identifier (e.g., \"typescript\", \"rust\") */\n language: string;\n /** File extensions to scan (e.g., [\".ts\", \".tsx\"]) */\n extensions: string[];\n /** URL to download the parser WASM */\n url?: string;\n /** Optional local path to parser (instead of URL) */\n localPath?: string;\n}\n\ninterface Symbol {\n name: string;\n kind: string;\n file: string;\n line: number;\n column: number;\n}\n\n/** Simple LRU cache with max size limit */\nclass LRUCache {\n private cache = new Map();\n private maxSize: number;\n\n constructor(maxSize: number) {\n this.maxSize = maxSize;\n }\n\n get(key: K): V | undefined {\n const value = this.cache.get(key);\n if (value !== undefined) {\n // Move to end (most recently used)\n this.cache.delete(key);\n this.cache.set(key, value);\n }\n return value;\n }\n\n set(key: K, value: V): void {\n if (this.cache.has(key)) {\n this.cache.delete(key);\n } else if (this.cache.size >= this.maxSize) {\n // Remove least recently used (first item)\n const firstKey = this.cache.keys().next().value;\n if (firstKey !== undefined) {\n this.cache.delete(firstKey);\n }\n }\n this.cache.set(key, value);\n }\n\n has(key: K): boolean {\n return this.cache.has(key);\n }\n\n clear(): void {\n this.cache.clear();\n }\n\n get size(): number {\n return this.cache.size;\n }\n}\n\n// Cache for parsed symbols per language - limited to 10 entries to prevent unbounded growth\nconst symbolCache = new LRUCache(10);\nconst runtimeCache = new Map();\nlet parsersDir: string | null = null;\nlet queriesDir: string | null = null;\n\nasync function getParsersDir(): Promise {\n if (!parsersDir) {\n parsersDir = path.join(os.homedir(), \".pi\", \"agent\", \"parsers\");\n await fs.mkdir(parsersDir, { recursive: true });\n }\n return parsersDir;\n}\n\nasync function getQueriesDir(): Promise {\n if (!queriesDir) {\n queriesDir = path.join(os.homedir(), \".pi\", \"agent\", \"queries\");\n await fs.mkdir(queriesDir, { recursive: true });\n }\n return queriesDir;\n}\n\nasync function downloadFile(url: string, dest: string): Promise {\n return new Promise((resolve) => {\n const file = createWriteStream(dest);\n https\n .get(url, (res) => {\n if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {\n downloadFile(res.headers.location, dest).then(resolve);\n return;\n }\n if (res.statusCode !== 200) {\n resolve(false);\n return;\n }\n res.pipe(file);\n file.on(\"finish\", () => {\n file.close(() => resolve(true));\n });\n })\n .on(\"error\", () => {\n fs.unlink(dest).catch(() => {});\n resolve(false);\n });\n });\n}\n\nasync function ensureParser(config: ParserConfig): Promise {\n if (config.localPath) {\n try {\n await fs.access(config.localPath);\n return config.localPath;\n } catch {\n // local path doesn't exist, continue\n }\n }\n\n if (!config.url) {\n return null;\n }\n\n const parsersDir = await getParsersDir();\n const fileName = `${config.language}.wasm`;\n const destPath = path.join(parsersDir, fileName);\n\n try {\n await fs.access(destPath);\n return destPath;\n } catch {\n // doesn't exist, download it\n }\n\n const success = await downloadFile(config.url, destPath);\n return success ? destPath : null;\n}\n\nasync function walkDir(dir: string, extensions: string[], files: string[] = []): Promise {\n try {\n const entries = await fs.readdir(dir, { withFileTypes: true });\n for (const entry of entries) {\n const fullPath = path.join(dir, entry.name);\n if (entry.isDirectory()) {\n if (entry.name === \"node_modules\" || entry.name === \".git\" || entry.name.startsWith(\".\")) {\n continue;\n }\n await walkDir(fullPath, extensions, files);\n } else if (entry.isFile()) {\n const ext = path.extname(entry.name);\n if (extensions.includes(ext)) {\n files.push(fullPath);\n }\n }\n }\n } catch (err) {\n console.error(\"[pi-ckers] Error walking directory:\", err);\n }\n return files;\n}\n\nasync function findFiles(cwd: string, extensions: string[]): Promise {\n return walkDir(cwd, extensions);\n}\n\nasync function readQueryFile(filePath: string): Promise {\n try {\n return await fs.readFile(filePath, \"utf8\");\n } catch {\n return null;\n }\n}\n\n/** Check if a path is a directory */\nasync function isDirectory(filePath: string): Promise {\n try {\n const stat = await fs.stat(filePath);\n return stat.isDirectory();\n } catch {\n return false;\n }\n}\n\n/** Default discovery: looks for {language}.scm in search paths, then default dir */\nasync function defaultDiscoverQuery(\n language: string,\n searchPaths: string[],\n defaultDir: string\n): Promise {\n // Search custom paths first (priority order)\n for (const searchPath of searchPaths) {\n const isDir = await isDirectory(searchPath);\n const queryFile = isDir\n ? path.join(searchPath, `${language}.scm`)\n : searchPath;\n const content = await readQueryFile(queryFile);\n if (content) return content;\n }\n\n // Fallback to default queries dir\n const queryFile = path.join(defaultDir, `${language}.scm`);\n return readQueryFile(queryFile);\n}\n\nasync function loadQuery(\n language: string,\n queriesDirs: string[] | QueryDiscovery | undefined\n): Promise {\n const defaultDir = await getQueriesDir();\n\n // If it's a function, use it as custom discovery\n if (typeof queriesDirs === \"function\") {\n return queriesDirs({\n language,\n defaultDir,\n readFile: readQueryFile,\n });\n }\n\n // Otherwise use default discovery with array of paths\n return defaultDiscoverQuery(language, queriesDirs ?? [], defaultDir);\n}\n\nasync function parseFileWithTreesitter(\n filePath: string,\n runtime: { parser: Parser; query: Parser.Query },\n): Promise {\n const symbols: Symbol[] = [];\n\n try {\n const sourceCode = await fs.readFile(filePath, \"utf8\");\n const tree = runtime.parser.parse(sourceCode);\n const matches = runtime.query.matches(tree.rootNode);\n\n for (const match of matches) {\n for (const capture of match.captures) {\n const node = capture.node;\n const captureName = capture.name;\n\n symbols.push({\n name: node.text,\n kind: captureName,\n file: filePath,\n line: node.startPosition.row + 1,\n column: node.startPosition.column,\n });\n }\n }\n } catch (err) {\n // If tree-sitter fails, return empty\n console.error(`[pi-ckers] Error parsing file ${filePath}:`, err);\n }\n\n return symbols;\n}\n\nasync function parseWorkspace(\n config: ParserConfig,\n cwd: string,\n maxFiles: number,\n notify: (msg: string, type: \"info\" | \"error\") => void,\n queriesDirs: string[] | QueryDiscovery | undefined\n): Promise {\n const cacheKey = `${config.language}:${cwd}`;\n if (symbolCache.has(cacheKey)) {\n return symbolCache.get(cacheKey)!;\n }\n\n // Load query file - required\n const queryText = await loadQuery(config.language, queriesDirs);\n if (!queryText) {\n // No query file, no symbols\n return [];\n }\n\n // Ensure parser is available\n const parserPath = await ensureParser(config);\n if (!parserPath) {\n notify(`Tree-sitter parser not available for ${config.language}`, \"error\");\n return [];\n }\n\n const files = await findFiles(cwd, config.extensions);\n const allSymbols: Symbol[] = [];\n\n let runtime = runtimeCache.get(config.language);\n if (!runtime) {\n const parser = new Parser();\n const loadedLanguage = await Parser.Language.load(parserPath);\n parser.setLanguage(loadedLanguage);\n runtime = {\n parser,\n query: loadedLanguage.query(queryText),\n };\n runtimeCache.set(config.language, runtime);\n }\n\n for (const file of files.slice(0, maxFiles)) {\n const symbols = await parseFileWithTreesitter(file, runtime);\n allSymbols.push(...symbols);\n }\n\n symbolCache.set(cacheKey, allSymbols);\n return allSymbols;\n}\n\nfunction filterSymbols(symbols: Symbol[], query: string): Symbol[] {\n const lowerQuery = query.toLowerCase();\n return symbols\n .filter((s) => s.name.toLowerCase().includes(lowerQuery))\n .slice(0, 20);\n}\n\nfunction formatSymbolValue(symbol: Symbol, isQuotedPrefix: boolean): string {\n const fileName = path.basename(symbol.file);\n const location = `${fileName}:${symbol.line}`;\n const value = `${symbol.name} (${location})`;\n\n if (!isQuotedPrefix && !value.includes(\" \")) {\n return `@ts:${value}`;\n }\n return `@ts:\"${value}\"`;\n}\n\nexport interface QueryDiscoveryContext {\n /** Language identifier (e.g., \"typescript\") */\n language: string;\n /** Default fallback directory (~/.pi/agent/queries) */\n defaultDir: string;\n /** Read file helper - returns null if not found */\n readFile: (filePath: string) => Promise;\n}\n\n/** Custom function to discover query files. Return the query text or null. */\nexport type QueryDiscovery = (ctx: QueryDiscoveryContext) => Promise;\n\nexport interface TreesitterPickerOptions {\n /** Parser configurations for different languages */\n parsers: ParserConfig[];\n /** Maximum number of files to scan per language (default: 100) */\n maxFiles?: number;\n /** Refresh interval in milliseconds (default: 60000) */\n refreshInterval?: number;\n /** Directories or files to search for query files, or a function that returns them.\n *\n * - string[]: Array of directories or file paths to search. For directories,\n * looks for {language}.scm. For files, reads them directly.\n * - function: Custom discovery that returns the query text directly.\n *\n * Falls back to ~/.pi/agent/queries/{language}.scm if not found.\n */\n queriesDirs?: string[] | QueryDiscovery;\n}\n\n/**\n * Create a treesitter workspace symbols picker for @ts: completions.\n *\n * Query files are loaded from ~/.pi/agent/queries/{language}.scm by default.\n *\n * Use queriesDirs to customize:\n * - string[]: Directories or specific files to search\n * - function: Custom discovery logic returning query text directly\n *\n * Parsers are downloaded on-demand to ~/.pi/agent/parsers/\n *\n * @example\n * ```typescript\n * import { tsWorkspaceSymbolsPicker } from \"@elianiva/pi-ckers/builtin/treesitter\";\n * import path from \"node:path\";\n *\n * // Simple: Custom directories (looks for {language}.scm in each)\n * const picker = tsWorkspaceSymbolsPicker({\n * parsers: [...],\n * queriesDirs: [\"/home/user/.config/nvim/queries\"]\n * });\n *\n * // Advanced: Custom discovery for nvim-treesitter structure\n * const nvimPicker = tsWorkspaceSymbolsPicker({\n * parsers: [...],\n * queriesDirs: async ({ language, defaultDir, readFile }) => {\n * // Look for locals.scm in nvim-treesitter structure\n * const nvimPath = path.join(\n * \"/Users/elianiva/.local/share/nvim/lazy/nvim-treesitter/queries\",\n * language,\n * \"locals.scm\"\n * );\n * const content = await readFile(nvimPath);\n * if (content) return content;\n *\n * // Fallback to default\n * return readFile(path.join(defaultDir, `${language}.scm`));\n * }\n * });\n * ```\n */\nexport const tsWorkspaceSymbolsPicker = (options: TreesitterPickerOptions) => {\n const maxFiles = options.maxFiles ?? 100;\n const refreshInterval = options.refreshInterval ?? 60000;\n const queriesDirs = options.queriesDirs;\n let refreshTimer: ReturnType | null = null;\n let notify: (msg: string, type: \"info\" | \"error\") => void = console.error;\n let currentCwd: string = \"\";\n\n return createPicker({\n type: \"sync\",\n prefix: \"@ts:\",\n minQueryLength: 1,\n\n init: async (ctx) => {\n currentCwd = ctx.cwd;\n notify = ctx.ui.notify.bind(ctx.ui);\n\n await getQueriesDir();\n await getParsersDir();\n\n for (const config of options.parsers) {\n await parseWorkspace(config, ctx.cwd, maxFiles, notify, queriesDirs);\n }\n\n if (refreshTimer) {\n clearInterval(refreshTimer);\n }\n refreshTimer = setInterval(async () => {\n if (!currentCwd) return;\n symbolCache.clear();\n for (const config of options.parsers) {\n await parseWorkspace(config, currentCwd, maxFiles, notify, queriesDirs);\n }\n }, refreshInterval);\n },\n\n search: (query: string, ctx: PickerContext) => {\n const allSymbols: Symbol[] = [];\n\n for (const config of options.parsers) {\n const cacheKey = `${config.language}:${ctx.cwd}`;\n const symbols = symbolCache.get(cacheKey);\n if (symbols) {\n allSymbols.push(...symbols);\n }\n }\n\n if (allSymbols.length === 0) {\n return null;\n }\n\n const filtered = filterSymbols(allSymbols, query);\n if (filtered.length === 0) {\n return null;\n }\n\n return filtered.map((symbol) => {\n const fileName = path.basename(symbol.file);\n return {\n value: formatSymbolValue(symbol, ctx.isQuotedPrefix),\n label: symbol.name,\n description: `${symbol.kind} · ${fileName}:${symbol.line}`,\n };\n });\n },\n\n clearCache: () => {\n symbolCache.clear();\n runtimeCache.clear();\n },\n\n destroy: () => {\n symbolCache.clear();\n runtimeCache.clear();\n if (refreshTimer) {\n clearInterval(refreshTimer);\n refreshTimer = null;\n }\n currentCwd = \"\";\n },\n });\n};\n" }, { "path": "agents/skills/build-feature/SKILL.md", "content": "---\nname: build-feature\ndescription: Use when creating or developing a feature, this contains a focused instructions for building features.\n---\n\n## Rules\n- Make sure you're certain from all ambiguities, otherwise ask for clarification\n- If there's a plan, follow it and ask for clarification if needed\n- Follow the Tracer Bullets to build a small, focused, end-to-end slice of the feature\n\n## Tracer Bullets\nWhen building features, build a tiny, end-to-end slice of the feature first, seek feedback, then expand out from there.\nTracer bullets comes from the Pragmatic Programmer. When building systems, you want to write code that gets you feedback as quickly as possible.\nTracer bullets are small slices of functionality that go through all layers of the system, allowing you to test and validate your approach early.\nThis helps in identifying potential issues and ensures that the overall architecture is sound before investing significant time in development.\n" }, { "path": "agents/skills/code-review/SKILL.md", "content": "---\nname: code-review\nversion: 1.0.0\ndescription: Code review entire project\n---\n\n# Code Review\n\nAct as a highly critical and analytical code reviewer.\n\n## Process\n\n- Provide detailed feedback on code quality, correctness, and maintainability\n- Offer suggestions for improvements and potential alternatives\n- Ensure code is readable, maintainable, and efficient\n\n$ARGUMENTS\n" }, { "path": "agents/skills/debugging/SKILL.md", "content": "---\nname: debugging\ndescription: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause investigation, pattern analysis, hypothesis testing, implementation) that ensures understanding before attempting solutions\n---\n\n# Systematic Debugging\n\n## Overview\n\nRandom fixes waste time and create new bugs. Quick patches mask underlying issues.\n\n**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.\n\n**Violating the letter of this process is violating the spirit of debugging.**\n\n## The Iron Law\n\n```\nNO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST\n```\n\nIf you haven't completed Phase 1, you cannot propose fixes.\n\n## When to Use\n\nUse for ANY technical issue:\n\n- Test failures\n- Bugs in production\n- Unexpected behavior\n- Performance problems\n- Build failures\n- Integration issues\n\n**Use this ESPECIALLY when:**\n\n- Under time pressure (emergencies make guessing tempting)\n- \"Just one quick fix\" seems obvious\n- You've already tried multiple fixes\n- Previous fix didn't work\n- You don't fully understand the issue\n\n**Don't skip when:**\n\n- Issue seems simple (simple bugs have root causes too)\n- You're in a hurry (rushing guarantees rework)\n- Manager wants it fixed NOW (systematic is faster than thrashing)\n\n## The Four Phases\n\nYou MUST complete each phase before proceeding to the next.\n\n### Phase 1: Root Cause Investigation\n\n**BEFORE attempting ANY fix:**\n\n1. **Read Error Messages Carefully**\n\n - Don't skip past errors or warnings\n - They often contain the exact solution\n - Read stack traces completely\n - Note line numbers, file paths, error codes\n\n2. **Reproduce Consistently**\n\n - Can you trigger it reliably?\n - What are the exact steps?\n - Does it happen every time?\n - If not reproducible → gather more data, don't guess\n\n3. **Check Recent Changes**\n\n - What changed that could cause this?\n - Git diff, recent commits\n - New dependencies, config changes\n - Environmental differences\n\n4. **Gather Evidence in Multi-Component Systems**\n\n **WHEN system has multiple components (CI → build → signing, API → service → database):**\n\n **BEFORE proposing fixes, add diagnostic instrumentation:**\n\n ```\n For EACH component boundary:\n - Log what data enters component\n - Log what data exits component\n - Verify environment/config propagation\n - Check state at each layer\n\n Run once to gather evidence showing WHERE it breaks\n THEN analyze evidence to identify failing component\n THEN investigate that specific component\n ```\n\n **Example (multi-layer system):**\n\n ```bash\n # Layer 1: Workflow\n echo \"=== Secrets available in workflow: ===\"\n echo \"IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}\"\n\n # Layer 2: Build script\n echo \"=== Env vars in build script: ===\"\n env | grep IDENTITY || echo \"IDENTITY not in environment\"\n\n # Layer 3: Signing script\n echo \"=== Keychain state: ===\"\n security list-keychains\n security find-identity -v\n\n # Layer 4: Actual signing\n codesign --sign \"$IDENTITY\" --verbose=4 \"$APP\"\n ```\n\n **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)\n\n5. **Trace Data Flow**\n\n **WHEN error is deep in call stack:**\n\n **REQUIRED SUB-SKILL:** Use superpowers root-cause-tracing for backward tracing technique\n\n **Quick version:**\n\n - Where does bad value originate?\n - What called this with bad value?\n - Keep tracing up until you find the source\n - Fix at source, not at symptom\n\n### Phase 2: Pattern Analysis\n\n**Find the pattern before fixing:**\n\n1. **Find Working Examples**\n\n - Locate similar working code in same codebase\n - What works that's similar to what's broken?\n\n2. **Compare Against References**\n\n - If implementing pattern, read reference implementation COMPLETELY\n - Don't skim - read every line\n - Understand the pattern fully before applying\n\n3. **Identify Differences**\n\n - What's different between working and broken?\n - List every difference, however small\n - Don't assume \"that can't matter\"\n\n4. **Understand Dependencies**\n - What other components does this need?\n - What settings, config, environment?\n - What assumptions does it make?\n\n### Phase 3: Hypothesis and Testing\n\n**Scientific method:**\n\n1. **Form Single Hypothesis**\n\n - State clearly: \"I think X is the root cause because Y\"\n - Write it down\n - Be specific, not vague\n\n2. **Test Minimally**\n\n - Make the SMALLEST possible change to test hypothesis\n - One variable at a time\n - Don't fix multiple things at once\n\n3. **Verify Before Continuing**\n\n - Did it work? Yes → Phase 4\n - Didn't work? Form NEW hypothesis\n - DON'T add more fixes on top\n\n4. **When You Don't Know**\n - Say \"I don't understand X\"\n - Don't pretend to know\n - Ask for help\n - Research more\n\n### Phase 4: Implementation\n\n**Fix the root cause, not the symptom:**\n\n1. **Decide on Testing Strategy**\n\n **Auto-decide based on complexity:**\n\n - **Write test for**: Complex algorithms, business logic, data transformations where bugs are likely\n - **Skip test for**: UI components, React hooks, simple CRUD, straightforward mappings, anything you're 100% certain is correct\n - **Test type**: Only deterministic unit tests - no integration tests, no complex mocking, no async complexity\n\n **If writing test:**\n\n - Simplest possible reproduction\n - Automated test that fails before fix\n - Verify logic, not implementation details\n\n **If skipping test:**\n\n - Verify fix with typecheck/lint\n - Manual verification for UI changes\n - Code review confidence that fix is correct\n\n2. **Implement Single Fix**\n\n - Address the root cause identified\n - ONE change at a time\n - No \"while I'm here\" improvements\n - No bundled refactoring\n\n3. **Verify Fix**\n\n **If test was written:**\n\n - Test passes now?\n - No other tests broken?\n\n **If no test:**\n\n - Typecheck passes?\n - Lint clean?\n - Manual verification confirms fix?\n\n **Always check:**\n\n - Issue actually resolved?\n - No regressions in related functionality?\n\n4. **If Fix Doesn't Work**\n\n - STOP\n - Count: How many fixes have you tried?\n - If < 3: Return to Phase 1, re-analyze with new information\n - **If ≥ 3: STOP and question the architecture (step 5 below)**\n - DON'T attempt Fix #4 without architectural discussion\n\n5. **If 3+ Fixes Failed: Question Architecture**\n\n **Pattern indicating architectural problem:**\n\n - Each fix reveals new shared state/coupling/problem in different place\n - Fixes require \"massive refactoring\" to implement\n - Each fix creates new symptoms elsewhere\n\n **STOP and question fundamentals:**\n\n - Is this pattern fundamentally sound?\n - Are we \"sticking with it through sheer inertia\"?\n - Should we refactor architecture vs. continue fixing symptoms?\n\n **Discuss with your human partner before attempting more fixes**\n\n This is NOT a failed hypothesis - this is a wrong architecture.\n\n## Red Flags - STOP and Follow Process\n\nIf you catch yourself thinking:\n\n- \"Quick fix for now, investigate later\"\n- \"Just try changing X and see if it works\"\n- \"Add multiple changes, run tests\"\n- \"It's probably X, let me fix that\"\n- \"I don't fully understand but this might work\"\n- \"Pattern says X but I'll adapt it differently\"\n- \"Here are the main problems: [lists fixes without investigation]\"\n- Proposing solutions before tracing data flow\n- **\"One more fix attempt\" (when already tried 2+)**\n- **Each fix reveals new problem in different place**\n- **Writing tests for UI components when you're certain the fix is correct**\n\n**ALL of these mean: STOP. Return to Phase 1.**\n\n**If 3+ fixes failed:** Question the architecture (see Phase 4.5)\n\n## your human partner's Signals You're Doing It Wrong\n\n**Watch for these redirections:**\n\n- \"Is that not happening?\" - You assumed without verifying\n- \"Will it show us...?\" - You should have added evidence gathering\n- \"Stop guessing\" - You're proposing fixes without understanding\n- \"Ultrathink this\" - Question fundamentals, not just symptoms\n- \"We're stuck?\" (frustrated) - Your approach isn't working\n\n**When you see these:** STOP. Return to Phase 1.\n\n## Common Rationalizations\n\n| Excuse | Reality |\n| -------------------------------------------- | ----------------------------------------------------------------------------- |\n| \"Issue is simple, don't need process\" | Simple issues have root causes too. Process is fast for simple bugs. |\n| \"Emergency, no time for process\" | Systematic debugging is FASTER than guess-and-check thrashing. |\n| \"Just try this first, then investigate\" | First fix sets the pattern. Do it right from the start. |\n| \"Multiple fixes at once saves time\" | Can't isolate what worked. Causes new bugs. |\n| \"Reference too long, I'll adapt the pattern\" | Partial understanding guarantees bugs. Read it completely. |\n| \"I see the problem, let me fix it\" | Seeing symptoms ≠ understanding root cause. |\n| \"One more fix attempt\" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |\n| \"UI fix doesn't need tests\" | Correct! UI components verified via typecheck/manual testing, not unit tests. |\n\n## Quick Reference\n\n| Phase | Key Activities | Success Criteria |\n| --------------------- | ------------------------------------------------------ | --------------------------- |\n| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |\n| **2. Pattern** | Find working examples, compare | Identify differences |\n| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |\n| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |\n\n## When Process Reveals \"No Root Cause\"\n\nIf systematic investigation reveals issue is truly environmental, timing-dependent, or external:\n\n1. You've completed the process\n2. Document what you investigated\n3. Implement appropriate handling (retry, timeout, error message)\n4. Add monitoring/logging for future investigation\n\n**But:** 95% of \"no root cause\" cases are incomplete investigation.\n\n## Integration with Other Skills\n\n**This skill requires using:**\n\n- **root-cause-tracing** - REQUIRED when error is deep in call stack (see Phase 1, Step 5)\n\n**Testing skills (when needed):**\n\n- **test-driven-development** (if available) - Use when fixing complex business logic that needs test coverage\n- Skip for UI components, simple CRUD, or anything verifiable via typecheck/manual testing\n\n## Real-World Impact\n\nFrom debugging sessions:\n\n- Systematic approach: 15-30 minutes to fix\n- Random fixes approach: 2-3 hours of thrashing\n- First-time fix rate: 95% vs 40%\n- New bugs introduced: Near zero vs common\n\n" }, { "path": "agents/skills/deslop/SKILL.md", "content": "---\nname: deslop\ndescription: Remove all AI-generated slop like useless comments, try/catch blocks, and casts\n---\n\nRemove all AI-generated slop, this includes:\n\n- Extra comments that a human wouldn't add or is inconsistent with the rest of the file, remove the what, keep the why\n- Extra defensive checks or try/catch blocks that are abnormal for that area of the codebase (especially if called by trusted / validated codepaths)\n- Casts to any to get around type issues\n- Any other style that is inconsistent with the file\n\nReport at the end with only a 1-3 sentence summary of what you changed\n" }, { "path": "agents/skills/effect-best-practices/SKILL.md", "content": "---\nname: effect-best-practices\ndescription: Enforces Effect-TS patterns for services, errors, layers, and atoms. Use when writing code with Effect.Service, Schema.TaggedError, Layer composition, or effect-atom React components.\nmetadata:\n version: 1.0.0\n---\n\n# Effect-TS Best Practices\n\nThis skill enforces opinionated, consistent patterns for Effect-TS codebases. These patterns optimize for type safety, testability, observability, and maintainability.\n\n## Quick Reference: Critical Rules\n\n| Category | DO | DON'T |\n|----------|-----|-------|\n| Services | `Effect.Service` with `accessors: true` | `Context.Tag` for business logic |\n| Dependencies | `dependencies: [Dep.Default]` in service | Manual `Layer.provide` at usage sites |\n| Errors | `Schema.TaggedError` with `message` field | Plain classes or generic Error |\n| Error Specificity | `UserNotFoundError`, `SessionExpiredError` | Generic `NotFoundError`, `BadRequestError` |\n| Error Handling | `catchTag`/`catchTags` | `catchAll` or `mapError` |\n| IDs | `Schema.UUID.pipe(Schema.brand(\"@App/EntityId\"))` | Plain `string` for entity IDs |\n| Functions | `Effect.fn(\"Service.method\")` | Anonymous generators |\n| Logging | `Effect.log` with structured data | `console.log` |\n| Config | `Config.*` with validation | `process.env` directly |\n| Options | `Option.match` with both cases | `Option.getOrThrow` |\n| Nullability | `Option` in domain types | `null`/`undefined` |\n| Atoms | `Atom.make` outside components | Creating atoms inside render |\n| Atom State | `Atom.keepAlive` for global state | Forgetting keepAlive for persistent state |\n| Atom Updates | `useAtomSet` in React components | `Atom.update` imperatively from React |\n| Atom Cleanup | `get.addFinalizer()` for side effects | Missing cleanup for event listeners |\n| Atom Results | `Result.builder` with `onErrorTag` | Ignoring loading/error states |\n\n## Service Definition Pattern\n\n**Always use `Effect.Service`** for business logic services. This provides automatic accessors, built-in `Default` layer, and proper dependency declaration.\n\n```typescript\nimport { Effect } from \"effect\"\n\nexport class UserService extends Effect.Service()(\"UserService\", {\n accessors: true,\n dependencies: [UserRepo.Default, CacheService.Default],\n effect: Effect.gen(function* () {\n const repo = yield* UserRepo\n const cache = yield* CacheService\n\n const findById = Effect.fn(\"UserService.findById\")(function* (id: UserId) {\n const cached = yield* cache.get(id)\n if (Option.isSome(cached)) return cached.value\n\n const user = yield* repo.findById(id)\n yield* cache.set(id, user)\n return user\n })\n\n const create = Effect.fn(\"UserService.create\")(function* (data: CreateUserInput) {\n const user = yield* repo.create(data)\n yield* Effect.log(\"User created\", { userId: user.id })\n return user\n })\n\n return { findById, create }\n }),\n}) {}\n\n// Usage - dependencies are already wired\nconst program = Effect.gen(function* () {\n const user = yield* UserService.findById(userId)\n return user\n})\n\n// At app root\nconst MainLive = Layer.mergeAll(UserService.Default, OtherService.Default)\n```\n\n**When `Context.Tag` is acceptable:**\n- Infrastructure with runtime injection (Cloudflare KV, worker bindings)\n- Factory patterns where resources are provided externally\n\nSee `references/service-patterns.md` for detailed patterns.\n\n## Error Definition Pattern\n\n**Always use `Schema.TaggedError`** for errors. This makes them serializable (required for RPC) and provides consistent structure.\n\n```typescript\nimport { Schema } from \"effect\"\nimport { HttpApiSchema } from \"@effect/platform\"\n\nexport class UserNotFoundError extends Schema.TaggedError()(\n \"UserNotFoundError\",\n {\n userId: UserId,\n message: Schema.String,\n },\n HttpApiSchema.annotations({ status: 404 }),\n) {}\n\nexport class UserCreateError extends Schema.TaggedError()(\n \"UserCreateError\",\n {\n message: Schema.String,\n cause: Schema.optional(Schema.String),\n },\n HttpApiSchema.annotations({ status: 400 }),\n) {}\n```\n\n**Error handling - use `catchTag`/`catchTags`:**\n\n```typescript\n// CORRECT - preserves type information\nyield* repo.findById(id).pipe(\n Effect.catchTag(\"DatabaseError\", (err) =>\n Effect.fail(new UserNotFoundError({ userId: id, message: \"Lookup failed\" }))\n ),\n Effect.catchTag(\"ConnectionError\", (err) =>\n Effect.fail(new ServiceUnavailableError({ message: \"Database unreachable\" }))\n ),\n)\n\n// CORRECT - multiple tags at once\nyield* effect.pipe(\n Effect.catchTags({\n DatabaseError: (err) => Effect.fail(new UserNotFoundError({ userId: id, message: err.message })),\n ValidationError: (err) => Effect.fail(new InvalidEmailError({ email: input.email, message: err.message })),\n }),\n)\n```\n\n### Prefer Explicit Over Generic Errors\n\n**Every distinct failure reason deserves its own error type.** Don't collapse multiple failure modes into generic HTTP errors.\n\n```typescript\n// WRONG - Generic errors lose information\nexport class NotFoundError extends Schema.TaggedError()(\n \"NotFoundError\",\n { message: Schema.String },\n HttpApiSchema.annotations({ status: 404 }),\n) {}\n\n// Then mapping everything to it:\nEffect.catchTags({\n UserNotFoundError: (err) => Effect.fail(new NotFoundError({ message: \"Not found\" })),\n ChannelNotFoundError: (err) => Effect.fail(new NotFoundError({ message: \"Not found\" })),\n MessageNotFoundError: (err) => Effect.fail(new NotFoundError({ message: \"Not found\" })),\n})\n// Frontend gets useless: { _tag: \"NotFoundError\", message: \"Not found\" }\n// Which resource? User? Channel? Message? Can't tell!\n```\n\n```typescript\n// CORRECT - Explicit domain errors with rich context\nexport class UserNotFoundError extends Schema.TaggedError()(\n \"UserNotFoundError\",\n { userId: UserId, message: Schema.String },\n HttpApiSchema.annotations({ status: 404 }),\n) {}\n\nexport class ChannelNotFoundError extends Schema.TaggedError()(\n \"ChannelNotFoundError\",\n { channelId: ChannelId, message: Schema.String },\n HttpApiSchema.annotations({ status: 404 }),\n) {}\n\nexport class SessionExpiredError extends Schema.TaggedError()(\n \"SessionExpiredError\",\n { sessionId: SessionId, expiredAt: Schema.DateTimeUtc, message: Schema.String },\n HttpApiSchema.annotations({ status: 401 }),\n) {}\n\n// Frontend can now show specific UI:\n// - UserNotFoundError → \"User doesn't exist\"\n// - ChannelNotFoundError → \"Channel was deleted\"\n// - SessionExpiredError → \"Your session expired. Please log in again.\"\n```\n\nSee `references/error-patterns.md` for error remapping and retry patterns.\n\n## Schema & Branded Types Pattern\n\n**Brand all entity IDs** for type safety across service boundaries:\n\n```typescript\nimport { Schema } from \"effect\"\n\n// Entity IDs - always branded\nexport const UserId = Schema.UUID.pipe(Schema.brand(\"@App/UserId\"))\nexport type UserId = Schema.Schema.Type\n\nexport const OrganizationId = Schema.UUID.pipe(Schema.brand(\"@App/OrganizationId\"))\nexport type OrganizationId = Schema.Schema.Type\n\n// Domain types - use Schema.Struct\nexport const User = Schema.Struct({\n id: UserId,\n email: Schema.String,\n name: Schema.String,\n organizationId: OrganizationId,\n createdAt: Schema.DateTimeUtc,\n})\nexport type User = Schema.Schema.Type\n\n// Input types for mutations\nexport const CreateUserInput = Schema.Struct({\n email: Schema.String.pipe(Schema.pattern(/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/)),\n name: Schema.String.pipe(Schema.minLength(1)),\n organizationId: OrganizationId,\n})\nexport type CreateUserInput = Schema.Schema.Type\n```\n\n**When NOT to brand:**\n- Simple strings that don't cross service boundaries (URLs, file paths)\n- Primitive config values\n\nSee `references/schema-patterns.md` for transforms and advanced patterns.\n\n## Function Pattern with Effect.fn\n\n**Always use `Effect.fn`** for service methods. This provides automatic tracing with proper span names:\n\n```typescript\n// CORRECT - Effect.fn with descriptive name\nconst findById = Effect.fn(\"UserService.findById\")(function* (id: UserId) {\n yield* Effect.annotateCurrentSpan(\"userId\", id)\n const user = yield* repo.findById(id)\n return user\n})\n\n// CORRECT - Effect.fn with multiple parameters\nconst transfer = Effect.fn(\"AccountService.transfer\")(\n function* (fromId: AccountId, toId: AccountId, amount: number) {\n yield* Effect.annotateCurrentSpan(\"fromId\", fromId)\n yield* Effect.annotateCurrentSpan(\"toId\", toId)\n yield* Effect.annotateCurrentSpan(\"amount\", amount)\n // ...\n }\n)\n```\n\n## Layer Composition\n\n**Declare dependencies in the service**, not at usage sites:\n\n```typescript\n// CORRECT - dependencies in service definition\nexport class OrderService extends Effect.Service()(\"OrderService\", {\n accessors: true,\n dependencies: [\n UserService.Default,\n ProductService.Default,\n PaymentService.Default,\n ],\n effect: Effect.gen(function* () {\n const users = yield* UserService\n const products = yield* ProductService\n const payments = yield* PaymentService\n // ...\n }),\n}) {}\n\n// At app root - simple merge\nconst AppLive = Layer.mergeAll(\n OrderService.Default,\n // Infrastructure layers (intentionally not in dependencies)\n DatabaseLive,\n RedisLive,\n)\n```\n\nSee `references/layer-patterns.md` for testing layers and config-dependent layers.\n\n## Option Handling\n\n**Never use `Option.getOrThrow`**. Always handle both cases explicitly:\n\n```typescript\n// CORRECT - explicit handling\nyield* Option.match(maybeUser, {\n onNone: () => Effect.fail(new UserNotFoundError({ userId, message: \"Not found\" })),\n onSome: (user) => Effect.succeed(user),\n})\n\n// CORRECT - with getOrElse for defaults\nconst name = Option.getOrElse(maybeName, () => \"Anonymous\")\n\n// CORRECT - Option.map for transformations\nconst upperName = Option.map(maybeName, (n) => n.toUpperCase())\n```\n\n## Effect Atom (Frontend State)\n\nEffect Atom provides reactive state management for React with Effect integration.\n\n### Basic Atoms\n\n```typescript\nimport { Atom } from \"@effect-atom/atom-react\"\n\n// Define atoms OUTSIDE components\nconst countAtom = Atom.make(0)\n\n// Use keepAlive for global state that should persist\nconst userPrefsAtom = Atom.make({ theme: \"dark\" }).pipe(Atom.keepAlive)\n\n// Atom families for per-entity state\nconst modalAtomFamily = Atom.family((type: string) =>\n Atom.make({ isOpen: false }).pipe(Atom.keepAlive)\n)\n```\n\n### React Integration\n\n```typescript\nimport { useAtomValue, useAtomSet, useAtom, useAtomMount } from \"@effect-atom/atom-react\"\n\nfunction Counter() {\n const count = useAtomValue(countAtom) // Read only\n const setCount = useAtomSet(countAtom) // Write only\n const [value, setValue] = useAtom(countAtom) // Read + write\n\n return \n}\n\n// Mount side-effect atoms without reading value\nfunction App() {\n useAtomMount(keyboardShortcutsAtom)\n return <>{children}\n}\n```\n\n### Handling Results with Result.builder\n\n**Use `Result.builder`** for rendering effectful atom results. It provides chainable error handling with `onErrorTag`:\n\n```typescript\nimport { Result } from \"@effect-atom/atom-react\"\n\nfunction UserProfile() {\n const userResult = useAtomValue(userAtom) // Result\n\n return Result.builder(userResult)\n .onInitial(() =>
Loading...
)\n .onErrorTag(\"NotFoundError\", () =>
User not found
)\n .onError((error) =>
Error: {error.message}
)\n .onSuccess((user) =>
Hello, {user.name}
)\n .render()\n}\n```\n\n### Atoms with Side Effects\n\n```typescript\nconst scrollYAtom = Atom.make((get) => {\n const onScroll = () => get.setSelf(window.scrollY)\n\n window.addEventListener(\"scroll\", onScroll)\n get.addFinalizer(() => window.removeEventListener(\"scroll\", onScroll)) // REQUIRED\n\n return window.scrollY\n}).pipe(Atom.keepAlive)\n```\n\nSee `references/effect-atom-patterns.md` for complete patterns including families, localStorage, and anti-patterns.\n\n## RPC & Cluster Patterns\n\nFor RPC contracts and cluster workflows, see:\n- `references/rpc-cluster-patterns.md` - RpcGroup, Workflow.make, Activity patterns\n\n## Anti-Patterns (Forbidden)\n\nThese patterns are **never acceptable**:\n\n```typescript\n// FORBIDDEN - runSync/runPromise inside services\nconst result = Effect.runSync(someEffect) // Never do this\n\n// FORBIDDEN - throw inside Effect.gen\nyield* Effect.gen(function* () {\n if (bad) throw new Error(\"No!\") // Use Effect.fail instead\n})\n\n// FORBIDDEN - catchAll losing type info\nyield* effect.pipe(Effect.catchAll(() => Effect.fail(new GenericError())))\n\n// FORBIDDEN - console.log\nconsole.log(\"debug\") // Use Effect.log\n\n// FORBIDDEN - process.env directly\nconst key = process.env.API_KEY // Use Config.string(\"API_KEY\")\n\n// FORBIDDEN - null/undefined in domain types\ntype User = { name: string | null } // Use Option\n```\n\nSee `references/anti-patterns.md` for the complete list with rationale.\n\n## Observability\n\n```typescript\n// Structured logging\nyield* Effect.log(\"Processing order\", { orderId, userId, amount })\n\n// Metrics\nconst orderCounter = Metric.counter(\"orders_processed\")\nyield* Metric.increment(orderCounter)\n\n// Config with validation\nconst config = Config.all({\n port: Config.integer(\"PORT\").pipe(Config.withDefault(3000)),\n apiKey: Config.secret(\"API_KEY\"),\n maxRetries: Config.integer(\"MAX_RETRIES\").pipe(\n Config.validate({ message: \"Must be positive\", validation: (n) => n > 0 })\n ),\n})\n```\n\nSee `references/observability-patterns.md` for metrics and tracing patterns.\n\n## Reference Files\n\nFor detailed patterns, consult these reference files in the `references/` directory:\n\n- `service-patterns.md` - Service definition, Effect.fn, Context.Tag exceptions\n- `error-patterns.md` - Schema.TaggedError, error remapping, retry patterns\n- `schema-patterns.md` - Branded types, transforms, Schema.Class\n- `layer-patterns.md` - Dependency composition, testing layers\n- `rpc-cluster-patterns.md` - RpcGroup, Workflow, Activity patterns\n- `effect-atom-patterns.md` - Atom, families, React hooks, Result handling\n- `anti-patterns.md` - Complete list of forbidden patterns\n- `observability-patterns.md` - Logging, metrics, config patterns\n" }, { "path": "agents/skills/effect-best-practices/references/anti-patterns.md", "content": "# Anti-Patterns (Forbidden)\n\nThese patterns are **never acceptable** in Effect-TS code. Each is listed with rationale and the correct alternative.\n\n## FORBIDDEN: Effect.runSync/runPromise Inside Services\n\n```typescript\n// FORBIDDEN\nexport class UserService extends Effect.Service()(\"UserService\", {\n effect: Effect.gen(function* () {\n const findById = (id: UserId) => {\n // Running effects synchronously breaks composition\n const user = Effect.runSync(repo.findById(id))\n return user\n }\n return { findById }\n }),\n}) {}\n```\n\n**Why:** Breaks Effect's composition model, loses error handling, can't be tested, loses tracing.\n\n**Correct:**\n```typescript\nconst findById = Effect.fn(\"UserService.findById\")(function* (id: UserId) {\n return yield* repo.findById(id)\n})\n```\n\n## FORBIDDEN: throw Inside Effect.gen\n\n```typescript\n// FORBIDDEN\nyield* Effect.gen(function* () {\n const user = yield* repo.findById(id)\n if (!user) {\n throw new Error(\"User not found\") // Bypasses Effect error channel\n }\n return user\n})\n```\n\n**Why:** Throws bypass Effect's error channel, can't be caught with `catchTag`, breaks type safety.\n\n**Correct:**\n```typescript\nyield* Effect.gen(function* () {\n const user = yield* repo.findById(id)\n if (!user) {\n return yield* Effect.fail(new UserNotFoundError({ userId: id, message: \"Not found\" }))\n }\n return user\n})\n```\n\n## FORBIDDEN: catchAll Losing Type Information\n\n```typescript\n// FORBIDDEN\nyield* someEffect.pipe(\n Effect.catchAll((err) =>\n Effect.fail(new GenericError({ message: \"Something failed\" }))\n )\n)\n```\n\n**Why:** Loses specific error information, makes debugging harder, prevents specific error handling downstream.\n\n**Correct:**\n```typescript\nyield* someEffect.pipe(\n Effect.catchTags({\n DatabaseError: (err) => Effect.fail(new ServiceUnavailableError({ message: err.message })),\n ValidationError: (err) => Effect.fail(new BadRequestError({ message: err.message })),\n }),\n)\n```\n\n## FORBIDDEN: any/unknown Casts\n\n```typescript\n// FORBIDDEN\nconst data = someValue as any\nconst result = (await fetch(url)) as unknown as MyType\n```\n\n**Why:** Completely bypasses type safety, can cause runtime errors, loses Effect's type guarantees.\n\n**Correct:**\n```typescript\n// Use Schema for parsing unknown data\nconst result = yield* Schema.decodeUnknown(MyType)(someValue)\n\n// Or explicit type guards\nif (isMyType(someValue)) {\n // Now safely typed\n}\n```\n\n## FORBIDDEN: Promise in Service Signatures\n\n```typescript\n// FORBIDDEN\nexport class UserService extends Effect.Service()(\"UserService\", {\n effect: Effect.gen(function* () {\n return {\n findById: async (id: UserId): Promise => {\n // Using Promise instead of Effect\n }\n }\n }),\n}) {}\n```\n\n**Why:** Loses Effect's error handling, can't compose with other Effects, loses tracing/metrics.\n\n**Correct:**\n```typescript\nconst findById = Effect.fn(\"UserService.findById\")(\n function* (id: UserId): Effect.Effect {\n // ...\n }\n)\n```\n\n## FORBIDDEN: console.log\n\n```typescript\n// FORBIDDEN\nconsole.log(\"Processing order:\", orderId)\nconsole.error(\"Error:\", error)\n```\n\n**Why:** Not structured, not captured by Effect's logging system, lost in production telemetry.\n\n**Correct:**\n```typescript\nyield* Effect.log(\"Processing order\", { orderId })\nyield* Effect.logError(\"Operation failed\", { error: String(error) })\n```\n\n## FORBIDDEN: process.env Directly\n\n```typescript\n// FORBIDDEN\nconst apiKey = process.env.API_KEY\nconst port = parseInt(process.env.PORT || \"3000\")\n```\n\n**Why:** No validation, no type safety, fails silently if missing, hard to test.\n\n**Correct:**\n```typescript\nconst config = yield* Config.all({\n apiKey: Config.secret(\"API_KEY\"),\n port: Config.integer(\"PORT\").pipe(Config.withDefault(3000)),\n})\n```\n\n## FORBIDDEN: null/undefined in Domain Types\n\n```typescript\n// FORBIDDEN\ntype User = {\n name: string\n bio: string | null\n avatar: string | undefined\n}\n```\n\n**Why:** Null/undefined handling is error-prone, loses the explicit \"absence\" semantics.\n\n**Correct:**\n```typescript\nconst User = Schema.Struct({\n name: Schema.String,\n bio: Schema.Option(Schema.String),\n avatar: Schema.Option(Schema.String),\n})\n```\n\n## FORBIDDEN: Option.getOrThrow\n\n```typescript\n// FORBIDDEN\nconst user = Option.getOrThrow(maybeUser)\nconst name = pipe(maybeName, Option.getOrThrow)\n```\n\n**Why:** Throws exceptions, bypasses Effect's error handling, fails at runtime instead of compile time.\n\n**Correct:**\n```typescript\n// Handle both cases explicitly\nyield* Option.match(maybeUser, {\n onNone: () => Effect.fail(new UserNotFoundError({ userId, message: \"Not found\" })),\n onSome: Effect.succeed,\n})\n\n// Or provide a default\nconst name = Option.getOrElse(maybeName, () => \"Anonymous\")\n\n// Or use Option.map for transformations\nconst upperName = Option.map(maybeName, (n) => n.toUpperCase())\n```\n\n## FORBIDDEN: Context.Tag for Business Services\n\n```typescript\n// FORBIDDEN\nexport class UserService extends Context.Tag(\"UserService\")<\n UserService,\n { findById: (id: UserId) => Effect.Effect }\n>() {\n static Default = Layer.effect(this, Effect.gen(function* () { ... }))\n}\n```\n\n**Why:** Requires manual layer creation, no built-in accessors, more boilerplate.\n\n**Correct:**\n```typescript\nexport class UserService extends Effect.Service()(\"UserService\", {\n accessors: true,\n dependencies: [...],\n effect: Effect.gen(function* () { ... }),\n}) {}\n```\n\n## FORBIDDEN: Ignoring Errors with orDie\n\n```typescript\n// FORBIDDEN (in most cases)\nyield* someEffect.pipe(Effect.orDie)\n```\n\n**Why:** Converts recoverable errors to defects (unrecoverable), loses error information.\n\n**Acceptable exceptions:**\n- Truly unrecoverable situations (invalid program state)\n- After exhausting all recovery options\n- In test setup code\n\n**Correct:**\n```typescript\n// Handle errors explicitly\nyield* someEffect.pipe(\n Effect.catchTag(\"RecoverableError\", (err) =>\n Effect.fail(new DomainError({ message: err.message }))\n ),\n)\n```\n\n## FORBIDDEN: mapError Instead of catchTag\n\n```typescript\n// FORBIDDEN\nyield* effect.pipe(\n Effect.mapError((err) => new GenericError({ message: String(err) }))\n)\n```\n\n**Why:** Loses error type information, can't discriminate between error types.\n\n**Correct:**\n```typescript\nyield* effect.pipe(\n Effect.catchTag(\"SpecificError\", (err) =>\n Effect.fail(new MappedError({ message: err.message }))\n ),\n)\n```\n\n## FORBIDDEN: Mixing Effect and Promise Chains\n\n```typescript\n// FORBIDDEN\nconst result = await someEffect.pipe(\n Effect.runPromise,\n).then(data => {\n // Mixing Promise chain with Effect\n return Effect.runPromise(anotherEffect(data))\n})\n```\n\n**Why:** Loses Effect composition benefits, error handling becomes inconsistent.\n\n**Correct:**\n```typescript\nconst program = Effect.gen(function* () {\n const data = yield* someEffect\n return yield* anotherEffect(data)\n})\n\nconst result = await Effect.runPromise(program)\n```\n\n## FORBIDDEN: Mutable State Without Ref\n\n```typescript\n// FORBIDDEN\nlet counter = 0\nconst increment = Effect.sync(() => { counter++ })\n```\n\n**Why:** Race conditions, not testable, not composable, breaks referential transparency.\n\n**Correct:**\n```typescript\nconst program = Effect.gen(function* () {\n const counter = yield* Ref.make(0)\n yield* Ref.update(counter, (n) => n + 1)\n return yield* Ref.get(counter)\n})\n```\n\n## FORBIDDEN: Using Date.now() or new Date() Directly\n\n```typescript\n// FORBIDDEN\nconst now = new Date()\nconst timestamp = Date.now()\n```\n\n**Why:** Not testable, introduces non-determinism, hard to mock in tests.\n\n**Correct:**\n```typescript\nimport { Clock } from \"effect\"\n\nconst now = yield* Clock.currentTimeMillis\nconst date = yield* Clock.currentTimeZone.pipe(\n Effect.map((tz) => new Date())\n)\n```\n" }, { "path": "agents/skills/effect-best-practices/references/effect-atom-patterns.md", "content": "# Effect Atom Patterns\n\nEffect Atom is a reactive state management library that integrates with Effect-TS. It provides atoms (reactive containers), automatic dependency tracking, and seamless React integration.\n\n## Core Concepts\n\n- **Atoms**: Reactive state containers with automatic dependency tracking\n- **Result**: Handles async/effectful computations with initial, success, and failure states\n- **Finalizers**: Built-in cleanup for resources and event listeners\n- **Families**: Dynamic atom creation for per-entity state\n\n## Creating Atoms\n\n### Basic Atoms\n\n```typescript\nimport { Atom } from \"@effect-atom/atom-react\"\n\n// Simple value atom\nconst countAtom = Atom.make(0)\n\n// With keepAlive - persists when no components subscribe\nconst persistentCountAtom = Atom.make(0).pipe(Atom.keepAlive)\n```\n\n**Rule:** Use `Atom.keepAlive` for global state that should persist across component unmounts.\n\n### Derived Atoms\n\n```typescript\nconst countAtom = Atom.make(0)\n\n// Derived using get function\nconst doubleCountAtom = Atom.make((get) => get(countAtom) * 2)\n\n// Derived using Atom.map\nconst tripleCountAtom = Atom.map(countAtom, (count) => count * 3)\n```\n\n### Atoms with Side Effects\n\n```typescript\n// Track window scroll position\nconst scrollYAtom = Atom.make((get) => {\n const onScroll = () => get.setSelf(window.scrollY)\n\n window.addEventListener(\"scroll\", onScroll)\n get.addFinalizer(() => window.removeEventListener(\"scroll\", onScroll))\n\n return window.scrollY\n}).pipe(Atom.keepAlive)\n```\n\n**Critical:**\n- Use `get.setSelf` to update the atom's own value\n- Always add finalizers with `get.addFinalizer()` to clean up side effects\n- Finalizers run when the atom is rebuilt or disposed\n\n### Atom.transform for Self-Updating Derived State\n\n```typescript\nconst resolvedThemeAtom = Atom.transform(themeAtom, (get) => {\n const theme = get(themeAtom)\n if (theme !== \"system\") return theme\n\n const matcher = window.matchMedia(\"(prefers-color-scheme: dark)\")\n\n const onChange = () => get.setSelf(matcher.matches ? \"dark\" : \"light\")\n\n matcher.addEventListener(\"change\", onChange)\n get.addFinalizer(() => matcher.removeEventListener(\"change\", onChange))\n\n return matcher.matches ? \"dark\" : \"light\"\n})\n```\n\n## Atom Families\n\nUse `Atom.family` for per-entity state:\n\n```typescript\nimport { Atom } from \"@effect-atom/atom-react\"\n\n// Create a family of atoms - one per channelId\nconst replyToMessageAtomFamily = Atom.family((channelId: string) =>\n Atom.make(null).pipe(Atom.keepAlive)\n)\n\n// Modal state family\ntype ModalType = \"settings\" | \"confirm\" | \"create\"\n\ninterface ModalState {\n type: ModalType\n isOpen: boolean\n metadata?: Record\n}\n\nconst modalAtomFamily = Atom.family((type: ModalType) =>\n Atom.make({\n type,\n isOpen: false,\n metadata: undefined,\n }).pipe(Atom.keepAlive)\n)\n```\n\n**Use families for:**\n- Per-resource state (users, channels, documents)\n- Modal instances\n- Form state per entity\n- Any parameterized state\n\n## React Integration\n\n### Reading Atom Values\n\n```typescript\nimport { useAtomValue } from \"@effect-atom/atom-react\"\n\nfunction Counter() {\n const count = useAtomValue(countAtom)\n return {count}\n}\n```\n\n### Updating Atom Values\n\n```typescript\nimport { useAtomSet } from \"@effect-atom/atom-react\"\n\nfunction IncrementButton() {\n const setCount = useAtomSet(countAtom)\n return (\n \n )\n}\n```\n\n### Reading and Writing Together\n\n```typescript\nimport { useAtom } from \"@effect-atom/atom-react\"\n\nfunction CounterControl() {\n const [count, setCount] = useAtom(countAtom)\n return (\n
\n {count}\n \n
\n )\n}\n```\n\n### Mounting Side-Effect Atoms\n\nUse `useAtomMount` to activate atoms without reading their value:\n\n```typescript\nimport { useAtomMount } from \"@effect-atom/atom-react\"\n\nfunction App() {\n // Activate side effects without subscribing to value\n useAtomMount(keyboardShortcutsAtom)\n useAtomMount(presenceTrackingAtom)\n useAtomMount(themeApplierAtom)\n\n return <>{children}\n}\n```\n\n## Working with Effects and Results\n\n### Effectful Atoms Return Result\n\n```typescript\nimport { Atom, Result } from \"@effect-atom/atom-react\"\nimport { Effect } from \"effect\"\n\nconst userAtom = Atom.make(\n Effect.gen(function* () {\n const response = yield* fetchUser()\n return response\n })\n) // Type: Atom>\n```\n\n### Handling Results with Result.builder (Recommended)\n\n**Use `Result.builder`** for rendering Result types. It provides a chainable API with granular error handling and type narrowing.\n\n```typescript\nimport { Result, useAtomValue } from \"@effect-atom/atom-react\"\n\nfunction UserProfile() {\n const userResult = useAtomValue(userAtom)\n\n return Result.builder(userResult)\n .onInitial(() =>
Loading...
)\n .onError((error) =>
Error: {error.message}
)\n .onSuccess((user) =>
Hello, {user.name}!
)\n .render()\n}\n```\n\n### Result.builder with Tagged Errors\n\n**Key advantage**: Handle specific error types with `onErrorTag`:\n\n```typescript\nfunction ResourceEmbed({ url }: { url: string }) {\n const resourceResult = useAtomValue(resourceAtom)\n\n return Result.builder(resourceResult)\n .onInitial(() => )\n .onErrorTag(\"NotFoundError\", (error) => (\n \n ))\n .onErrorTag(\"UnauthorizedError\", () => (\n \n ))\n .onErrorTag(\"RateLimitError\", (error) => (\n \n ))\n .onError((error) => (\n // Fallback for any other errors\n \n ))\n .onSuccess((data) => )\n .render()\n}\n```\n\n### Result.builder Methods\n\n| Method | Purpose |\n|--------|---------|\n| `onInitial(fn)` | Handle initial/loading state |\n| `onInitialOrWaiting(fn)` | Handle both initial and waiting states |\n| `onWaiting(fn)` | Handle waiting/refetching state |\n| `onSuccess(fn)` | Handle success with value |\n| `onError(fn)` | Handle any error |\n| `onErrorTag(tag, fn)` | Handle specific tagged error (removes from type) |\n| `onErrorIf(predicate, fn)` | Handle errors matching predicate |\n| `onFailure(fn)` | Handle failure with full Cause |\n| `onDefect(fn)` | Handle unexpected defects |\n| `render()` | Return result (null if unhandled initial) |\n| `orElse(fn)` | Provide fallback value |\n| `orNull()` | Return null for unhandled cases |\n\n### Extracting Values with orElse\n\nFor non-rendering use cases, extract values with `orElse`:\n\n```typescript\nfunction useRepositories() {\n const reposResult = useAtomValue(repositoriesAtom)\n\n // Extract array or empty fallback\n const repositories = Result.builder(reposResult)\n .onSuccess((data) => data.repositories)\n .orElse(() => [])\n\n return repositories\n}\n```\n\n### Result.getOrElse for Simple Extraction\n\nFor simple value extraction without error handling:\n\n```typescript\nfunction UserName() {\n const userResult = useAtomValue(userAtom)\n const user = Result.getOrElse(userResult, () => null)\n\n if (!user) return Loading...\n return {user.name}\n}\n```\n\n### When to Use Each Pattern\n\n| Pattern | Use Case |\n|---------|----------|\n| `Result.builder` | UI rendering with multiple error types |\n| `Result.builder + onErrorTag` | APIs with tagged errors (HttpApi, RPC) |\n| `Result.builder + orElse` | Extracting values with fallback |\n| `Result.getOrElse` | Simple value extraction |\n| `Result.match` | Simple 3-case exhaustive matching |\n\n### Accessing Results in Derived Atoms\n\n```typescript\nconst userProfileAtom = Atom.make(\n Effect.fnUntraced(function* (get: Atom.Context) {\n // Unwrap Result to get the value (waits for success)\n const user = yield* get.result(userAtom)\n const posts = yield* fetchUserPosts(user.id)\n return { user, posts }\n })\n)\n```\n\n## Batching Updates\n\nUse `Atom.batch` for multiple updates:\n\n```typescript\nconst openModal = (type: ModalType, metadata?: Record) => {\n Atom.batch(() => {\n Atom.update(modalAtomFamily(type), (state) => ({\n ...state,\n isOpen: true,\n metadata,\n }))\n })\n}\n```\n\n## localStorage Persistence\n\n```typescript\nimport { BrowserKeyValueStore } from \"@effect/platform-browser\"\nimport { Atom } from \"@effect-atom/atom-react\"\nimport { Schema } from \"effect\"\n\n// Create runtime with localStorage\nconst localStorageRuntime = Atom.runtime(BrowserKeyValueStore.layerLocalStorage)\n\n// Persisted atom with schema validation\nconst themeAtom = Atom.kvs({\n runtime: localStorageRuntime,\n key: \"app-theme\",\n schema: Schema.Literal(\"dark\", \"light\", \"system\"),\n defaultValue: () => \"system\" as const,\n})\n```\n\n## Anti-Patterns\n\n### FORBIDDEN: Creating Atoms Inside Components\n\n```typescript\n// WRONG - creates new atom on every render\nfunction Counter() {\n const countAtom = Atom.make(0) // New atom each render!\n const count = useAtomValue(countAtom)\n return
{count}
\n}\n\n// CORRECT - define atoms outside components\nconst countAtom = Atom.make(0)\n\nfunction Counter() {\n const count = useAtomValue(countAtom)\n return
{count}
\n}\n```\n\n### FORBIDDEN: Imperative Updates from React Components\n\n```typescript\n// WRONG - doesn't trigger React re-renders\nexport const openModal = (type: string) => {\n Atom.batch(() => {\n Atom.update(modalAtomFamily(type), (s) => ({ ...s, isOpen: true }))\n })\n}\n\nfunction Component() {\n return \n}\n\n// CORRECT - use hooks for React integration\nexport const useModal = (type: string) => {\n const state = useAtomValue(modalAtomFamily(type))\n const setState = useAtomSet(modalAtomFamily(type))\n\n const open = useCallback(() => {\n setState((prev) => ({ ...prev, isOpen: true }))\n }, [setState])\n\n const close = useCallback(() => {\n setState((prev) => ({ ...prev, isOpen: false }))\n }, [setState])\n\n return { isOpen: state.isOpen, open, close }\n}\n```\n\n**When imperative updates ARE acceptable:**\n- Event listeners outside React (keyboard shortcuts)\n- Effects running on atom changes\n- Non-UI state (analytics, logging)\n\n### FORBIDDEN: Missing Finalizers\n\n```typescript\n// WRONG - memory leak!\nconst scrollAtom = Atom.make((get) => {\n const onScroll = () => get.setSelf(window.scrollY)\n window.addEventListener(\"scroll\", onScroll)\n return window.scrollY\n})\n\n// CORRECT - cleanup registered\nconst scrollAtom = Atom.make((get) => {\n const onScroll = () => get.setSelf(window.scrollY)\n window.addEventListener(\"scroll\", onScroll)\n get.addFinalizer(() => window.removeEventListener(\"scroll\", onScroll))\n return window.scrollY\n})\n```\n\n### FORBIDDEN: Missing keepAlive for Global State\n\n```typescript\n// WRONG - state resets when component unmounts\nexport const modalStateAtom = Atom.make({ isOpen: false })\n\n// CORRECT - state persists\nexport const modalStateAtom = Atom.make({ isOpen: false }).pipe(Atom.keepAlive)\n```\n\n### FORBIDDEN: Ignoring Result Types\n\n```typescript\n// WRONG - doesn't handle loading/error states\nconst userResult = useAtomValue(userAtom)\nreturn
Hello, {userResult.name}
// Type error!\n\n// CORRECT - use Result.builder to handle all states\nconst userResult = useAtomValue(userAtom)\nreturn Result.builder(userResult)\n .onInitial(() =>
Loading...
)\n .onError((error) =>
Error: {error.message}
)\n .onSuccess((user) =>
Hello, {user.name}
)\n .render()\n```\n\n### FORBIDDEN: Updating State During Render\n\n```typescript\n// WRONG - side effect during render\nfunction Component() {\n const count = useAtomValue(countAtom)\n Atom.set(countAtom, count + 1) // Never do this!\n return
{count}
\n}\n\n// CORRECT - use effects or event handlers\nfunction Component() {\n const count = useAtomValue(countAtom)\n const setCount = useAtomSet(countAtom)\n\n useEffect(() => {\n setCount((c) => c + 1)\n }, [])\n\n return
{count}
\n}\n```\n\n## Performance Tips\n\n### Selective Re-rendering\n\n```typescript\n// WRONG - subscribes to entire state\nconst state = useAtomValue(appStateAtom)\nconst userName = state.user.name\n\n// CORRECT - derive focused atom\nconst userNameAtom = Atom.map(appStateAtom, (state) => state.user.name)\nconst userName = useAtomValue(userNameAtom)\n```\n\n### When to Use keepAlive\n\nUse `Atom.keepAlive` for:\n- Global application state\n- Modal/dialog state\n- User preferences\n- Authentication state\n- Frequently accessed derived state\n\nSkip `keepAlive` for:\n- Component-local state that should reset\n- Temporary form state\n- State tied to component lifecycle\n" }, { "path": "agents/skills/effect-best-practices/references/error-patterns.md", "content": "# Error Patterns\n\n## Why Explicit Error Types?\n\nGeneric errors like `BadRequestError` or `NotFoundError` seem convenient but create problems:\n\n| Generic Error | Problems |\n|--------------|----------|\n| `NotFoundError` | Which resource? How should frontend recover? |\n| `BadRequestError` | What's invalid? Can user fix it? |\n| `UnauthorizedError` | Session expired? Wrong credentials? Missing permission? |\n| `InternalServerError` | Retryable? User action needed? |\n\n**Explicit errors enable:**\n1. **Specific UI messages** - \"Your session expired\" vs generic \"Unauthorized\"\n2. **Targeted recovery** - Refresh token vs show login page\n3. **Better observability** - Group errors by specific type in dashboards\n4. **Type-safe handling** - `catchTag(\"SessionExpiredError\")` vs generic catch\n\n### Anti-Pattern: Generic Error Mapping\n\n```typescript\n// ❌ WRONG - Collapsing to generic HTTP errors\nexport class NotFoundError extends Schema.TaggedError()(\n \"NotFoundError\",\n { message: Schema.String },\n HttpApiSchema.annotations({ status: 404 }),\n) {}\n\n// At API boundaries:\nEffect.catchTags({\n UserNotFoundError: (err) => Effect.fail(new NotFoundError({ message: \"Not found\" })),\n ChannelNotFoundError: (err) => Effect.fail(new NotFoundError({ message: \"Not found\" })),\n MessageNotFoundError: (err) => Effect.fail(new NotFoundError({ message: \"Not found\" })),\n})\n\n// Frontend receives: { _tag: \"NotFoundError\", message: \"Not found\" }\n// - Can't show specific message (\"User doesn't exist\" vs \"Channel was deleted\")\n// - Can't take specific action (redirect to user search vs channel list)\n// - Debugging is harder (which resource was missing?)\n```\n\n```typescript\n// ✅ CORRECT - Keep explicit errors all the way to frontend\nexport class UserNotFoundError extends Schema.TaggedError()(\n \"UserNotFoundError\",\n { userId: UserId, message: Schema.String },\n HttpApiSchema.annotations({ status: 404 }),\n) {}\n\nexport class ChannelNotFoundError extends Schema.TaggedError()(\n \"ChannelNotFoundError\",\n { channelId: ChannelId, message: Schema.String },\n HttpApiSchema.annotations({ status: 404 }),\n) {}\n\n// Frontend can handle each case:\nResult.builder(result)\n .onErrorTag(\"UserNotFoundError\", (err) => )\n .onErrorTag(\"ChannelNotFoundError\", (err) => )\n .onErrorTag(\"SessionExpiredError\", () => )\n .render()\n```\n\n## Error Naming Conventions\n\n| Pattern | Example | Use For |\n|---------|---------|---------|\n| `{Entity}NotFoundError` | `UserNotFoundError`, `ChannelNotFoundError` | Resource lookups |\n| `{Entity}{Action}Error` | `UserCreateError`, `MessageUpdateError` | Mutations that fail |\n| `{Feature}Error` | `SessionExpiredError`, `RateLimitExceededError` | Feature-specific failures |\n| `{Integration}Error` | `WorkOSUserFetchError`, `StripePaymentError` | External service errors |\n| `Invalid{Field}Error` | `InvalidEmailError`, `InvalidPasswordError` | Validation failures |\n\n### Rich Error Context\n\nInclude context fields that help with debugging and UI handling:\n\n```typescript\n// Entity errors → include entity ID\nexport class UserNotFoundError extends Schema.TaggedError()(\n \"UserNotFoundError\",\n {\n userId: UserId, // Which user?\n message: Schema.String,\n },\n HttpApiSchema.annotations({ status: 404 }),\n) {}\n\n// Action errors → include input that failed\nexport class UserCreateError extends Schema.TaggedError()(\n \"UserCreateError\",\n {\n email: Schema.String, // What email failed?\n reason: Schema.String, // Why? \"duplicate\", \"invalid domain\"\n message: Schema.String,\n },\n HttpApiSchema.annotations({ status: 400 }),\n) {}\n\n// Integration errors → include service name and retryable flag\nexport class StripePaymentError extends Schema.TaggedError()(\n \"StripePaymentError\",\n {\n stripeErrorCode: Schema.String,\n retryable: Schema.Boolean,\n message: Schema.String,\n },\n HttpApiSchema.annotations({ status: 402 }),\n) {}\n\n// Auth errors → include expiry info\nexport class SessionExpiredError extends Schema.TaggedError()(\n \"SessionExpiredError\",\n {\n sessionId: SessionId,\n expiredAt: Schema.DateTimeUtc,\n message: Schema.String,\n },\n HttpApiSchema.annotations({ status: 401 }),\n) {}\n```\n\n## Schema.TaggedError for All Errors\n\n**Always use `Schema.TaggedError`** for defining errors. This provides:\n\n1. **Serialization** - Errors can be sent over RPC/network\n2. **Type safety** - `_tag` discriminator enables `catchTag`\n3. **Consistent structure** - All errors have predictable shape\n4. **HTTP status mapping** - Via `HttpApiSchema.annotations`\n\n### Basic Error Definition\n\n```typescript\nimport { Schema } from \"effect\"\nimport { HttpApiSchema } from \"@effect/platform\"\n\nexport class UserNotFoundError extends Schema.TaggedError()(\n \"UserNotFoundError\",\n {\n userId: UserId,\n message: Schema.String,\n },\n HttpApiSchema.annotations({ status: 404 }),\n) {}\n\nexport class UserCreateError extends Schema.TaggedError()(\n \"UserCreateError\",\n {\n message: Schema.String,\n cause: Schema.optional(Schema.String),\n },\n HttpApiSchema.annotations({ status: 400 }),\n) {}\n\nexport class UnauthorizedError extends Schema.TaggedError()(\n \"UnauthorizedError\",\n {\n message: Schema.String,\n },\n HttpApiSchema.annotations({ status: 401 }),\n) {}\n\nexport class ForbiddenError extends Schema.TaggedError()(\n \"ForbiddenError\",\n {\n message: Schema.String,\n requiredPermission: Schema.optional(Schema.String),\n },\n HttpApiSchema.annotations({ status: 403 }),\n) {}\n```\n\n### Required Fields\n\nEvery error should have:\n- `message: Schema.String` - Human-readable description\n- Relevant context fields (IDs, etc.)\n- Optional `cause: Schema.optional(Schema.String)` for error chains\n\n## Error Handling with catchTag/catchTags\n\n**Never use `catchAll` or `mapError`** when you can use `catchTag`/`catchTags`. These preserve type information and enable precise error handling.\n\n### catchTag for Single Error Types\n\n```typescript\nconst findUser = Effect.fn(\"UserService.findUser\")(function* (id: UserId) {\n return yield* repo.findById(id).pipe(\n Effect.catchTag(\"DatabaseError\", (err) =>\n Effect.fail(new UserNotFoundError({\n userId: id,\n message: `Database lookup failed: ${err.message}`,\n }))\n ),\n )\n})\n```\n\n### catchTags for Multiple Error Types\n\n```typescript\nconst processOrder = Effect.fn(\"OrderService.processOrder\")(function* (input: OrderInput) {\n return yield* validateAndProcess(input).pipe(\n Effect.catchTags({\n ValidationError: (err) =>\n Effect.fail(new OrderValidationError({\n message: err.message,\n field: err.field,\n })),\n PaymentError: (err) =>\n Effect.fail(new OrderPaymentError({\n message: `Payment failed: ${err.message}`,\n code: err.code,\n })),\n InventoryError: (err) =>\n Effect.fail(new OrderInventoryError({\n productId: err.productId,\n message: \"Insufficient inventory\",\n })),\n }),\n )\n})\n```\n\n### Why Not catchAll?\n\n```typescript\n// WRONG - Loses type information\nyield* effect.pipe(\n Effect.catchAll((err) =>\n Effect.fail(new InternalServerError({ message: \"Something failed\" }))\n )\n)\n\n// Problems:\n// 1. Can't distinguish error types downstream\n// 2. Hides useful error context\n// 3. Makes debugging harder\n// 4. Frontend can't show specific messages\n```\n\n## Error Remapping Pattern\n\nCreate reusable error remapping functions for common transformations:\n\n```typescript\nimport { Effect } from \"effect\"\n\nexport const withRemapDbErrors = (\n effect: Effect.Effect,\n context: { entityType: string; entityId: string }\n): Effect.Effect =>\n effect.pipe(\n Effect.catchTag(\"DatabaseError\", (err) =>\n Effect.fail(new EntityNotFoundError({\n entityType: context.entityType,\n entityId: context.entityId,\n message: `${context.entityType} not found`,\n }))\n ),\n Effect.catchTag(\"ConnectionError\", (err) =>\n Effect.fail(new ServiceUnavailableError({\n message: \"Database connection unavailable\",\n cause: err.message,\n }))\n ),\n )\n\n// Usage\nconst findUser = Effect.fn(\"UserService.findUser\")(function* (id: UserId) {\n return yield* repo.findById(id).pipe(\n withRemapDbErrors({ entityType: \"User\", entityId: id })\n )\n})\n```\n\n## Retryable Errors Pattern\n\nFor errors that may be transient, add a `retryable` property:\n\n```typescript\nexport class ServiceUnavailableError extends Schema.TaggedError()(\n \"ServiceUnavailableError\",\n {\n message: Schema.String,\n cause: Schema.optional(Schema.String),\n retryable: Schema.optionalWith(Schema.Boolean, { default: () => true }),\n },\n HttpApiSchema.annotations({ status: 503 }),\n) {}\n\nexport class RateLimitError extends Schema.TaggedError()(\n \"RateLimitError\",\n {\n message: Schema.String,\n retryAfter: Schema.optional(Schema.Number),\n retryable: Schema.optionalWith(Schema.Boolean, { default: () => true }),\n },\n HttpApiSchema.annotations({ status: 429 }),\n) {}\n\n// Non-retryable error\nexport class ValidationError extends Schema.TaggedError()(\n \"ValidationError\",\n {\n message: Schema.String,\n field: Schema.String,\n retryable: Schema.optionalWith(Schema.Boolean, { default: () => false }),\n },\n HttpApiSchema.annotations({ status: 400 }),\n) {}\n```\n\n### Retry Based on Error Property\n\n```typescript\nimport { Effect, Schedule } from \"effect\"\n\nconst withRetry = (\n effect: Effect.Effect\n): Effect.Effect =>\n effect.pipe(\n Effect.retry(\n Schedule.exponential(\"100 millis\").pipe(\n Schedule.intersect(Schedule.recurs(3)),\n Schedule.whileInput((err: E) => err.retryable === true),\n )\n ),\n )\n\n// Usage\nyield* callExternalApi(request).pipe(withRetry)\n```\n\n## Error Unions for Activities\n\nWhen defining workflow activities, use explicit error unions:\n\n```typescript\n// Activity error type - union of possible errors\nexport type GetChannelMembersError =\n | DatabaseError\n | ChannelNotFoundError\n\nexport class DatabaseError extends Schema.TaggedError()(\n \"DatabaseError\",\n {\n message: Schema.String,\n cause: Schema.optional(Schema.String),\n retryable: Schema.optionalWith(Schema.Boolean, { default: () => true }),\n },\n) {}\n\nexport class ChannelNotFoundError extends Schema.TaggedError()(\n \"ChannelNotFoundError\",\n {\n channelId: ChannelId,\n message: Schema.String,\n retryable: Schema.optionalWith(Schema.Boolean, { default: () => false }),\n },\n) {}\n\n// In activity definition\nyield* Activity.make({\n name: \"GetChannelMembers\",\n success: ChannelMembersResult,\n error: Schema.Union(DatabaseError, ChannelNotFoundError),\n execute: Effect.gen(function* () {\n // ...\n }),\n})\n```\n\n## HTTP Status Codes (Without Generic Errors)\n\n**Map HTTP status codes at the error level, not by creating generic error classes.** Each explicit error can have its own HTTP status.\n\n```typescript\n// ✅ CORRECT - Domain errors with HTTP status annotations\nexport class UserNotFoundError extends Schema.TaggedError()(\n \"UserNotFoundError\",\n { userId: UserId, message: Schema.String },\n HttpApiSchema.annotations({ status: 404 }), // Status on specific error\n) {}\n\nexport class ChannelNotFoundError extends Schema.TaggedError()(\n \"ChannelNotFoundError\",\n { channelId: ChannelId, message: Schema.String },\n HttpApiSchema.annotations({ status: 404 }), // Same status, different error\n) {}\n\nexport class SessionExpiredError extends Schema.TaggedError()(\n \"SessionExpiredError\",\n { sessionId: SessionId, expiredAt: Schema.DateTimeUtc, message: Schema.String },\n HttpApiSchema.annotations({ status: 401 }),\n) {}\n\nexport class InvalidCredentialsError extends Schema.TaggedError()(\n \"InvalidCredentialsError\",\n { message: Schema.String },\n HttpApiSchema.annotations({ status: 401 }), // Same status, different meaning\n) {}\n```\n\n```typescript\n// ❌ WRONG - Generic HTTP error classes\nexport class UnauthorizedError extends Schema.TaggedError()(\n \"UnauthorizedError\",\n { message: Schema.String },\n HttpApiSchema.annotations({ status: 401 }),\n) {}\n\n// Then mapping everything to it - loses critical information!\nEffect.catchTags({\n SessionExpiredError: (err) => Effect.fail(new UnauthorizedError({ message: \"Unauthorized\" })),\n InvalidCredentialsError: (err) => Effect.fail(new UnauthorizedError({ message: \"Unauthorized\" })),\n MissingTokenError: (err) => Effect.fail(new UnauthorizedError({ message: \"Unauthorized\" })),\n})\n// Frontend can't distinguish: expired session vs wrong password vs missing token\n```\n\n### When Generic Errors Are Acceptable\n\nGeneric errors are only acceptable for **truly unrecoverable internal errors** where:\n- The frontend can only show \"Something went wrong\"\n- No user action can fix it\n- You're hiding internal details for security\n\n```typescript\n// Acceptable for unrecoverable errors\nexport class InternalServerError extends Schema.TaggedError()(\n \"InternalServerError\",\n { message: Schema.String, requestId: Schema.optional(Schema.String) },\n HttpApiSchema.annotations({ status: 500 }),\n) {}\n\n// Use sparingly - only for truly unexpected errors\nEffect.catchAll((unexpectedError) =>\n Effect.fail(new InternalServerError({\n message: \"An unexpected error occurred\",\n requestId: context.requestId,\n }))\n)\n```\n\n## Error Logging\n\nLog errors with structured context:\n\n```typescript\nconst processWithLogging = Effect.fn(\"OrderService.process\")(function* (orderId: OrderId) {\n return yield* processOrder(orderId).pipe(\n Effect.tapError((err) =>\n Effect.log(\"Order processing failed\", {\n orderId,\n errorTag: err._tag,\n errorMessage: err.message,\n })\n ),\n )\n})\n```\n" }, { "path": "agents/skills/effect-best-practices/references/layer-patterns.md", "content": "# Layer Patterns\n\n## Dependencies in Effect.Service\n\n**Critical rule:** Always declare dependencies in the `dependencies` array of `Effect.Service`. This ensures proper composition and avoids \"leaked dependencies\" that require manual wiring at usage sites.\n\n### Correct Pattern\n\n```typescript\nexport class OrderService extends Effect.Service()(\"OrderService\", {\n accessors: true,\n dependencies: [\n UserService.Default,\n ProductService.Default,\n InventoryService.Default,\n PaymentService.Default,\n ],\n effect: Effect.gen(function* () {\n const users = yield* UserService\n const products = yield* ProductService\n const inventory = yield* InventoryService\n const payments = yield* PaymentService\n\n // Service implementation...\n return { /* methods */ }\n }),\n}) {}\n\n// At app root - simple, flat composition\nconst AppLive = Layer.mergeAll(\n OrderService.Default,\n // Other top-level services\n NotificationService.Default,\n AnalyticsService.Default,\n)\n```\n\n### Wrong Pattern (Leaked Dependencies)\n\n```typescript\n// WRONG - Dependencies not declared\nexport class OrderService extends Effect.Service()(\"OrderService\", {\n accessors: true,\n effect: Effect.gen(function* () {\n const users = yield* UserService // Not in dependencies!\n // ...\n }),\n}) {}\n\n// Now every usage requires manual wiring\nconst program = OrderService.create(input).pipe(\n Effect.provide(\n OrderService.Default.pipe(\n Layer.provide(UserService.Default),\n Layer.provide(ProductService.Default),\n // Easy to forget one, causes runtime errors\n )\n ),\n)\n```\n\n## Infrastructure Layers\n\nInfrastructure layers (Database, Redis, HTTP clients) are **acceptable** to leave as \"leaked\" dependencies because:\n\n1. They're provided once at the application root\n2. They don't change between test/production (different implementations, same interface)\n3. They're true infrastructure, not business logic\n\n```typescript\n// Infrastructure can be provided at app root\nimport { PgClient } from \"@effect/sql-pg\"\n\nconst DatabaseLive = PgClient.layer({\n host: Config.string(\"DB_HOST\"),\n port: Config.integer(\"DB_PORT\"),\n database: Config.string(\"DB_NAME\"),\n username: Config.string(\"DB_USER\"),\n password: Config.secret(\"DB_PASSWORD\"),\n})\n\n// Services use database but don't declare it in dependencies\nexport class UserRepo extends Effect.Service()(\"UserRepo\", {\n accessors: true,\n // No dependencies array - PgClient provided at app root\n effect: Effect.gen(function* () {\n const sql = yield* PgClient.PgClient\n\n const findById = Effect.fn(\"UserRepo.findById\")(function* (id: UserId) {\n const rows = yield* sql`SELECT * FROM users WHERE id = ${id}`.pipe(Effect.orDie)\n return rows[0] as User | undefined\n })\n\n return { findById }\n }),\n}) {}\n\n// App root provides infrastructure once\nconst AppLive = Layer.mergeAll(\n OrderService.Default,\n UserService.Default,\n).pipe(\n Layer.provide(DatabaseLive), // Infrastructure provided here\n Layer.provide(RedisLive),\n)\n```\n\n## Layer.mergeAll Over Nested Provides\n\n**Use `Layer.mergeAll`** for composing layers at the same level:\n\n```typescript\n// CORRECT - Flat composition\nconst ServicesLive = Layer.mergeAll(\n UserService.Default,\n OrderService.Default,\n ProductService.Default,\n NotificationService.Default,\n)\n\nconst InfrastructureLive = Layer.mergeAll(\n DatabaseLive,\n RedisLive,\n HttpClientLive,\n)\n\nconst AppLive = ServicesLive.pipe(\n Layer.provide(InfrastructureLive),\n)\n```\n\n```typescript\n// WRONG - Deeply nested, hard to read\nconst AppLive = UserService.Default.pipe(\n Layer.provide(\n OrderService.Default.pipe(\n Layer.provide(\n ProductService.Default.pipe(\n Layer.provide(DatabaseLive),\n ),\n ),\n ),\n ),\n)\n```\n\n## Layer Naming Conventions\n\nUse suffixes to indicate layer type:\n\n- `ServiceLive` - Production implementation\n- `ServiceTest` - Test/mock implementation\n- `ServiceLayer` - Generic layer (rare)\n\n```typescript\n// Production\nexport const UserServiceLive = UserService.Default\n\n// Test with mocks\nexport const UserServiceTest = Layer.succeed(\n UserService,\n UserService.of({\n findById: (id) => Effect.succeed(mockUser),\n create: (input) => Effect.succeed({ id: UserId.make(\"test-id\"), ...input }),\n })\n)\n\n// Test with in-memory state\nexport class UserServiceInMemory extends Effect.Service()(\"UserService\", {\n accessors: true,\n effect: Effect.gen(function* () {\n const store = new Map()\n\n return {\n findById: Effect.fn(\"UserService.findById\")(function* (id) {\n const user = store.get(id)\n if (!user) return yield* Effect.fail(new UserNotFoundError({ userId: id }))\n return user\n }),\n create: Effect.fn(\"UserService.create\")(function* (input) {\n const user = { id: UserId.make(crypto.randomUUID()), ...input }\n store.set(user.id, user)\n return user\n }),\n }\n }),\n}) {}\n```\n\n## Layer.unwrapEffect for Config-Dependent Layers\n\nWhen a layer needs async configuration:\n\n```typescript\nimport { Config, Effect, Layer } from \"effect\"\n\n// Layer that depends on config\nconst ApiClientLive = Layer.unwrapEffect(\n Effect.gen(function* () {\n const apiKey = yield* Config.string(\"API_KEY\")\n const baseUrl = yield* Config.string(\"API_BASE_URL\")\n const timeout = yield* Config.integer(\"API_TIMEOUT\").pipe(\n Config.withDefault(5000)\n )\n\n return Layer.succeed(\n ApiClient,\n new ApiClientImpl({ apiKey, baseUrl, timeout })\n )\n })\n)\n\n// Layer that validates config\nconst ValidatedConfigLive = Layer.unwrapEffect(\n Effect.gen(function* () {\n const config = yield* Config.all({\n dbUrl: Config.string(\"DATABASE_URL\"),\n redisUrl: Config.string(\"REDIS_URL\"),\n port: Config.integer(\"PORT\"),\n })\n\n // Validate config\n if (!config.dbUrl.startsWith(\"postgresql://\")) {\n return yield* Effect.fail(new ConfigError({ message: \"Invalid DATABASE_URL\" }))\n }\n\n return Layer.succeed(AppConfig, config)\n })\n)\n```\n\n## Scoped Layers\n\nFor resources that need cleanup:\n\n```typescript\nimport { Effect, Layer, Scope } from \"effect\"\n\n// Resource that needs cleanup\nconst DatabaseConnectionLive = Layer.scoped(\n DatabaseConnection,\n Effect.acquireRelease(\n Effect.gen(function* () {\n const pool = yield* createPool(config)\n yield* Effect.log(\"Database pool created\")\n return pool\n }),\n (pool) =>\n Effect.gen(function* () {\n yield* pool.end()\n yield* Effect.log(\"Database pool closed\")\n }).pipe(Effect.orDie)\n )\n)\n\n// Service using scoped resource\nexport class UserRepo extends Effect.Service()(\"UserRepo\", {\n accessors: true,\n effect: Effect.gen(function* () {\n const db = yield* DatabaseConnection\n\n return {\n findById: Effect.fn(\"UserRepo.findById\")(function* (id) {\n return yield* db.query(\"SELECT * FROM users WHERE id = $1\", [id])\n }),\n }\n }),\n}) {}\n```\n\n## Testing Layer Composition\n\n```typescript\n// test/setup.ts\nimport { Layer } from \"effect\"\n\nexport const TestLive = Layer.mergeAll(\n UserServiceTest,\n OrderServiceTest,\n ProductServiceTest,\n).pipe(\n Layer.provide(InMemoryDatabaseLive),\n)\n\n// test/user.test.ts\nimport { Effect } from \"effect\"\nimport { TestLive } from \"./setup\"\n\ndescribe(\"UserService\", () => {\n it(\"creates users\", async () => {\n const program = Effect.gen(function* () {\n const user = yield* UserService.create({\n email: \"test@example.com\",\n name: \"Test User\",\n })\n expect(user.email).toBe(\"test@example.com\")\n })\n\n await Effect.runPromise(program.pipe(Effect.provide(TestLive)))\n })\n})\n```\n\n## Layer.effect vs Layer.succeed\n\n```typescript\n// Layer.succeed - for static values (no effects)\nconst ConfigLive = Layer.succeed(AppConfig, {\n port: 3000,\n env: \"development\",\n})\n\n// Layer.effect - when construction needs effects\nconst LoggerLive = Layer.effect(\n Logger,\n Effect.gen(function* () {\n const config = yield* AppConfig\n const transport = config.env === \"production\"\n ? createCloudTransport()\n : createConsoleTransport()\n return new LoggerImpl(transport)\n })\n)\n```\n\n## Lazy Layers\n\nFor expensive initialization that should be deferred:\n\n```typescript\nconst ExpensiveServiceLive = Layer.lazy(() => {\n // This code runs only when the layer is first used\n return Layer.effect(\n ExpensiveService,\n Effect.gen(function* () {\n yield* Effect.log(\"Initializing expensive service...\")\n const client = yield* createExpensiveClient()\n return new ExpensiveServiceImpl(client)\n })\n )\n})\n```\n" }, { "path": "agents/skills/effect-best-practices/references/observability-patterns.md", "content": "# Observability Patterns\n\n## Structured Logging with Effect.log\n\n**Always use Effect.log** instead of console.log. Effect.log provides:\n- Structured data\n- Log levels\n- Integration with telemetry systems\n- Testability\n\n### Basic Logging\n\n```typescript\n// Simple message\nyield* Effect.log(\"Processing started\")\n\n// With structured data\nyield* Effect.log(\"Processing order\", {\n orderId,\n userId,\n amount,\n currency,\n})\n\n// Different log levels\nyield* Effect.logDebug(\"Cache lookup\", { key, hit: true })\nyield* Effect.logInfo(\"User logged in\", { userId })\nyield* Effect.logWarning(\"Rate limit approaching\", { current: 95, limit: 100 })\nyield* Effect.logError(\"Payment failed\", { orderId, reason: error.message })\nyield* Effect.logFatal(\"Database connection lost\")\n```\n\n### Logging in Services\n\n```typescript\nconst processOrder = Effect.fn(\"OrderService.processOrder\")(function* (input: OrderInput) {\n yield* Effect.log(\"Starting order processing\", { orderId: input.orderId })\n\n const result = yield* validateAndProcess(input).pipe(\n Effect.tap(() => Effect.log(\"Order processed successfully\")),\n Effect.tapError((err) =>\n Effect.logError(\"Order processing failed\", {\n orderId: input.orderId,\n error: err._tag,\n message: err.message,\n })\n ),\n )\n\n return result\n})\n```\n\n## Effect.fn for Automatic Tracing\n\n**Always use Effect.fn** for service methods. This automatically creates spans with proper names:\n\n```typescript\n// Creates span: \"UserService.findById\"\nconst findById = Effect.fn(\"UserService.findById\")(function* (id: UserId) {\n // Automatic span creation with:\n // - Start/end timing\n // - Error capture\n // - Parameter tracking (if annotated)\n})\n\n// Creates span: \"PaymentService.processPayment\"\nconst processPayment = Effect.fn(\"PaymentService.processPayment\")(\n function* (orderId: OrderId, amount: number) {\n // ...\n }\n)\n```\n\n### Naming Convention\n\nUse `ServiceName.methodName` format consistently:\n- `UserService.findById`\n- `OrderService.create`\n- `PaymentService.refund`\n- `NotificationService.sendEmail`\n\n## Span Annotations\n\nAdd important context to spans, but don't overdo it:\n\n```typescript\nconst processOrder = Effect.fn(\"OrderService.process\")(function* (orderId: OrderId) {\n // GOOD - Important business identifiers\n yield* Effect.annotateCurrentSpan(\"orderId\", orderId)\n yield* Effect.annotateCurrentSpan(\"userId\", order.userId)\n yield* Effect.annotateCurrentSpan(\"totalAmount\", order.total)\n\n // BAD - Too much detail, creates noise\n // yield* Effect.annotateCurrentSpan(\"step\", \"validating\")\n // yield* Effect.annotateCurrentSpan(\"itemCount\", order.items.length)\n // yield* Effect.annotateCurrentSpan(\"item0Name\", order.items[0].name)\n})\n```\n\n### What to Annotate\n\n**Do annotate:**\n- Entity IDs (orderId, userId, etc.)\n- Important business values (amounts, statuses)\n- Error context when failing\n\n**Don't annotate:**\n- Step-by-step progress\n- Individual item details\n- Internal implementation state\n- Sensitive data (PII, secrets)\n\n## Metrics\n\n### Counter\n\n```typescript\nimport { Metric } from \"effect\"\n\n// Define metrics at module level\nconst ordersProcessed = Metric.counter(\"orders_processed\", {\n description: \"Total orders processed\",\n})\n\nconst ordersFailed = Metric.counter(\"orders_failed\", {\n description: \"Total orders that failed processing\",\n})\n\n// Use in service\nconst processOrder = Effect.fn(\"OrderService.process\")(function* (input: OrderInput) {\n return yield* process(input).pipe(\n Effect.tap(() => Metric.increment(ordersProcessed)),\n Effect.tapError(() => Metric.increment(ordersFailed)),\n )\n})\n```\n\n### Counter with Tags\n\n```typescript\nconst httpRequests = Metric.counter(\"http_requests_total\", {\n description: \"Total HTTP requests\",\n})\n\n// Tag with method and status\nyield* Metric.increment(httpRequests).pipe(\n Metric.tagged(\"method\", request.method),\n Metric.tagged(\"status\", String(response.status)),\n Metric.tagged(\"path\", request.path),\n)\n```\n\n### Gauge\n\n```typescript\nconst activeConnections = Metric.gauge(\"active_connections\", {\n description: \"Number of active connections\",\n})\n\n// Update gauge\nyield* Metric.set(activeConnections, connectionCount)\n\n// Or increment/decrement\nyield* Metric.increment(activeConnections)\nyield* Metric.decrement(activeConnections)\n```\n\n### Histogram\n\n```typescript\nconst requestDuration = Metric.histogram(\"request_duration_ms\", {\n description: \"Request duration in milliseconds\",\n boundaries: [10, 50, 100, 250, 500, 1000, 2500, 5000],\n})\n\n// Record value\nyield* Metric.update(requestDuration, durationMs)\n\n// Or use timer helper\nconst timedEffect = effect.pipe(\n Metric.timerWithHistogram(requestDuration),\n)\n```\n\n## Configuration with Config\n\n**Always use Config** instead of process.env:\n\n### Basic Config\n\n```typescript\nimport { Config, Effect } from \"effect\"\n\nconst config = Config.all({\n port: Config.integer(\"PORT\").pipe(Config.withDefault(3000)),\n host: Config.string(\"HOST\").pipe(Config.withDefault(\"localhost\")),\n env: Config.literal(\"development\", \"staging\", \"production\")(\"NODE_ENV\"),\n})\n\n// Use in layer\nconst ServerLive = Layer.unwrapEffect(\n Effect.gen(function* () {\n const { port, host, env } = yield* config\n return Layer.succeed(ServerConfig, { port, host, env })\n })\n)\n```\n\n### Config with Validation\n\n```typescript\nconst dbConfig = Config.all({\n host: Config.string(\"DB_HOST\"),\n port: Config.integer(\"DB_PORT\").pipe(\n Config.validate({\n message: \"Port must be between 1 and 65535\",\n validation: (p) => p >= 1 && p <= 65535,\n })\n ),\n database: Config.string(\"DB_NAME\"),\n maxConnections: Config.integer(\"DB_MAX_CONNECTIONS\").pipe(\n Config.withDefault(10),\n Config.validate({\n message: \"Max connections must be positive\",\n validation: (n) => n > 0,\n })\n ),\n})\n```\n\n### Secret Config\n\n```typescript\n// For sensitive values that shouldn't be logged\nconst secretConfig = Config.all({\n apiKey: Config.secret(\"API_KEY\"), // Returns Secret\n dbPassword: Config.secret(\"DB_PASSWORD\"),\n})\n\n// Using secrets\nconst program = Effect.gen(function* () {\n const { apiKey, dbPassword } = yield* secretConfig\n\n // Secret values are wrapped - use Secret.value to unwrap\n const key = Secret.value(apiKey)\n\n // Logging a Secret shows \"[REDACTED]\"\n yield* Effect.log(\"Config loaded\", { apiKey }) // Safe - shows [REDACTED]\n})\n```\n\n### Config with Nested Structure\n\n```typescript\nconst appConfig = Config.all({\n server: Config.all({\n port: Config.integer(\"SERVER_PORT\"),\n host: Config.string(\"SERVER_HOST\"),\n }),\n database: Config.all({\n url: Config.string(\"DATABASE_URL\"),\n pool: Config.integer(\"DATABASE_POOL_SIZE\").pipe(Config.withDefault(10)),\n }),\n features: Config.all({\n enableBeta: Config.boolean(\"ENABLE_BETA\").pipe(Config.withDefault(false)),\n maxUploadSize: Config.integer(\"MAX_UPLOAD_SIZE\").pipe(Config.withDefault(10485760)),\n }),\n})\n```\n\n## Log Level Configuration\n\n```typescript\nimport { Logger, LogLevel } from \"effect\"\n\n// Set log level via config\nconst LoggerLive = Layer.unwrapEffect(\n Effect.gen(function* () {\n const level = yield* Config.literal(\n \"debug\", \"info\", \"warning\", \"error\"\n )(\"LOG_LEVEL\").pipe(Config.withDefault(\"info\"))\n\n const logLevel = {\n debug: LogLevel.Debug,\n info: LogLevel.Info,\n warning: LogLevel.Warning,\n error: LogLevel.Error,\n }[level]\n\n return Logger.minimumLogLevel(logLevel)\n })\n)\n\n// Production: structured JSON logging\nconst JsonLoggerLive = Logger.json\n```\n\n## Combining Observability\n\n```typescript\nconst processOrder = Effect.fn(\"OrderService.process\")(function* (input: OrderInput) {\n const startTime = yield* Effect.clockWith((clock) => clock.currentTimeMillis)\n\n // Annotate span\n yield* Effect.annotateCurrentSpan(\"orderId\", input.orderId)\n yield* Effect.annotateCurrentSpan(\"userId\", input.userId)\n\n // Log start\n yield* Effect.log(\"Processing order\", { orderId: input.orderId })\n\n const result = yield* process(input).pipe(\n Effect.tap((order) =>\n Effect.gen(function* () {\n const endTime = yield* Effect.clockWith((c) => c.currentTimeMillis)\n const duration = endTime - startTime\n\n // Record metric\n yield* Metric.update(orderProcessingDuration, duration)\n yield* Metric.increment(ordersProcessed)\n\n // Log completion\n yield* Effect.log(\"Order processed\", {\n orderId: input.orderId,\n durationMs: duration,\n })\n })\n ),\n Effect.tapError((err) =>\n Effect.gen(function* () {\n yield* Metric.increment(ordersFailed)\n yield* Effect.logError(\"Order processing failed\", {\n orderId: input.orderId,\n error: err._tag,\n })\n })\n ),\n )\n\n return result\n})\n```\n" }, { "path": "agents/skills/effect-best-practices/references/rpc-cluster-patterns.md", "content": "# RPC & Cluster Patterns\n\n## RpcGroup for API Organization\n\n**Use `RpcGroup.make`** to organize related RPC endpoints:\n\n```typescript\nimport { Rpc, RpcGroup } from \"@effect/rpc\"\nimport { Schema } from \"effect\"\n\n// Group related operations\nexport const UserRpc = RpcGroup.make(\"User\", {\n // Queries (read operations)\n findById: Rpc.query({\n input: UserId,\n output: User,\n error: UserNotFoundError,\n }),\n\n list: Rpc.query({\n input: Schema.Struct({\n organizationId: OrganizationId,\n limit: Schema.optionalWith(Schema.Number, { default: () => 50 }),\n offset: Schema.optionalWith(Schema.Number, { default: () => 0 }),\n }),\n output: Schema.Array(User),\n error: Schema.Never,\n }),\n\n // Mutations (write operations)\n create: Rpc.mutation({\n input: CreateUserInput,\n output: User,\n error: Schema.Union(UserCreateError, ValidationError),\n }),\n\n update: Rpc.mutation({\n input: Schema.Struct({\n id: UserId,\n data: UpdateUserInput,\n }),\n output: User,\n error: Schema.Union(UserNotFoundError, ValidationError),\n }),\n\n delete: Rpc.mutation({\n input: UserId,\n output: Schema.Void,\n error: UserNotFoundError,\n }),\n})\n```\n\n### Query vs Mutation\n\n- **Rpc.query** - Read operations, idempotent, cacheable\n- **Rpc.mutation** - Write operations, may have side effects\n\n```typescript\n// Query - safe to retry, can be cached\nfindById: Rpc.query({ ... }),\nsearch: Rpc.query({ ... }),\nlist: Rpc.query({ ... }),\n\n// Mutation - may modify state\ncreate: Rpc.mutation({ ... }),\nupdate: Rpc.mutation({ ... }),\ndelete: Rpc.mutation({ ... }),\n```\n\n## Error Unions in RPC\n\n**Always use explicit error unions** for RPC error types:\n\n```typescript\n// Explicit union of possible errors\ncreate: Rpc.mutation({\n input: CreateOrderInput,\n output: Order,\n error: Schema.Union(\n ValidationError,\n InsufficientInventoryError,\n PaymentFailedError,\n UserNotFoundError,\n ),\n}),\n\n// NOT - generic error type\ncreate: Rpc.mutation({\n input: CreateOrderInput,\n output: Order,\n error: GenericError, // WRONG - loses type information\n}),\n```\n\n## RPC Middleware for Authentication\n\n```typescript\nimport { RpcMiddleware, Rpc } from \"@effect/rpc\"\nimport { Effect, Layer } from \"effect\"\n\n// Context type for authenticated user\nexport class CurrentUser extends Context.Tag(\"CurrentUser\")<\n CurrentUser,\n { id: UserId; role: UserRole; organizationId: OrganizationId }\n>() {}\n\n// Auth middleware - extracts and validates auth\nexport class AuthMiddleware extends RpcMiddleware.Tag()(\n \"AuthMiddleware\",\n {\n provides: CurrentUser,\n failure: UnauthorizedError,\n }\n) {}\n\n// Middleware implementation\nexport const AuthMiddlewareLive = Layer.effect(\n AuthMiddleware,\n Effect.gen(function* () {\n const authService = yield* AuthService\n\n return AuthMiddleware.of({\n execute: (request) =>\n Effect.gen(function* () {\n const token = request.headers.get(\"authorization\")?.replace(\"Bearer \", \"\")\n\n if (!token) {\n return yield* Effect.fail(new UnauthorizedError({ message: \"Missing token\" }))\n }\n\n const user = yield* authService.validateToken(token).pipe(\n Effect.catchTag(\"TokenExpiredError\", () =>\n Effect.fail(new UnauthorizedError({ message: \"Token expired\" }))\n ),\n Effect.catchTag(\"TokenInvalidError\", () =>\n Effect.fail(new UnauthorizedError({ message: \"Invalid token\" }))\n ),\n )\n\n return user\n }),\n })\n })\n)\n\n// Protected RPC using middleware\nexport const ProtectedUserRpc = UserRpc.middleware(AuthMiddleware)\n```\n\n## Workflow Definition\n\n**Use `Workflow.make`** with explicit idempotency keys:\n\n```typescript\nimport { Workflow } from \"@effect/cluster\"\nimport { Schema } from \"effect\"\n\nexport const OrderFulfillmentWorkflow = Workflow.make({\n name: \"OrderFulfillmentWorkflow\",\n payload: {\n id: OrderId, // Execution ID\n orderId: OrderId,\n userId: UserId,\n items: Schema.Array(OrderItem),\n shippingAddress: ShippingAddress,\n },\n // Idempotency key prevents duplicate processing\n idempotencyKey: ({ orderId }) => orderId,\n})\n\nexport const NotificationWorkflow = Workflow.make({\n name: \"NotificationWorkflow\",\n payload: {\n id: Schema.String, // Unique execution ID\n messageId: MessageId,\n channelId: ChannelId,\n authorId: UserId,\n },\n idempotencyKey: ({ messageId }) => messageId,\n})\n```\n\n### Workflow Implementation\n\n```typescript\nimport { Activity } from \"@effect/workflow\"\nimport { Effect } from \"effect\"\n\nexport const OrderFulfillmentWorkflowLayer = OrderFulfillmentWorkflow.toLayer(\n Effect.fn(\"OrderFulfillmentWorkflow\")(function* (payload) {\n // Step 1: Reserve inventory\n const reservation = yield* Activity.make({\n name: \"ReserveInventory\",\n success: InventoryReservation,\n error: Schema.Union(InsufficientInventoryError, DatabaseError),\n execute: Effect.gen(function* () {\n const inventory = yield* InventoryService\n return yield* inventory.reserve(payload.items)\n }),\n })\n\n // Step 2: Process payment\n const payment = yield* Activity.make({\n name: \"ProcessPayment\",\n success: PaymentResult,\n error: Schema.Union(PaymentFailedError, PaymentTimeoutError),\n execute: Effect.gen(function* () {\n const payments = yield* PaymentService\n return yield* payments.charge(payload.userId, payload.items)\n }),\n })\n\n // Step 3: Create shipment\n const shipment = yield* Activity.make({\n name: \"CreateShipment\",\n success: Shipment,\n error: Schema.Union(ShippingError, AddressInvalidError),\n execute: Effect.gen(function* () {\n const shipping = yield* ShippingService\n return yield* shipping.createShipment({\n items: payload.items,\n address: payload.shippingAddress,\n reservationId: reservation.id,\n })\n }),\n })\n\n // Step 4: Send confirmation\n yield* Activity.make({\n name: \"SendConfirmation\",\n success: Schema.Void,\n error: NotificationError,\n execute: Effect.gen(function* () {\n const notifications = yield* NotificationService\n yield* notifications.sendOrderConfirmation({\n userId: payload.userId,\n orderId: payload.orderId,\n trackingNumber: shipment.trackingNumber,\n })\n }),\n })\n\n return { shipment, payment }\n })\n)\n```\n\n## Activity Patterns\n\n**Always include `success` and `error` schemas** in Activity.make:\n\n```typescript\n// CORRECT - schemas specified\nyield* Activity.make({\n name: \"SendEmail\",\n success: EmailSentResult,\n error: Schema.Union(EmailDeliveryError, EmailTemplateError),\n execute: Effect.gen(function* () {\n // Implementation\n return { messageId: \"msg-123\", sentAt: new Date() }\n }),\n})\n\n// WRONG - missing schemas\nyield* Activity.make({\n name: \"SendEmail\",\n execute: Effect.gen(function* () {\n // This will not serialize properly across workflow restarts\n }),\n})\n```\n\n### Activity Error Handling with Retryable\n\n```typescript\nexport class ExternalApiError extends Schema.TaggedError()(\n \"ExternalApiError\",\n {\n message: Schema.String,\n statusCode: Schema.Number,\n retryable: Schema.Boolean,\n },\n) {\n static fromResponse(response: Response): ExternalApiError {\n return new ExternalApiError({\n message: `API error: ${response.statusText}`,\n statusCode: response.status,\n retryable: response.status >= 500, // 5xx errors are retryable\n })\n }\n}\n\nyield* Activity.make({\n name: \"CallExternalApi\",\n success: ApiResponse,\n error: ExternalApiError,\n execute: Effect.gen(function* () {\n const response = yield* fetch(url)\n if (!response.ok) {\n return yield* Effect.fail(ExternalApiError.fromResponse(response))\n }\n return yield* response.json()\n }),\n})\n```\n\n## ClusterCron for Scheduled Jobs\n\n```typescript\nimport { ClusterCron } from \"@effect/cluster\"\n\nexport const DailyReportCron = ClusterCron.make({\n name: \"DailyReportCron\",\n // Cron expression: every day at 6 AM UTC\n schedule: \"0 6 * * *\",\n})\n\n// Implementation\nexport const DailyReportCronLayer = DailyReportCron.toLayer(\n Effect.fn(\"DailyReportCron\")(function* () {\n yield* Effect.log(\"Starting daily report generation\")\n\n const reports = yield* ReportService\n yield* reports.generateDailyReport()\n\n yield* Effect.log(\"Daily report generation complete\")\n })\n)\n```\n\n## Triggering Workflows\n\n### From HTTP Handler\n\n```typescript\nimport { HttpApi, HttpApiEndpoint } from \"@effect/platform\"\n\nconst createOrder = HttpApiEndpoint.post(\"createOrder\", \"/orders\")\n .setPayload(CreateOrderInput)\n .addSuccess(Order)\n .addError(ValidationError)\n\n// Handler triggers workflow\nconst createOrderHandler = Effect.gen(function* () {\n const input = yield* HttpApi.payload\n const workflowClient = yield* WorkflowClient\n\n // Create order in database\n const order = yield* OrderService.create(input)\n\n // Trigger async fulfillment workflow\n yield* workflowClient.workflows.OrderFulfillmentWorkflow.execute({\n id: order.id,\n orderId: order.id,\n userId: input.userId,\n items: input.items,\n shippingAddress: input.shippingAddress,\n })\n\n return order\n})\n```\n\n### From Backend Service\n\n```typescript\nexport class MessageService extends Effect.Service()(\"MessageService\", {\n accessors: true,\n dependencies: [MessageRepo.Default, WorkflowClient.Default],\n effect: Effect.gen(function* () {\n const repo = yield* MessageRepo\n const workflows = yield* WorkflowClient\n\n const create = Effect.fn(\"MessageService.create\")(function* (input: CreateMessageInput) {\n const message = yield* repo.create(input)\n\n // Trigger notification workflow\n yield* workflows.workflows.NotificationWorkflow.execute({\n id: message.id,\n messageId: message.id,\n channelId: message.channelId,\n authorId: message.authorId,\n })\n\n return message\n })\n\n return { create }\n }),\n}) {}\n```\n\n## Workflow HTTP API\n\n```typescript\n// Expose workflow execution via HTTP\nconst executeWorkflow = HttpApiEndpoint.post(\"executeWorkflow\", \"/workflows/:name/execute\")\n .setPath(Schema.Struct({ name: Schema.String }))\n .setPayload(Schema.Unknown)\n .addSuccess(Schema.Struct({ executionId: Schema.String }))\n .addError(WorkflowNotFoundError)\n\n// Handler\nconst executeWorkflowHandler = Effect.gen(function* () {\n const { name } = yield* HttpApi.path\n const payload = yield* HttpApi.payload\n const client = yield* WorkflowClient\n\n const workflow = client.workflows[name]\n if (!workflow) {\n return yield* Effect.fail(new WorkflowNotFoundError({ name }))\n }\n\n const result = yield* workflow.execute(payload)\n return { executionId: payload.id }\n})\n```\n" }, { "path": "agents/skills/effect-best-practices/references/schema-patterns.md", "content": "# Schema Patterns\n\n## Branded Types for IDs\n\n**Always brand entity IDs** to prevent accidentally passing the wrong ID type:\n\n```typescript\nimport { Schema } from \"effect\"\n\n// Entity IDs - always branded with namespace\nexport const UserId = Schema.UUID.pipe(Schema.brand(\"@App/UserId\"))\nexport type UserId = Schema.Schema.Type\n\nexport const OrganizationId = Schema.UUID.pipe(Schema.brand(\"@App/OrganizationId\"))\nexport type OrganizationId = Schema.Schema.Type\n\nexport const OrderId = Schema.UUID.pipe(Schema.brand(\"@App/OrderId\"))\nexport type OrderId = Schema.Schema.Type\n\nexport const ProductId = Schema.UUID.pipe(Schema.brand(\"@App/ProductId\"))\nexport type ProductId = Schema.Schema.Type\n```\n\n### Branding Convention\n\nUse `@Namespace/EntityName` format:\n- `@App/UserId` - Main application entities\n- `@Billing/InvoiceId` - Billing domain entities\n- `@External/StripeCustomerId` - External system IDs\n\n### Creating Branded Values\n\n```typescript\n// From string (validates UUID format)\nconst userId = Schema.decodeSync(UserId)(\"123e4567-e89b-12d3-a456-426614174000\")\n\n// Generate new ID\nconst newUserId = UserId.make(crypto.randomUUID())\n\n// Type error - can't mix ID types\nconst order = yield* orderService.findById(userId) // Error: UserId is not OrderId\n```\n\n### When NOT to Brand\n\nDon't brand simple strings that don't need type safety:\n\n```typescript\n// NOT branded - acceptable\nexport const Url = Schema.String\nexport const FilePath = Schema.String\nexport const EmailAddress = Schema.String.pipe(Schema.pattern(/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/))\n\n// These don't need branding because:\n// 1. They don't cross service boundaries in ways that could be confused\n// 2. They're typically validated by format, not by type\n```\n\n## Schema.Struct for Domain Types\n\n**Prefer Schema.Struct** over TypeScript interfaces for domain types:\n\n```typescript\n// CORRECT - Schema.Struct\nexport const User = Schema.Struct({\n id: UserId,\n email: Schema.String,\n name: Schema.String,\n organizationId: OrganizationId,\n role: Schema.Literal(\"admin\", \"member\", \"viewer\"),\n createdAt: Schema.DateTimeUtc,\n updatedAt: Schema.DateTimeUtc,\n})\nexport type User = Schema.Schema.Type\n\n// Can derive encoded type for database/API\nexport type UserEncoded = Schema.Schema.Encoded\n```\n\n### Input Types for Mutations\n\n```typescript\nexport const CreateUserInput = Schema.Struct({\n email: Schema.String.pipe(\n Schema.pattern(/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/),\n Schema.annotations({ description: \"Valid email address\" }),\n ),\n name: Schema.String.pipe(\n Schema.minLength(1),\n Schema.maxLength(100),\n ),\n organizationId: OrganizationId,\n role: Schema.optionalWith(\n Schema.Literal(\"admin\", \"member\", \"viewer\"),\n { default: () => \"member\" as const }\n ),\n})\nexport type CreateUserInput = Schema.Schema.Type\n\nexport const UpdateUserInput = Schema.Struct({\n name: Schema.optional(Schema.String.pipe(Schema.minLength(1))),\n role: Schema.optional(Schema.Literal(\"admin\", \"member\", \"viewer\")),\n})\nexport type UpdateUserInput = Schema.Schema.Type\n```\n\n## Schema.transform and transformOrFail\n\n**Use transforms** instead of manual parsing:\n\n```typescript\n// Transform string to Date\nexport const DateFromString = Schema.transform(\n Schema.String,\n Schema.DateTimeUtc,\n {\n decode: (s) => new Date(s),\n encode: (d) => d.toISOString(),\n }\n)\n\n// Transform with validation (can fail)\nexport const PositiveNumber = Schema.transformOrFail(\n Schema.Number,\n Schema.Number.pipe(Schema.brand(\"PositiveNumber\")),\n {\n decode: (n, _, ast) =>\n n > 0\n ? ParseResult.succeed(n as Schema.Schema.Type)\n : ParseResult.fail(new ParseResult.Type(ast, n, \"Must be positive\")),\n encode: ParseResult.succeed,\n }\n)\n```\n\n### Common Transforms\n\n```typescript\n// JSON string to object\nexport const JsonFromString = (schema: Schema.Schema) =>\n Schema.transform(\n Schema.String,\n schema,\n {\n decode: (s) => JSON.parse(s),\n encode: (a) => JSON.stringify(a),\n }\n )\n\n// Comma-separated string to array\nexport const CommaSeparatedList = Schema.transform(\n Schema.String,\n Schema.Array(Schema.String),\n {\n decode: (s) => s.split(\",\").map((x) => x.trim()).filter(Boolean),\n encode: (arr) => arr.join(\",\"),\n }\n)\n\n// Cents to dollars\nexport const DollarsFromCents = Schema.transform(\n Schema.Number.pipe(Schema.int()),\n Schema.Number,\n {\n decode: (cents) => cents / 100,\n encode: (dollars) => Math.round(dollars * 100),\n }\n)\n```\n\n## Schema.Class for Entities with Methods\n\nUse `Schema.Class` when entities need methods:\n\n```typescript\nexport class User extends Schema.Class(\"User\")({\n id: UserId,\n email: Schema.String,\n name: Schema.String,\n role: Schema.Literal(\"admin\", \"member\", \"viewer\"),\n createdAt: Schema.DateTimeUtc,\n}) {\n get isAdmin(): boolean {\n return this.role === \"admin\"\n }\n\n get displayName(): string {\n return this.name || this.email.split(\"@\")[0]\n }\n\n canAccessResource(resource: Resource): boolean {\n if (this.isAdmin) return true\n return resource.ownerId === this.id\n }\n}\n\n// Usage\nconst user = new User({\n id: UserId.make(crypto.randomUUID()),\n email: \"alice@example.com\",\n name: \"Alice\",\n role: \"member\",\n createdAt: new Date(),\n})\n\nconsole.log(user.displayName) // \"Alice\"\nconsole.log(user.isAdmin) // false\n```\n\n## Schema.annotations\n\nAdd annotations for documentation and validation messages:\n\n```typescript\nexport const CreateOrderInput = Schema.Struct({\n productId: ProductId.pipe(\n Schema.annotations({ description: \"The product to order\" }),\n ),\n quantity: Schema.Number.pipe(\n Schema.int(),\n Schema.positive(),\n Schema.annotations({\n description: \"Number of items to order\",\n examples: [1, 5, 10],\n }),\n ),\n shippingAddress: Schema.Struct({\n line1: Schema.String.pipe(Schema.annotations({ description: \"Street address\" })),\n line2: Schema.optional(Schema.String),\n city: Schema.String,\n state: Schema.String.pipe(Schema.length(2)),\n zip: Schema.String.pipe(Schema.pattern(/^\\d{5}(-\\d{4})?$/)),\n }).pipe(Schema.annotations({ description: \"Shipping destination\" })),\n}).pipe(\n Schema.annotations({\n title: \"Create Order Input\",\n description: \"Input for creating a new order\",\n }),\n)\n```\n\n## Optional Fields\n\nUse `Schema.optional` and `Schema.optionalWith`:\n\n```typescript\nexport const UserPreferences = Schema.Struct({\n // Optional, undefined if not provided\n theme: Schema.optional(Schema.Literal(\"light\", \"dark\")),\n\n // Optional with default value\n language: Schema.optionalWith(Schema.String, { default: () => \"en\" }),\n\n // Optional with null support (for database compatibility)\n bio: Schema.NullOr(Schema.String),\n\n // Optional but must be present if set (no undefined)\n timezone: Schema.optional(Schema.String, { exact: true }),\n})\n```\n\n## Union Types and Discriminated Unions\n\n```typescript\n// Simple union\nexport const PaymentMethod = Schema.Union(\n Schema.Literal(\"card\"),\n Schema.Literal(\"bank_transfer\"),\n Schema.Literal(\"crypto\"),\n)\n\n// Discriminated union (tagged)\nexport const PaymentDetails = Schema.Union(\n Schema.Struct({\n _tag: Schema.Literal(\"Card\"),\n cardNumber: Schema.String,\n expiry: Schema.String,\n cvv: Schema.String,\n }),\n Schema.Struct({\n _tag: Schema.Literal(\"BankTransfer\"),\n accountNumber: Schema.String,\n routingNumber: Schema.String,\n }),\n Schema.Struct({\n _tag: Schema.Literal(\"Crypto\"),\n walletAddress: Schema.String,\n network: Schema.Literal(\"ethereum\", \"bitcoin\", \"solana\"),\n }),\n)\nexport type PaymentDetails = Schema.Schema.Type\n\n// Usage with match\nconst processPayment = (details: PaymentDetails) => {\n switch (details._tag) {\n case \"Card\":\n return processCard(details.cardNumber, details.expiry, details.cvv)\n case \"BankTransfer\":\n return processBankTransfer(details.accountNumber, details.routingNumber)\n case \"Crypto\":\n return processCrypto(details.walletAddress, details.network)\n }\n}\n```\n\n## Enums and Literals\n\n```typescript\n// Use Literal for small, fixed sets\nexport const UserRole = Schema.Literal(\"admin\", \"member\", \"viewer\")\nexport type UserRole = Schema.Schema.Type\n\n// Use Enums for larger sets or when you need runtime values\nexport const OrderStatus = Schema.Enums({\n Pending: \"pending\",\n Processing: \"processing\",\n Shipped: \"shipped\",\n Delivered: \"delivered\",\n Cancelled: \"cancelled\",\n} as const)\nexport type OrderStatus = Schema.Schema.Type\n```\n\n## Recursive Schemas\n\n```typescript\ninterface Category {\n id: string\n name: string\n children: readonly Category[]\n}\n\nexport const Category: Schema.Schema = Schema.Struct({\n id: Schema.String,\n name: Schema.String,\n children: Schema.Array(Schema.suspend(() => Category)),\n})\n```\n\n## Decoding and Encoding\n\n```typescript\n// Decode (parse) - use in services\nconst parseUser = Schema.decodeUnknown(User)\nconst result = yield* parseUser(rawData) // Effect\n\n// Decode sync - only in controlled contexts\nconst user = Schema.decodeUnknownSync(User)(rawData)\n\n// Encode - for serialization\nconst encodeUser = Schema.encode(User)\nconst encoded = yield* encodeUser(user) // Effect\n```\n" }, { "path": "agents/skills/effect-best-practices/references/service-patterns.md", "content": "# Service Patterns\n\n## Effect.Service Over Context.Tag\n\n**Always prefer `Effect.Service`** for defining business logic services. This is the modern, recommended approach that provides:\n\n1. **Built-in `Default` layer** - No manual layer creation needed\n2. **Automatic accessors** - Direct method calls via `ServiceName.method()`\n3. **Proper dependency declaration** - Dependencies are explicit and type-checked\n4. **Consistent structure** - All services follow the same pattern\n\n### Basic Service Definition\n\n```typescript\nimport { Effect, Layer } from \"effect\"\n\nexport class UserService extends Effect.Service()(\"UserService\", {\n accessors: true,\n effect: Effect.gen(function* () {\n const findById = Effect.fn(\"UserService.findById\")(function* (id: UserId) {\n // Implementation\n })\n\n const findByEmail = Effect.fn(\"UserService.findByEmail\")(function* (email: string) {\n // Implementation\n })\n\n const create = Effect.fn(\"UserService.create\")(function* (input: CreateUserInput) {\n // Implementation\n })\n\n return { findById, findByEmail, create }\n }),\n}) {}\n```\n\n### Service with Dependencies\n\n**Critical:** Always declare dependencies using the `dependencies` array. This ensures:\n- Dependencies are automatically provided when using `ServiceName.Default`\n- Type errors if dependencies are missing\n- No manual `Layer.provide` at usage sites\n\n```typescript\nexport class OrderService extends Effect.Service()(\"OrderService\", {\n accessors: true,\n dependencies: [\n UserService.Default,\n ProductService.Default,\n InventoryService.Default,\n ],\n effect: Effect.gen(function* () {\n // Dependencies are automatically available\n const users = yield* UserService\n const products = yield* ProductService\n const inventory = yield* InventoryService\n\n const create = Effect.fn(\"OrderService.create\")(function* (input: CreateOrderInput) {\n // Validate user exists\n const user = yield* users.findById(input.userId)\n\n // Check product availability\n const product = yield* products.findById(input.productId)\n const available = yield* inventory.checkAvailability(input.productId, input.quantity)\n\n if (!available) {\n return yield* Effect.fail(new InsufficientInventoryError({\n productId: input.productId,\n message: \"Not enough inventory\",\n }))\n }\n\n // Create order...\n })\n\n return { create }\n }),\n}) {}\n```\n\n### Wrong: Leaking Dependencies\n\n```typescript\n// WRONG - Dependencies not declared, must be provided manually\nexport class OrderService extends Effect.Service()(\"OrderService\", {\n accessors: true,\n effect: Effect.gen(function* () {\n const users = yield* UserService // Dependency not in `dependencies` array!\n // ...\n }),\n}) {}\n\n// Now every usage site must do this:\nconst program = OrderService.create(input).pipe(\n Effect.provide(UserService.Default), // Annoying and error-prone\n)\n```\n\n## Effect.fn for Tracing\n\n**Always wrap service methods with `Effect.fn`**. This provides automatic tracing with meaningful span names.\n\n### Naming Convention\n\nUse `ServiceName.methodName` format for span names:\n\n```typescript\nconst findById = Effect.fn(\"UserService.findById\")(function* (id: UserId) {\n yield* Effect.annotateCurrentSpan(\"userId\", id)\n // Implementation\n})\n\nconst processPayment = Effect.fn(\"PaymentService.processPayment\")(\n function* (orderId: OrderId, amount: number, currency: string) {\n yield* Effect.annotateCurrentSpan(\"orderId\", orderId)\n yield* Effect.annotateCurrentSpan(\"amount\", amount)\n yield* Effect.annotateCurrentSpan(\"currency\", currency)\n // Implementation\n }\n)\n```\n\n### Annotating Spans\n\nAdd important context to spans, but don't overdo it:\n\n```typescript\n// CORRECT - Important business identifiers\nyield* Effect.annotateCurrentSpan(\"userId\", userId)\nyield* Effect.annotateCurrentSpan(\"orderId\", orderId)\nyield* Effect.annotateCurrentSpan(\"amount\", amount)\n\n// WRONG - Too much detail, noise in traces\nyield* Effect.annotateCurrentSpan(\"userEmail\", user.email)\nyield* Effect.annotateCurrentSpan(\"userName\", user.name)\nyield* Effect.annotateCurrentSpan(\"userCreatedAt\", user.createdAt)\nyield* Effect.annotateCurrentSpan(\"step\", \"validating\")\nyield* Effect.annotateCurrentSpan(\"step\", \"processing\")\nyield* Effect.annotateCurrentSpan(\"step\", \"completing\")\n```\n\n## When Context.Tag is Acceptable\n\n`Context.Tag` is appropriate **only** for infrastructure that's injected at runtime:\n\n### Cloudflare Worker Bindings\n\n```typescript\nimport { Context } from \"effect\"\n\n// These are provided by the runtime, not created by our code\nexport class KVNamespace extends Context.Tag(\"KVNamespace\")<\n KVNamespace,\n CloudflareKVNamespace\n>() {}\n\nexport class R2Bucket extends Context.Tag(\"R2Bucket\")<\n R2Bucket,\n CloudflareR2Bucket\n>() {}\n\n// In the worker entry point\nconst handler = {\n fetch(request: Request, env: Env) {\n return program.pipe(\n Effect.provideService(KVNamespace, env.MY_KV),\n Effect.provideService(R2Bucket, env.MY_BUCKET),\n Effect.runPromise,\n )\n }\n}\n```\n\n### Database/Redis Clients (Infrastructure)\n\n```typescript\n// Infrastructure provided at app root - acceptable as Context.Tag\n// But prefer using @effect/sql or similar typed clients\n\nimport { PgClient } from \"@effect/sql-pg\"\n\n// PgClient is already a Context.Tag from the library\n// Just provide it at the app root\nconst DatabaseLive = PgClient.layer({\n host: Config.string(\"DB_HOST\"),\n port: Config.integer(\"DB_PORT\"),\n database: Config.string(\"DB_NAME\"),\n // ...\n})\n```\n\n## Single Responsibility\n\nEach service should have a focused responsibility:\n\n```typescript\n// CORRECT - Focused services\nexport class UserService extends Effect.Service()(\"UserService\", { /* user operations */ }) {}\nexport class AuthService extends Effect.Service()(\"AuthService\", { /* auth operations */ }) {}\nexport class NotificationService extends Effect.Service()(\"NotificationService\", { /* notifications */ }) {}\n\n// WRONG - God service doing everything\nexport class AppService extends Effect.Service()(\"AppService\", {\n effect: Effect.gen(function* () {\n return {\n createUser,\n deleteUser,\n login,\n logout,\n sendEmail,\n sendPush,\n processPayment,\n // ... 50 more methods\n }\n }),\n}) {}\n```\n\n## Service Interface Patterns\n\n### Return Types\n\nServices should return `Effect` types, never `Promise`:\n\n```typescript\n// CORRECT\nconst findById = Effect.fn(\"UserService.findById\")(\n function* (id: UserId): Effect.Effect {\n // ...\n }\n)\n\n// WRONG - Promise in service interface\nconst findById = async (id: UserId): Promise => {\n // ...\n}\n```\n\n### Use Option for Nullable Results\n\n```typescript\n// CORRECT - findById can fail, findByIdOption returns Option\nconst findById = Effect.fn(\"UserService.findById\")(\n function* (id: UserId): Effect.Effect {\n const maybeUser = yield* repo.findById(id)\n return yield* Option.match(maybeUser, {\n onNone: () => Effect.fail(new UserNotFoundError({ userId: id, message: \"Not found\" })),\n onSome: Effect.succeed,\n })\n }\n)\n\nconst findByIdOption = Effect.fn(\"UserService.findByIdOption\")(\n function* (id: UserId): Effect.Effect> {\n return yield* repo.findById(id)\n }\n)\n```\n\n## Testing Services\n\nCreate test implementations using the same pattern:\n\n```typescript\n// Test implementation\nexport const UserServiceTest = Layer.succeed(\n UserService,\n UserService.of({\n findById: (id) => Effect.succeed(mockUser),\n create: (input) => Effect.succeed({ ...mockUser, ...input }),\n })\n)\n\n// Or with Effect.Service for stateful mocks\nexport class UserServiceTest extends Effect.Service()(\"UserService\", {\n accessors: true,\n effect: Effect.gen(function* () {\n const users = new Map()\n\n const findById = Effect.fn(\"UserService.findById\")(function* (id: UserId) {\n const user = users.get(id)\n if (!user) return yield* Effect.fail(new UserNotFoundError({ userId: id, message: \"Not found\" }))\n return user\n })\n\n const create = Effect.fn(\"UserService.create\")(function* (input: CreateUserInput) {\n const user = { id: UserId.make(crypto.randomUUID()), ...input }\n users.set(user.id, user)\n return user\n })\n\n return { findById, create }\n }),\n}) {}\n```\n" }, { "path": "agents/skills/emil-design-eng/SKILL.md", "content": "---\nname: emil-design-eng\ndescription: This skill encodes Emil Kowalski's philosophy on UI polish, component design, animation decisions, and the invisible details that make software feel great.\n---\n\n# Design Engineering\n\nYou are a design engineer with the craft sensibility. You build interfaces where every detail compounds into something that feels right. You understand that in a world where everyone's software is good enough, taste is the differentiator.\n\n## Core Philosophy\n\n### Taste is trained, not innate\n\nGood taste is not personal preference. It is a trained instinct: the ability to see beyond the obvious and recognize what elevates. You develop it by surrounding yourself with great work, thinking deeply about why something feels good, and practicing relentlessly.\n\nWhen building UI, don't just make it work. Study why the best interfaces feel the way they do. Reverse engineer animations. Inspect interactions. Be curious.\n\n### Unseen details compound\n\nMost details users never consciously notice. That is the point. When a feature functions exactly as someone assumes it should, they proceed without giving it a second thought. That is the goal.\n\n> \"All those unseen details combine to produce something that's just stunning, like a thousand barely audible voices all singing in tune.\" - Paul Graham\n\nEvery decision below exists because the aggregate of invisible correctness creates interfaces people love without knowing why.\n\n### Beauty is leverage\n\nPeople select tools based on the overall experience, not just functionality. Good defaults and good animations are real differentiators. Beauty is underutilized in software. Use it as leverage to stand out.\n\n## Review Format (Required)\n\nWhen reviewing UI code, you MUST use a markdown table with Before/After columns. Do NOT use a list with \"Before:\" and \"After:\" on separate lines. Always output an actual markdown table like this:\n\n| Before | After | Why |\n| --- | --- | --- |\n| `transition: all 300ms` | `transition: transform 200ms ease-out` | Specify exact properties; avoid `all` |\n| `transform: scale(0)` | `transform: scale(0.95); opacity: 0` | Nothing in the real world appears from nothing |\n| `ease-in` on dropdown | `ease-out` with custom curve | `ease-in` feels sluggish; `ease-out` gives instant feedback |\n| No `:active` state on button | `transform: scale(0.97)` on `:active` | Buttons must feel responsive to press |\n| `transform-origin: center` on popover | `transform-origin: var(--radix-popover-content-transform-origin)` | Popovers should scale from their trigger (not modals — modals stay centered) |\n\nWrong format (never do this):\n\n```\nBefore: transition: all 300ms\nAfter: transition: transform 200ms ease-out\n────────────────────────────\nBefore: scale(0)\nAfter: scale(0.95)\n```\n\nCorrect format: A single markdown table with | Before | After | Why | columns, one row per issue found. The \"Why\" column briefly explains the reasoning.\n\n## The Animation Decision Framework\n\nBefore writing any animation code, answer these questions in order:\n\n### 1. Should this animate at all?\n\n**Ask:** How often will users see this animation?\n\n| Frequency | Decision |\n| ----------------------------------------------------------- | ---------------------------- |\n| 100+ times/day (keyboard shortcuts, command palette toggle) | No animation. Ever. |\n| Tens of times/day (hover effects, list navigation) | Remove or drastically reduce |\n| Occasional (modals, drawers, toasts) | Standard animation |\n| Rare/first-time (onboarding, feedback forms, celebrations) | Can add delight |\n\n**Never animate keyboard-initiated actions.** These actions are repeated hundreds of times daily. Animation makes them feel slow, delayed, and disconnected from the user's actions.\n\nRaycast has no open/close animation. That is the optimal experience for something used hundreds of times a day.\n\n### 2. What is the purpose?\n\nEvery animation must have a clear answer to \"why does this animate?\"\n\nValid purposes:\n\n- **Spatial consistency**: toast enters and exits from the same direction, making swipe-to-dismiss feel intuitive\n- **State indication**: a morphing feedback button shows the state change\n- **Explanation**: a marketing animation that shows how a feature works\n- **Feedback**: a button scales down on press, confirming the interface heard the user\n- **Preventing jarring changes**: elements appearing or disappearing without transition feel broken\n\nIf the purpose is just \"it looks cool\" and the user will see it often, don't animate.\n\n### 3. What easing should it use?\n\nIs the element entering or exiting?\n Yes → ease-out (starts fast, feels responsive)\n No →\n Is it moving/morphing on screen?\n Yes → ease-in-out (natural acceleration/deceleration)\n Is it a hover/color change?\n Yes → ease\n Is it constant motion (marquee, progress bar)?\n Yes → linear\n Default → ease-out\n\n**Critical: use custom easing curves.** The built-in CSS easings are too weak. They lack the punch that makes animations feel intentional.\n\n```css\n/* Strong ease-out for UI interactions */\n--ease-out: cubic-bezier(0.23, 1, 0.32, 1);\n\n/* Strong ease-in-out for on-screen movement */\n--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);\n\n/* iOS-like drawer curve (from Ionic Framework) */\n--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);\n```\n\n**Never use ease-in for UI animations.** It starts slow, which makes the interface feel sluggish and unresponsive. A dropdown with `ease-in` at 300ms _feels_ slower than `ease-out` at the same 300ms, because ease-in delays the initial movement — the exact moment the user is watching most closely.\n\n**Easing curve resources:** Don't create curves from scratch. Use [easing.dev](https://easing.dev/) or [easings.co](https://easings.co/) to find stronger custom variants of standard easings.\n\n### 4. How fast should it be?\n\n| Element | Duration |\n| ------------------------ | ------------- |\n| Button press feedback | 100-160ms |\n| Tooltips, small popovers | 125-200ms |\n| Dropdowns, selects | 150-250ms |\n| Modals, drawers | 200-500ms |\n| Marketing/explanatory | Can be longer |\n\n**Rule: UI animations should stay under 300ms.** A 180ms dropdown feels more responsive than a 400ms one. A faster-spinning spinner makes the app feel like it loads faster, even when the load time is identical.\n\n### Perceived performance\n\nSpeed in animation is not just about feeling snappy — it directly affects how users perceive your app's performance:\n\n- A **fast-spinning spinner** makes loading feel faster (same load time, different perception)\n- A **180ms select** animation feels more responsive than a **400ms** one\n- **Instant tooltips** after the first one is open (skip delay + skip animation) make the whole toolbar feel faster\n\nThe perception of speed matters as much as actual speed. Easing amplifies this: `ease-out` at 200ms _feels_ faster than `ease-in` at 200ms because the user sees immediate movement.\n\n## Spring Animations\n\nSprings feel more natural than duration-based animations because they simulate real physics. They don't have fixed durations — they settle based on physical parameters.\n\n### When to use springs\n\n- Drag interactions with momentum\n- Elements that should feel \"alive\" (like Apple's Dynamic Island)\n- Gestures that can be interrupted mid-animation\n- Decorative mouse-tracking interactions\n\n### Spring-based mouse interactions\n\nTying visual changes directly to mouse position feels artificial because it lacks motion. Use `useSpring` from Motion (formerly Framer Motion) to interpolate value changes with spring-like behavior instead of updating immediately.\n\n```jsx\nimport { useSpring } from 'framer-motion';\n\n// Without spring: feels artificial, instant\nconst rotation = mouseX * 0.1;\n\n// With spring: feels natural, has momentum\nconst springRotation = useSpring(mouseX * 0.1, {\n stiffness: 100,\n damping: 10,\n});\n```\n\nThis works because the animation is **decorative** — it doesn't serve a function. If this were a functional graph in a banking app, no animation would be better. Know when decoration helps and when it hinders.\n\n### Spring configuration\n\n**Apple's approach (recommended — easier to reason about):**\n\n```js\n{ type: \"spring\", duration: 0.5, bounce: 0.2 }\n```\n\n**Traditional physics (more control):**\n\n```js\n{ type: \"spring\", mass: 1, stiffness: 100, damping: 10 }\n```\n\nKeep bounce subtle (0.1-0.3) when used. Avoid bounce in most UI contexts. Use it for drag-to-dismiss and playful interactions.\n\n### Interruptibility advantage\n\nSprings maintain velocity when interrupted — CSS animations and keyframes restart from zero. This makes springs ideal for gestures users might change mid-motion. When you click an expanded item and quickly press Escape, a spring-based animation smoothly reverses from its current position.\n\n## Component Building Principles\n\n### Buttons must feel responsive\n\nAdd `transform: scale(0.97)` on `:active`. This gives instant feedback, making the UI feel like it is truly listening to the user.\n\n```css\n.button {\n transition: transform 160ms ease-out;\n}\n\n.button:active {\n transform: scale(0.97);\n}\n```\n\nThis applies to any pressable element. The scale should be subtle (0.95-0.98).\n\n### Never animate from scale(0)\n\nNothing in the real world disappears and reappears completely. Elements animating from `scale(0)` look like they come out of nowhere.\n\nStart from `scale(0.9)` or higher, combined with opacity. Even a barely-visible initial scale makes the entrance feel more natural, like a balloon that has a visible shape even when deflated.\n\n```css\n/* Bad */\n.entering {\n transform: scale(0);\n}\n\n/* Good */\n.entering {\n transform: scale(0.95);\n opacity: 0;\n}\n```\n\n### Make popovers origin-aware\n\nPopovers should scale in from their trigger, not from center. The default `transform-origin: center` is wrong for almost every popover. **Exception: modals.** Modals should keep `transform-origin: center` because they are not anchored to a specific trigger — they appear centered in the viewport.\n\n```css\n/* Radix UI */\n.popover {\n transform-origin: var(--radix-popover-content-transform-origin);\n}\n\n/* Base UI */\n.popover {\n transform-origin: var(--transform-origin);\n}\n```\n\nWhether the user notices the difference individually does not matter. In the aggregate, unseen details become visible. They compound.\n\n### Tooltips: skip delay on subsequent hovers\n\nTooltips should delay before appearing to prevent accidental activation. But once one tooltip is open, hovering over adjacent tooltips should open them instantly with no animation. This feels faster without defeating the purpose of the initial delay.\n\n```css\n.tooltip {\n transition: transform 125ms ease-out, opacity 125ms ease-out;\n transform-origin: var(--transform-origin);\n}\n\n.tooltip[data-starting-style],\n.tooltip[data-ending-style] {\n opacity: 0;\n transform: scale(0.97);\n}\n\n/* Skip animation on subsequent tooltips */\n.tooltip[data-instant] {\n transition-duration: 0ms;\n}\n```\n\n### Use CSS transitions over keyframes for interruptible UI\n\nCSS transitions can be interrupted and retargeted mid-animation. Keyframes restart from zero. For any interaction that can be triggered rapidly (adding toasts, toggling states), transitions produce smoother results.\n\n```css\n/* Interruptible - good for UI */\n.toast {\n transition: transform 400ms ease;\n}\n\n/* Not interruptible - avoid for dynamic UI */\n@keyframes slideIn {\n from {\n transform: translateY(100%);\n }\n to {\n transform: translateY(0);\n }\n}\n```\n\n### Use blur to mask imperfect transitions\n\nWhen a crossfade between two states feels off despite trying different easings and durations, add subtle `filter: blur(2px)` during the transition.\n\n**Why blur works:** Without blur, you see two distinct objects during a crossfade — the old state and the new state overlapping. This looks unnatural. Blur bridges the visual gap by blending the two states together, tricking the eye into perceiving a single smooth transformation instead of two objects swapping.\n\nCombine blur with scale-on-press (`scale(0.97)`) for a polished button state transition:\n\n```css\n.button {\n transition: transform 160ms ease-out;\n}\n\n.button:active {\n transform: scale(0.97);\n}\n\n.button-content {\n transition: filter 200ms ease, opacity 200ms ease;\n}\n\n.button-content.transitioning {\n filter: blur(2px);\n opacity: 0.7;\n}\n```\n\nKeep blur under 20px. Heavy blur is expensive, especially in Safari.\n\n### Animate enter states with @starting-style\n\nThe modern CSS way to animate element entry without JavaScript:\n\n```css\n.toast {\n opacity: 1;\n transform: translateY(0);\n transition: opacity 400ms ease, transform 400ms ease;\n\n @starting-style {\n opacity: 0;\n transform: translateY(100%);\n }\n}\n```\n\nThis replaces the common React pattern of using `useEffect` to set `mounted: true` after initial render. Use `@starting-style` when browser support allows; fall back to the `data-mounted` attribute pattern otherwise.\n\n```jsx\n// Legacy pattern (still works everywhere)\nuseEffect(() => {\n setMounted(true);\n}, []);\n//
\n```\n\n## CSS Transform Mastery\n\n### translateY with percentages\n\nPercentage values in `translate()` are relative to the element's own size. Use `translateY(100%)` to move an element by its own height, regardless of actual dimensions. This is how Sonner positions toasts and how Vaul hides the drawer before animating in.\n\n```css\n/* Works regardless of drawer height */\n.drawer-hidden {\n transform: translateY(100%);\n}\n\n/* Works regardless of toast height */\n.toast-enter {\n transform: translateY(-100%);\n}\n```\n\nPrefer percentages over hardcoded pixel values. They are less error-prone and adapt to content.\n\n### scale() scales children too\n\nUnlike `width`/`height`, `scale()` also scales an element's children. When scaling a button on press, the font size, icons, and content scale proportionally. This is a feature, not a bug.\n\n### 3D transforms for depth\n\n`rotateX()`, `rotateY()` with `transform-style: preserve-3d` create real 3D effects in CSS. Orbiting animations, coin flips, and depth effects are all possible without JavaScript.\n\n```css\n.wrapper {\n transform-style: preserve-3d;\n}\n\n@keyframes orbit {\n from {\n transform: translate(-50%, -50%) rotateY(0deg) translateZ(72px) rotateY(360deg);\n }\n to {\n transform: translate(-50%, -50%) rotateY(360deg) translateZ(72px) rotateY(0deg);\n }\n}\n```\n\n### transform-origin\n\nEvery element has an anchor point from which transforms execute. The default is center. Set it to match where the trigger lives for origin-aware interactions.\n\n## clip-path for Animation\n\n`clip-path` is not just for shapes. It is one of the most powerful animation tools in CSS.\n\n### The inset shape\n\n`clip-path: inset(top right bottom left)` defines a rectangular clipping region. Each value \"eats\" into the element from that side.\n\n```css\n/* Fully hidden from right */\n.hidden {\n clip-path: inset(0 100% 0 0);\n}\n\n/* Fully visible */\n.visible {\n clip-path: inset(0 0 0 0);\n}\n\n/* Reveal from left to right */\n.overlay {\n clip-path: inset(0 100% 0 0);\n transition: clip-path 200ms ease-out;\n}\n.button:active .overlay {\n clip-path: inset(0 0 0 0);\n transition: clip-path 2s linear;\n}\n```\n\n### Tabs with perfect color transitions\n\nDuplicate the tab list. Style the copy as \"active\" (different background, different text color). Clip the copy so only the active tab is visible. Animate the clip on tab change. This creates a seamless color transition that timing individual color transitions can never achieve.\n\n### Hold-to-delete pattern\n\nUse `clip-path: inset(0 100% 0 0)` on a colored overlay. On `:active`, transition to `inset(0 0 0 0)` over 2s with linear timing. On release, snap back with 200ms ease-out. Add `scale(0.97)` on the button for press feedback.\n\n### Image reveals on scroll\n\nStart with `clip-path: inset(0 0 100% 0)` (hidden from bottom). Animate to `inset(0 0 0 0)` when the element enters the viewport. Use `IntersectionObserver` or Framer Motion's `useInView` with `{ once: true, margin: \"-100px\" }`.\n\n### Comparison sliders\n\nOverlay two images. Clip the top one with `clip-path: inset(0 50% 0 0)`. Adjust the right inset value based on drag position. No extra DOM elements needed, fully hardware-accelerated.\n\n## Gesture and Drag Interactions\n\n### Momentum-based dismissal\n\nDon't require dragging past a threshold. Calculate velocity: `Math.abs(dragDistance) / elapsedTime`. If velocity exceeds ~0.11, dismiss regardless of distance. A quick flick should be enough.\n\n```js\nconst timeTaken = new Date().getTime() - dragStartTime.current.getTime();\nconst velocity = Math.abs(swipeAmount) / timeTaken;\n\nif (Math.abs(swipeAmount) >= SWIPE_THRESHOLD || velocity > 0.11) {\n dismiss();\n}\n```\n\n### Damping at boundaries\n\nWhen a user drags past the natural boundary (e.g., dragging a drawer up when already at top), apply damping. The more they drag, the less the element moves. Things in real life don't suddenly stop; they slow down first.\n\n### Pointer capture for drag\n\nOnce dragging starts, set the element to capture all pointer events. This ensures dragging continues even if the pointer leaves the element bounds.\n\n### Multi-touch protection\n\nIgnore additional touch points after the initial drag begins. Without this, switching fingers mid-drag causes the element to jump to the new position.\n\n```js\nfunction onPress() {\n if (isDragging) return;\n // Start drag...\n}\n```\n\n### Friction instead of hard stops\n\nInstead of preventing upward drag entirely, allow it with increasing friction. It feels more natural than hitting an invisible wall.\n\n## Performance Rules\n\n### Only animate transform and opacity\n\nThese properties skip layout and paint, running on the GPU. Animating `padding`, `margin`, `height`, or `width` triggers all three rendering steps.\n\n### CSS variables are inheritable\n\nChanging a CSS variable on a parent recalculates styles for all children. In a drawer with many items, updating `--swipe-amount` on the container causes expensive style recalculation. Update `transform` directly on the element instead.\n\n```js\n// Bad: triggers recalc on all children\nelement.style.setProperty('--swipe-amount', `${distance}px`);\n\n// Good: only affects this element\nelement.style.transform = `translateY(${distance}px)`;\n```\n\n### Framer Motion hardware acceleration caveat\n\nFramer Motion's shorthand properties (`x`, `y`, `scale`) are NOT hardware-accelerated. They use `requestAnimationFrame` on the main thread. For hardware acceleration, use the full `transform` string:\n\n```jsx\n// NOT hardware accelerated (convenient but drops frames under load)\n\n\n// Hardware accelerated (stays smooth even when main thread is busy)\n\n```\n\nThis matters when the browser is simultaneously loading content, running scripts, or painting. At Vercel, the dashboard tab animation used Shared Layout Animations and dropped frames during page loads. Switching to CSS animations (off main thread) fixed it.\n\n### CSS animations beat JS under load\n\nCSS animations run off the main thread. When the browser is busy loading a new page, Framer Motion animations (using `requestAnimationFrame`) drop frames. CSS animations remain smooth. Use CSS for predetermined animations; JS for dynamic, interruptible ones.\n\n### Use WAAPI for programmatic CSS animations\n\nThe Web Animations API gives you JavaScript control with CSS performance. Hardware-accelerated, interruptible, and no library needed.\n\n```js\nelement.animate([{ clipPath: 'inset(0 0 100% 0)' }, { clipPath: 'inset(0 0 0 0)' }], {\n duration: 1000,\n fill: 'forwards',\n easing: 'cubic-bezier(0.77, 0, 0.175, 1)',\n});\n```\n\n## Accessibility\n\n### prefers-reduced-motion\n\nAnimations can cause motion sickness. Reduced motion means fewer and gentler animations, not zero. Keep opacity and color transitions that aid comprehension. Remove movement and position animations.\n\n```css\n@media (prefers-reduced-motion: reduce) {\n .element {\n animation: fade 0.2s ease;\n /* No transform-based motion */\n }\n}\n```\n\n```jsx\nconst shouldReduceMotion = useReducedMotion();\nconst closedX = shouldReduceMotion ? 0 : '-100%';\n```\n\n### Touch device hover states\n\n```css\n@media (hover: hover) and (pointer: fine) {\n .element:hover {\n transform: scale(1.05);\n }\n}\n```\n\nTouch devices trigger hover on tap, causing false positives. Gate hover animations behind this media query.\n\n## The Sonner Principles (Building Loved Components)\n\nThese principles come from building Sonner (13M+ weekly npm downloads) and apply to any component:\n\n1. **Developer experience is key.** No hooks, no context, no complex setup. Insert `` once, call `toast()` from anywhere. The less friction to adopt, the more people will use it.\n\n2. **Good defaults matter more than options.** Ship beautiful out of the box. Most users never customize. The default easing, timing, and visual design should be excellent.\n\n3. **Naming creates identity.** \"Sonner\" (French for \"to ring\") feels more elegant than \"react-toast\". Sacrifice discoverability for memorability when appropriate.\n\n4. **Handle edge cases invisibly.** Pause toast timers when the tab is hidden. Fill gaps between stacked toasts with pseudo-elements to maintain hover state. Capture pointer events during drag. Users never notice these, and that is exactly right.\n\n5. **Use transitions, not keyframes, for dynamic UI.** Toasts are added rapidly. Keyframes restart from zero on interruption. Transitions retarget smoothly.\n\n6. **Build a great documentation site.** Let people touch the product, play with it, and understand it before they use it. Interactive examples with ready-to-use code snippets lower the barrier to adoption.\n\n### Cohesion matters\n\nSonner's animation feels satisfying partly because the whole experience is cohesive. The easing and duration fit the vibe of the library. It is slightly slower than typical UI animations and uses `ease` rather than `ease-out` to feel more elegant. The animation style matches the toast design, the page design, the name — everything is in harmony.\n\nWhen choosing animation values, consider the personality of the component. A playful component can be bouncier. A professional dashboard should be crisp and fast. Match the motion to the mood.\n\n### The opacity + height combination\n\nWhen items enter and exit a list (like Family's drawer), the opacity change must work well with the height animation. This is often trial and error. There is no formula — you adjust until it feels right.\n\n### Review your work the next day\n\nReview animations with fresh eyes. You notice imperfections the next day that you missed during development. Play animations in slow motion or frame by frame to spot timing issues that are invisible at full speed.\n\n### Asymmetric enter/exit timing\n\nPressing should be slow when it needs to be deliberate (hold-to-delete: 2s linear), but release should always be snappy (200ms ease-out). This pattern applies broadly: slow where the user is deciding, fast where the system is responding.\n\n```css\n/* Release: fast */\n.overlay {\n transition: clip-path 200ms ease-out;\n}\n\n/* Press: slow and deliberate */\n.button:active .overlay {\n transition: clip-path 2s linear;\n}\n```\n\n## Stagger Animations\n\nWhen multiple elements enter together, stagger their appearance. Each element animates in with a small delay after the previous one. This creates a cascading effect that feels more natural than everything appearing at once.\n\n```css\n.item {\n opacity: 0;\n transform: translateY(8px);\n animation: fadeIn 300ms ease-out forwards;\n}\n\n.item:nth-child(1) {\n animation-delay: 0ms;\n}\n.item:nth-child(2) {\n animation-delay: 50ms;\n}\n.item:nth-child(3) {\n animation-delay: 100ms;\n}\n.item:nth-child(4) {\n animation-delay: 150ms;\n}\n\n@keyframes fadeIn {\n to {\n opacity: 1;\n transform: translateY(0);\n }\n}\n```\n\nKeep stagger delays short (30-80ms between items). Long delays make the interface feel slow. Stagger is decorative — never block interaction while stagger animations are playing.\n\n## Debugging Animations\n\n### Slow motion testing\n\nPlay animations at reduced speed to spot issues invisible at full speed. Temporarily increase duration to 2-5x normal, or use browser DevTools animation inspector to slow playback.\n\nThings to look for in slow motion:\n\n- Do colors transition smoothly, or do you see two distinct states overlapping?\n- Does the easing feel right, or does it start/stop abruptly?\n- Is the transform-origin correct, or does the element scale from the wrong point?\n- Are multiple animated properties (opacity, transform, color) in sync?\n\n### Frame-by-frame inspection\n\nStep through animations frame by frame in Chrome DevTools (Animations panel). This reveals timing issues between coordinated properties that you cannot see at full speed.\n\n### Test on real devices\n\nFor touch interactions (drawers, swipe gestures), test on physical devices. Connect your phone via USB, visit your local dev server by IP address, and use Safari's remote devtools. The Xcode Simulator is an alternative but real hardware is better for gesture testing.\n\n## Review Checklist\n\nWhen reviewing UI code, check for:\n\n| Issue | Fix |\n| ------------------------------------------ | ---------------------------------------------------------------- |\n| `transition: all` | Specify exact properties: `transition: transform 200ms ease-out` |\n| `scale(0)` entry animation | Start from `scale(0.95)` with `opacity: 0` |\n| `ease-in` on UI element | Switch to `ease-out` or custom curve |\n| `transform-origin: center` on popover | Set to trigger location or use Radix/Base UI CSS variable (modals are exempt — keep centered) |\n| Animation on keyboard action | Remove animation entirely |\n| Duration > 300ms on UI element | Reduce to 150-250ms |\n| Hover animation without media query | Add `@media (hover: hover) and (pointer: fine)` |\n| Keyframes on rapidly-triggered element | Use CSS transitions for interruptibility |\n| Framer Motion `x`/`y` props under load | Use `transform: \"translateX()\"` for hardware acceleration |\n| Same enter/exit transition speed | Make exit faster than enter (e.g., enter 2s, exit 200ms) |\n| Elements all appear at once | Add stagger delay (30-80ms between items) |\n" }, { "path": "agents/skills/frontend-design/LICENSE.txt", "content": "\n Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\n TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n 1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n 2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n 3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n 4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n 5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n 6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n 7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n 8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n 9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\n END OF TERMS AND CONDITIONS\n" }, { "path": "agents/skills/frontend-design/SKILL.md", "content": "---\nname: frontend-design\ndescription: \"Design and implement distinctive, production-ready frontend interfaces with strong aesthetic direction. Use when asked to create or restyle web pages, components, or applications (HTML/CSS/JS, React, Vue, etc.).\"\n---\n\n# Frontend Design Skill\n\nDesign and implement memorable frontend interfaces with a clear, intentional aesthetic. The output must be real, working code — not just mood boards. This skill is about **design thinking + execution**: every visual choice should be rooted in purpose and context.\n\n## When to Use\n\nUse this skill when the user wants to:\n- Create a new web page, landing page, dashboard, or app UI\n- Design or redesign frontend components or screens\n- Improve typography, layout, color, motion, or overall visual polish\n- Convert a concept or brief into a high‑fidelity, coded interface\n\n## Inputs to Gather (or Assume)\n\nBefore coding, identify:\n- **Purpose & audience**: What problem does this UI solve? Who uses it?\n- **Brand/voice**: Any reference brands, tone, or visual inspiration?\n- **Technical constraints**: Framework, library, CSS strategy, accessibility, performance\n- **Content constraints**: Required copy, assets, data, features\n\nIf the user did not provide this, ask **2–4 targeted questions**, or state reasonable assumptions in a short preface.\n\n## Design Thinking (Required)\n\nCommit to a **single, bold aesthetic direction**. Name it and execute it consistently. Examples:\n- Brutalist / raw / utilitarian\n- Editorial / magazine / typographic\n- Luxury / refined / minimal\n- Retro‑futuristic / cyber / neon\n- Art‑deco / geometric / ornamental\n- Handcrafted / organic / textured\n\n**Avoid generic AI aesthetics.** No “default” fonts, color schemes, or stock layouts.\n\nBefore writing code, define the system:\n1. **Visual direction** — one sentence that describes the vibe\n2. **Differentiator** — what should be memorable about this UI?\n3. **Typography system** — display + body fonts, scale, weight, casing\n4. **Color system** — dominant, accent, neutral; define as CSS variables\n5. **Layout strategy** — grid rhythm, spacing scale, hierarchy plan\n6. **Motion strategy** — 1–2 meaningful interaction moments\n\nIf the user wants code only, skip the explanation but still follow this internally.\n\n## Implementation Principles\n\n- **Working code**: HTML/CSS/JS or framework code that runs as‑is\n- **Semantic & accessible**: headings, labels, focus states, keyboard nav\n- **Responsive**: fluid layouts, breakpoints, responsive typography\n- **Tokenized styling**: CSS variables for colors, spacing, radii, shadows\n- **Modern layout**: prefer CSS Grid/Flex, avoid brittle positioning hacks\n\n## Aesthetic Guidelines\n\n### Typography\n- Typography should define the voice of the design\n- Avoid default fonts (Inter, Roboto, Arial, system stacks)\n- Use a **distinct display font** + a **refined body font**\n- Implement a clear hierarchy (size, weight, spacing, casing)\n\n### Color & Theme\n- Commit to a palette with a strong point‑of‑view\n- Avoid timid, overused gradients (e.g., purple‑to‑pink on white)\n- Use contrast intentionally and check legibility\n\n### Composition & Layout\n- Encourage asymmetry, scale contrast, overlap, or grid breaks\n- Use negative space deliberately (or controlled density if maximalist)\n- Create visual rhythm and hierarchy through spacing and alignment\n\n### Detail & Atmosphere\n- Add texture or depth when appropriate (noise, grain, subtle patterns)\n- Use shadows/glows only when they serve the concept\n- Consider unique borders, masks, or clip‑paths for distinct shapes\n\n### Motion & Interaction\n- Use motion sparingly but meaningfully\n- Favor one standout interaction over many tiny ones\n- Honor `prefers-reduced-motion`\n\n## Avoid\n\n- Cookie‑cutter hero + 3 card layouts\n- Generic gradients and default font choices\n- Unmotivated decorative elements\n- Overly flat, characterless component libraries\n\n## Deliverables\n\n- Provide full code with file names or component boundaries\n- Make customization easy with CSS variables or config objects\n- If assets are needed, provide inline SVGs or generative CSS patterns\n\n## Quality Checklist (Self‑validate)\n\n- Aesthetic direction is unmistakable\n- Typography feels intentional and expressive\n- Layout and spacing are consistent and purposeful\n- Color palette feels cohesive and legible\n- Interactions enhance the experience without clutter\n- Code runs as provided and is production‑ready\n\n**Remember:** a design is only as strong as its commitment. Choose a direction and execute it relentlessly.\n" }, { "path": "agents/skills/grill-me/SKILL.md", "content": "---\nname: grill-me\ndescription: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions \"grill me\".\n---\n\nInterview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.\n\nAsk the questions one at a time.\n\nIf a question can be answered by exploring the codebase, explore the codebase instead.\n" }, { "path": "agents/skills/initz/SKILL.md", "content": "---\nname: initz\nversion: 1.0.0\ndescription: Initialize or improve AGENTS.md\n---\n\n# AGENTS.md Initialization\n\nAnalyze this codebase and create an AGENTS.md file containing:\n\n1. Build/lint/test commands - especially for running a single test\n2. Code style guidelines including imports, formatting, types, naming conventions, error handling, etc.\n\n## Guidelines\n\n- Target length: ~150 lines\n- Include Cursor rules (from `.cursor/rules/` or `.cursorrules`) if present\n- Include Copilot rules (from `.github/copilot-instructions.md`) if present\n- If there's already an AGENTS.md at `${path}`, improve it\n\n## Progressive Disclosure Approach\n\n1. **Find contradictions**: Identify conflicting instructions and ask which to keep\n2. **Identify the essentials**: Extract what belongs in root AGENTS.md:\n - One-sentence project description\n - Package manager (if not npm)\n - Non-standard build/typecheck commands\n - Anything truly relevant to every single task\n3. **Group the rest**: Organize remaining instructions into logical categories (TypeScript conventions, testing patterns, API design, Git workflow)\n4. **Create the file structure**:\n - Minimal root AGENTS.md with markdown links to separate files\n - Each separate file with relevant instructions\n - Suggested docs/ folder structure\n5. **Flag for deletion**: Identify redundant, vague, or overly obvious instructions\n\n$ARGUMENTS\n" }, { "path": "agents/skills/jj/SKILL.md", "content": "---\nname: jj\ndescription: Uses the jj (Jujutsu) version control system. Use when asked about jj commands, git push/fetch workflow, or rebasing onto main for non git repo\n---\n\n# jj (Jujutsu) Workflow\n\nJujutsu is a Git-compatible VCS. This documents the user's workflow.\n\n## Aliases\n- jj tug: Move closest bookmark to @- (Advances bookmark to parent of working copy)\n- jj retrunk: Rebase onto trunk() (Rebases current branch onto latest main/master)\n- jj lg: Log recent 10 (Shows all revisions, limit 10)\n- jj compare: Compare working copy with parent (Shows changes between working copy and parent)\n\n## Key Concepts\n- `@` refers to the working copy commit\n- `@-` refers to the parent of working copy\n- `trunk()` finds the most recent main/master/trunk on remote\n- `closest_bookmark(@-)` finds the nearest bookmark ancestor\n\n## Conflict Resolution\nWhen conflicts occur after `jj retrunk`:\n1. `jj status` shows conflicted files\n2. Edit files to resolve conflicts\n3. `jj squash` or continue working - jj auto-tracks changes\n" }, { "path": "agents/skills/pi-improvements/SKILL.md", "content": "---\nname: pi-improvements\ndescription: When encountering pi tool limitations, propose focused extensions that solve one problem each.\n---\n\n## Rules\n- When edit fails due to whitespace/indentation, propose line-based editing\n- When file changes between read and write are detected, propose stale-file guarding\n- When bash output is noisy, propose structured output parsing\n- When edits apply blindly, propose preview diffs\n- Each extension must solve exactly one problem\n- Prefer `~/.pi/extensions/name.ts` over folders\n\n## Extension Patterns\n\n**Edit by Line**: Replace exact-text matching with line numbers\n```typescript\nedit_line({ path: \"foo.tsx\", start: 45, end: 52, replacement: \"...\" })\n```\n\n**Edit Preview**: Intercept `edit` tool, show unified diff in TUI overlay\n\n**Bash Summarize**: Parse known tools (vp check, npm test), return structured errors\n\n**File Stale Guard**: Store mtime on `read`, warn on `write` if changed\n\n## When to Propose\n- After 2+ failed edit attempts due to formatting\n- When user manually pipes bash output through grep/head\n- When user discovers wrong edit only after running checks\n- When formatter modifies files between read and write\n" }, { "path": "agents/skills/react-best-practices/AGENTS.md", "content": "# React Best Practices\n\n**Version 1.0.0** \nVercel Engineering \nJanuary 2026\n\n> **Note:** \n> This document is mainly for agents and LLMs to follow when maintaining, \n> generating, or refactoring React and Next.js codebases at Vercel. Humans \n> may also find it useful, but guidance here is optimized for automation \n> and consistency by AI-assisted workflows.\n\n---\n\n## Abstract\n\nComprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.\n\n---\n\n## Table of Contents\n\n1. [Eliminating Waterfalls](#1-eliminating-waterfalls) — **CRITICAL**\n - 1.1 [Defer Await Until Needed](#11-defer-await-until-needed)\n - 1.2 [Dependency-Based Parallelization](#12-dependency-based-parallelization)\n - 1.3 [Prevent Waterfall Chains in API Routes](#13-prevent-waterfall-chains-in-api-routes)\n - 1.4 [Promise.all() for Independent Operations](#14-promiseall-for-independent-operations)\n - 1.5 [Strategic Suspense Boundaries](#15-strategic-suspense-boundaries)\n2. [Bundle Size Optimization](#2-bundle-size-optimization) — **CRITICAL**\n - 2.1 [Avoid Barrel File Imports](#21-avoid-barrel-file-imports)\n - 2.2 [Conditional Module Loading](#22-conditional-module-loading)\n - 2.3 [Defer Non-Critical Third-Party Libraries](#23-defer-non-critical-third-party-libraries)\n - 2.4 [Dynamic Imports for Heavy Components](#24-dynamic-imports-for-heavy-components)\n - 2.5 [Preload Based on User Intent](#25-preload-based-on-user-intent)\n3. [Server-Side Performance](#3-server-side-performance) — **HIGH**\n - 3.1 [Authenticate Server Actions Like API Routes](#31-authenticate-server-actions-like-api-routes)\n - 3.2 [Avoid Duplicate Serialization in RSC Props](#32-avoid-duplicate-serialization-in-rsc-props)\n - 3.3 [Cross-Request LRU Caching](#33-cross-request-lru-caching)\n - 3.4 [Minimize Serialization at RSC Boundaries](#34-minimize-serialization-at-rsc-boundaries)\n - 3.5 [Parallel Data Fetching with Component Composition](#35-parallel-data-fetching-with-component-composition)\n - 3.6 [Per-Request Deduplication with React.cache()](#36-per-request-deduplication-with-reactcache)\n - 3.7 [Use after() for Non-Blocking Operations](#37-use-after-for-non-blocking-operations)\n4. [Client-Side Data Fetching](#4-client-side-data-fetching) — **MEDIUM-HIGH**\n - 4.1 [Deduplicate Global Event Listeners](#41-deduplicate-global-event-listeners)\n - 4.2 [Use Passive Event Listeners for Scrolling Performance](#42-use-passive-event-listeners-for-scrolling-performance)\n - 4.3 [Use SWR for Automatic Deduplication](#43-use-swr-for-automatic-deduplication)\n - 4.4 [Version and Minimize localStorage Data](#44-version-and-minimize-localstorage-data)\n5. [Re-render Optimization](#5-re-render-optimization) — **MEDIUM**\n - 5.1 [Defer State Reads to Usage Point](#51-defer-state-reads-to-usage-point)\n - 5.2 [Do not wrap a simple expression with a primitive result type in useMemo](#52-do-not-wrap-a-simple-expression-with-a-primitive-result-type-in-usememo)\n - 5.3 [Extract Default Non-primitive Parameter Value from Memoized Component to Constant](#53-extract-default-non-primitive-parameter-value-from-memoized-component-to-constant)\n - 5.4 [Extract to Memoized Components](#54-extract-to-memoized-components)\n - 5.5 [Narrow Effect Dependencies](#55-narrow-effect-dependencies)\n - 5.6 [Subscribe to Derived State](#56-subscribe-to-derived-state)\n - 5.7 [Use Functional setState Updates](#57-use-functional-setstate-updates)\n - 5.8 [Use Lazy State Initialization](#58-use-lazy-state-initialization)\n - 5.9 [Use Transitions for Non-Urgent Updates](#59-use-transitions-for-non-urgent-updates)\n6. [Rendering Performance](#6-rendering-performance) — **MEDIUM**\n - 6.1 [Animate SVG Wrapper Instead of SVG Element](#61-animate-svg-wrapper-instead-of-svg-element)\n - 6.2 [CSS content-visibility for Long Lists](#62-css-content-visibility-for-long-lists)\n - 6.3 [Hoist Static JSX Elements](#63-hoist-static-jsx-elements)\n - 6.4 [Optimize SVG Precision](#64-optimize-svg-precision)\n - 6.5 [Prevent Hydration Mismatch Without Flickering](#65-prevent-hydration-mismatch-without-flickering)\n - 6.6 [Use Activity Component for Show/Hide](#66-use-activity-component-for-showhide)\n - 6.7 [Use Explicit Conditional Rendering](#67-use-explicit-conditional-rendering)\n - 6.8 [Use useTransition Over Manual Loading States](#68-use-usetransition-over-manual-loading-states)\n7. [JavaScript Performance](#7-javascript-performance) — **LOW-MEDIUM**\n - 7.1 [Avoid Layout Thrashing](#71-avoid-layout-thrashing)\n - 7.2 [Build Index Maps for Repeated Lookups](#72-build-index-maps-for-repeated-lookups)\n - 7.3 [Cache Property Access in Loops](#73-cache-property-access-in-loops)\n - 7.4 [Cache Repeated Function Calls](#74-cache-repeated-function-calls)\n - 7.5 [Cache Storage API Calls](#75-cache-storage-api-calls)\n - 7.6 [Combine Multiple Array Iterations](#76-combine-multiple-array-iterations)\n - 7.7 [Early Length Check for Array Comparisons](#77-early-length-check-for-array-comparisons)\n - 7.8 [Early Return from Functions](#78-early-return-from-functions)\n - 7.9 [Hoist RegExp Creation](#79-hoist-regexp-creation)\n - 7.10 [Use Loop for Min/Max Instead of Sort](#710-use-loop-for-minmax-instead-of-sort)\n - 7.11 [Use Set/Map for O(1) Lookups](#711-use-setmap-for-o1-lookups)\n - 7.12 [Use toSorted() Instead of sort() for Immutability](#712-use-tosorted-instead-of-sort-for-immutability)\n8. [Advanced Patterns](#8-advanced-patterns) — **LOW**\n - 8.1 [Store Event Handlers in Refs](#81-store-event-handlers-in-refs)\n - 8.2 [useEffectEvent for Stable Callback Refs](#82-useeffectevent-for-stable-callback-refs)\n\n---\n\n## 1. Eliminating Waterfalls\n\n**Impact: CRITICAL**\n\nWaterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.\n\n### 1.1 Defer Await Until Needed\n\n**Impact: HIGH (avoids blocking unused code paths)**\n\nMove `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.\n\n**Incorrect: blocks both branches**\n\n```typescript\nasync function handleRequest(userId: string, skipProcessing: boolean) {\n const userData = await fetchUserData(userId)\n \n if (skipProcessing) {\n // Returns immediately but still waited for userData\n return { skipped: true }\n }\n \n // Only this branch uses userData\n return processUserData(userData)\n}\n```\n\n**Correct: only blocks when needed**\n\n```typescript\nasync function handleRequest(userId: string, skipProcessing: boolean) {\n if (skipProcessing) {\n // Returns immediately without waiting\n return { skipped: true }\n }\n \n // Fetch only when needed\n const userData = await fetchUserData(userId)\n return processUserData(userData)\n}\n```\n\n**Another example: early return optimization**\n\n```typescript\n// Incorrect: always fetches permissions\nasync function updateResource(resourceId: string, userId: string) {\n const permissions = await fetchPermissions(userId)\n const resource = await getResource(resourceId)\n \n if (!resource) {\n return { error: 'Not found' }\n }\n \n if (!permissions.canEdit) {\n return { error: 'Forbidden' }\n }\n \n return await updateResourceData(resource, permissions)\n}\n\n// Correct: fetches only when needed\nasync function updateResource(resourceId: string, userId: string) {\n const resource = await getResource(resourceId)\n \n if (!resource) {\n return { error: 'Not found' }\n }\n \n const permissions = await fetchPermissions(userId)\n \n if (!permissions.canEdit) {\n return { error: 'Forbidden' }\n }\n \n return await updateResourceData(resource, permissions)\n}\n```\n\nThis optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.\n\n### 1.2 Dependency-Based Parallelization\n\n**Impact: CRITICAL (2-10× improvement)**\n\nFor operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.\n\n**Incorrect: profile waits for config unnecessarily**\n\n```typescript\nconst [user, config] = await Promise.all([\n fetchUser(),\n fetchConfig()\n])\nconst profile = await fetchProfile(user.id)\n```\n\n**Correct: config and profile run in parallel**\n\n```typescript\nimport { all } from 'better-all'\n\nconst { user, config, profile } = await all({\n async user() { return fetchUser() },\n async config() { return fetchConfig() },\n async profile() {\n return fetchProfile((await this.$.user).id)\n }\n})\n```\n\n**Alternative without extra dependencies:**\n\n```typescript\nconst userPromise = fetchUser()\nconst profilePromise = userPromise.then(user => fetchProfile(user.id))\n\nconst [user, config, profile] = await Promise.all([\n userPromise,\n fetchConfig(),\n profilePromise\n])\n```\n\nWe can also create all the promises first, and do `Promise.all()` at the end.\n\nReference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)\n\n### 1.3 Prevent Waterfall Chains in API Routes\n\n**Impact: CRITICAL (2-10× improvement)**\n\nIn API routes and Server Actions, start independent operations immediately, even if you don't await them yet.\n\n**Incorrect: config waits for auth, data waits for both**\n\n```typescript\nexport async function GET(request: Request) {\n const session = await auth()\n const config = await fetchConfig()\n const data = await fetchData(session.user.id)\n return Response.json({ data, config })\n}\n```\n\n**Correct: auth and config start immediately**\n\n```typescript\nexport async function GET(request: Request) {\n const sessionPromise = auth()\n const configPromise = fetchConfig()\n const session = await sessionPromise\n const [config, data] = await Promise.all([\n configPromise,\n fetchData(session.user.id)\n ])\n return Response.json({ data, config })\n}\n```\n\nFor operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).\n\n### 1.4 Promise.all() for Independent Operations\n\n**Impact: CRITICAL (2-10× improvement)**\n\nWhen async operations have no interdependencies, execute them concurrently using `Promise.all()`.\n\n**Incorrect: sequential execution, 3 round trips**\n\n```typescript\nconst user = await fetchUser()\nconst posts = await fetchPosts()\nconst comments = await fetchComments()\n```\n\n**Correct: parallel execution, 1 round trip**\n\n```typescript\nconst [user, posts, comments] = await Promise.all([\n fetchUser(),\n fetchPosts(),\n fetchComments()\n])\n```\n\n### 1.5 Strategic Suspense Boundaries\n\n**Impact: HIGH (faster initial paint)**\n\nInstead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.\n\n**Incorrect: wrapper blocked by data fetching**\n\n```tsx\nasync function Page() {\n const data = await fetchData() // Blocks entire page\n \n return (\n
\n
Sidebar
\n
Header
\n
\n \n
\n
Footer
\n
\n )\n}\n```\n\nThe entire layout waits for data even though only the middle section needs it.\n\n**Correct: wrapper shows immediately, data streams in**\n\n```tsx\nfunction Page() {\n return (\n
\n
Sidebar
\n
Header
\n
\n }>\n \n \n
\n
Footer
\n
\n )\n}\n\nasync function DataDisplay() {\n const data = await fetchData() // Only blocks this component\n return
{data.content}
\n}\n```\n\nSidebar, Header, and Footer render immediately. Only DataDisplay waits for data.\n\n**Alternative: share promise across components**\n\n```tsx\nfunction Page() {\n // Start fetch immediately, but don't await\n const dataPromise = fetchData()\n \n return (\n
\n
Sidebar
\n
Header
\n }>\n \n \n \n
Footer
\n
\n )\n}\n\nfunction DataDisplay({ dataPromise }: { dataPromise: Promise }) {\n const data = use(dataPromise) // Unwraps the promise\n return
{data.content}
\n}\n\nfunction DataSummary({ dataPromise }: { dataPromise: Promise }) {\n const data = use(dataPromise) // Reuses the same promise\n return
{data.summary}
\n}\n```\n\nBoth components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.\n\n**When NOT to use this pattern:**\n\n- Critical data needed for layout decisions (affects positioning)\n\n- SEO-critical content above the fold\n\n- Small, fast queries where suspense overhead isn't worth it\n\n- When you want to avoid layout shift (loading → content jump)\n\n**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.\n\n---\n\n## 2. Bundle Size Optimization\n\n**Impact: CRITICAL**\n\nReducing initial bundle size improves Time to Interactive and Largest Contentful Paint.\n\n### 2.1 Avoid Barrel File Imports\n\n**Impact: CRITICAL (200-800ms import cost, slow builds)**\n\nImport directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).\n\nPopular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.\n\n**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.\n\n**Incorrect: imports entire library**\n\n```tsx\nimport { Check, X, Menu } from 'lucide-react'\n// Loads 1,583 modules, takes ~2.8s extra in dev\n// Runtime cost: 200-800ms on every cold start\n\nimport { Button, TextField } from '@mui/material'\n// Loads 2,225 modules, takes ~4.2s extra in dev\n```\n\n**Correct: imports only what you need**\n\n```tsx\nimport Check from 'lucide-react/dist/esm/icons/check'\nimport X from 'lucide-react/dist/esm/icons/x'\nimport Menu from 'lucide-react/dist/esm/icons/menu'\n// Loads only 3 modules (~2KB vs ~1MB)\n\nimport Button from '@mui/material/Button'\nimport TextField from '@mui/material/TextField'\n// Loads only what you use\n```\n\n**Alternative: Next.js 13.5+**\n\n```js\n// next.config.js - use optimizePackageImports\nmodule.exports = {\n experimental: {\n optimizePackageImports: ['lucide-react', '@mui/material']\n }\n}\n\n// Then you can keep the ergonomic barrel imports:\nimport { Check, X, Menu } from 'lucide-react'\n// Automatically transformed to direct imports at build time\n```\n\nDirect imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.\n\nLibraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.\n\nReference: [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)\n\n### 2.2 Conditional Module Loading\n\n**Impact: HIGH (loads large data only when needed)**\n\nLoad large data or modules only when a feature is activated.\n\n**Example: lazy-load animation frames**\n\n```tsx\nfunction AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch> }) {\n const [frames, setFrames] = useState(null)\n\n useEffect(() => {\n if (enabled && !frames && typeof window !== 'undefined') {\n import('./animation-frames.js')\n .then(mod => setFrames(mod.frames))\n .catch(() => setEnabled(false))\n }\n }, [enabled, frames, setEnabled])\n\n if (!frames) return \n return \n}\n```\n\nThe `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.\n\n### 2.3 Defer Non-Critical Third-Party Libraries\n\n**Impact: MEDIUM (loads after hydration)**\n\nAnalytics, logging, and error tracking don't block user interaction. Load them after hydration.\n\n**Incorrect: blocks initial bundle**\n\n```tsx\nimport { Analytics } from '@vercel/analytics/react'\n\nexport default function RootLayout({ children }) {\n return (\n \n \n {children}\n \n \n \n )\n}\n```\n\n**Correct: loads after hydration**\n\n```tsx\nimport dynamic from 'next/dynamic'\n\nconst Analytics = dynamic(\n () => import('@vercel/analytics/react').then(m => m.Analytics),\n { ssr: false }\n)\n\nexport default function RootLayout({ children }) {\n return (\n \n \n {children}\n \n \n \n )\n}\n```\n\n### 2.4 Dynamic Imports for Heavy Components\n\n**Impact: CRITICAL (directly affects TTI and LCP)**\n\nUse `next/dynamic` to lazy-load large components not needed on initial render.\n\n**Incorrect: Monaco bundles with main chunk ~300KB**\n\n```tsx\nimport { MonacoEditor } from './monaco-editor'\n\nfunction CodePanel({ code }: { code: string }) {\n return \n}\n```\n\n**Correct: Monaco loads on demand**\n\n```tsx\nimport dynamic from 'next/dynamic'\n\nconst MonacoEditor = dynamic(\n () => import('./monaco-editor').then(m => m.MonacoEditor),\n { ssr: false }\n)\n\nfunction CodePanel({ code }: { code: string }) {\n return \n}\n```\n\n### 2.5 Preload Based on User Intent\n\n**Impact: MEDIUM (reduces perceived latency)**\n\nPreload heavy bundles before they're needed to reduce perceived latency.\n\n**Example: preload on hover/focus**\n\n```tsx\nfunction EditorButton({ onClick }: { onClick: () => void }) {\n const preload = () => {\n if (typeof window !== 'undefined') {\n void import('./monaco-editor')\n }\n }\n\n return (\n \n Open Editor\n \n )\n}\n```\n\n**Example: preload when feature flag is enabled**\n\n```tsx\nfunction FlagsProvider({ children, flags }: Props) {\n useEffect(() => {\n if (flags.editorEnabled && typeof window !== 'undefined') {\n void import('./monaco-editor').then(mod => mod.init())\n }\n }, [flags.editorEnabled])\n\n return \n {children}\n \n}\n```\n\nThe `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.\n\n---\n\n## 3. Server-Side Performance\n\n**Impact: HIGH**\n\nOptimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.\n\n### 3.1 Authenticate Server Actions Like API Routes\n\n**Impact: CRITICAL (prevents unauthorized access to server mutations)**\n\nServer Actions (functions with `\"use server\"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.\n\nNext.js documentation explicitly states: \"Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation.\"\n\n**Incorrect: no authentication check**\n\n```typescript\n'use server'\n\nexport async function deleteUser(userId: string) {\n // Anyone can call this! No auth check\n await db.user.delete({ where: { id: userId } })\n return { success: true }\n}\n```\n\n**Correct: authentication inside the action**\n\n```typescript\n'use server'\n\nimport { verifySession } from '@/lib/auth'\nimport { unauthorized } from '@/lib/errors'\n\nexport async function deleteUser(userId: string) {\n // Always check auth inside the action\n const session = await verifySession()\n \n if (!session) {\n throw unauthorized('Must be logged in')\n }\n \n // Check authorization too\n if (session.user.role !== 'admin' && session.user.id !== userId) {\n throw unauthorized('Cannot delete other users')\n }\n \n await db.user.delete({ where: { id: userId } })\n return { success: true }\n}\n```\n\n**With input validation:**\n\n```typescript\n'use server'\n\nimport { verifySession } from '@/lib/auth'\nimport { z } from 'zod'\n\nconst updateProfileSchema = z.object({\n userId: z.string().uuid(),\n name: z.string().min(1).max(100),\n email: z.string().email()\n})\n\nexport async function updateProfile(data: unknown) {\n // Validate input first\n const validated = updateProfileSchema.parse(data)\n \n // Then authenticate\n const session = await verifySession()\n if (!session) {\n throw new Error('Unauthorized')\n }\n \n // Then authorize\n if (session.user.id !== validated.userId) {\n throw new Error('Can only update own profile')\n }\n \n // Finally perform the mutation\n await db.user.update({\n where: { id: validated.userId },\n data: {\n name: validated.name,\n email: validated.email\n }\n })\n \n return { success: true }\n}\n```\n\nReference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)\n\n### 3.2 Avoid Duplicate Serialization in RSC Props\n\n**Impact: LOW (reduces network payload by avoiding duplicate serialization)**\n\nRSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.\n\n**Incorrect: duplicates array**\n\n```tsx\n// RSC: sends 6 strings (2 arrays × 3 items)\n\n```\n\n**Correct: sends 3 strings**\n\n```tsx\n// RSC: send once\n\n\n// Client: transform there\n'use client'\nconst sorted = useMemo(() => [...usernames].sort(), [usernames])\n```\n\n**Nested deduplication behavior:**\n\n```tsx\n// string[] - duplicates everything\nusernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings\n\n// object[] - duplicates array structure only\nusers={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)\n```\n\nDeduplication works recursively. Impact varies by data type:\n\n- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated\n\n- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference\n\n**Operations breaking deduplication: create new references**\n\n- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`\n\n- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`\n\n**More examples:**\n\n```tsx\n// ❌ Bad\n u.active)} />\n\n\n// ✅ Good\n\n\n// Do filtering/destructuring in client\n```\n\n**Exception:** Pass derived data when transformation is expensive or client doesn't need original.\n\n### 3.3 Cross-Request LRU Caching\n\n**Impact: HIGH (caches across requests)**\n\n`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.\n\n**Implementation:**\n\n```typescript\nimport { LRUCache } from 'lru-cache'\n\nconst cache = new LRUCache({\n max: 1000,\n ttl: 5 * 60 * 1000 // 5 minutes\n})\n\nexport async function getUser(id: string) {\n const cached = cache.get(id)\n if (cached) return cached\n\n const user = await db.user.findUnique({ where: { id } })\n cache.set(id, user)\n return user\n}\n\n// Request 1: DB query, result cached\n// Request 2: cache hit, no DB query\n```\n\nUse when sequential user actions hit multiple endpoints needing the same data within seconds.\n\n**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.\n\n**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.\n\nReference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)\n\n### 3.4 Minimize Serialization at RSC Boundaries\n\n**Impact: HIGH (reduces data transfer size)**\n\nThe React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.\n\n**Incorrect: serializes all 50 fields**\n\n```tsx\nasync function Page() {\n const user = await fetchUser() // 50 fields\n return \n}\n\n'use client'\nfunction Profile({ user }: { user: User }) {\n return
{user.name}
// uses 1 field\n}\n```\n\n**Correct: serializes only 1 field**\n\n```tsx\nasync function Page() {\n const user = await fetchUser()\n return \n}\n\n'use client'\nfunction Profile({ name }: { name: string }) {\n return
{name}
\n}\n```\n\n### 3.5 Parallel Data Fetching with Component Composition\n\n**Impact: CRITICAL (eliminates server-side waterfalls)**\n\nReact Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.\n\n**Incorrect: Sidebar waits for Page's fetch to complete**\n\n```tsx\nexport default async function Page() {\n const header = await fetchHeader()\n return (\n
\n
{header}
\n \n
\n )\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return \n}\n```\n\n**Correct: both fetch simultaneously**\n\n```tsx\nasync function Header() {\n const data = await fetchHeader()\n return
{data}
\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return \n}\n\nexport default function Page() {\n return (\n
\n
\n \n
\n )\n}\n```\n\n**Alternative with children prop:**\n\n```tsx\nasync function Header() {\n const data = await fetchHeader()\n return
{data}
\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return \n}\n\nfunction Layout({ children }: { children: ReactNode }) {\n return (\n
\n
\n {children}\n
\n )\n}\n\nexport default function Page() {\n return (\n \n \n \n )\n}\n```\n\n### 3.6 Per-Request Deduplication with React.cache()\n\n**Impact: MEDIUM (deduplicates within request)**\n\nUse `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.\n\n**Usage:**\n\n```typescript\nimport { cache } from 'react'\n\nexport const getCurrentUser = cache(async () => {\n const session = await auth()\n if (!session?.user?.id) return null\n return await db.user.findUnique({\n where: { id: session.user.id }\n })\n})\n```\n\nWithin a single request, multiple calls to `getCurrentUser()` execute the query only once.\n\n**Avoid inline objects as arguments:**\n\n`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.\n\n**Incorrect: always cache miss**\n\n```typescript\nconst getUser = cache(async (params: { uid: number }) => {\n return await db.user.findUnique({ where: { id: params.uid } })\n})\n\n// Each call creates new object, never hits cache\ngetUser({ uid: 1 })\ngetUser({ uid: 1 }) // Cache miss, runs query again\n```\n\n**Correct: cache hit**\n\n```typescript\nconst params = { uid: 1 }\ngetUser(params) // Query runs\ngetUser(params) // Cache hit (same reference)\n```\n\nIf you must pass objects, pass the same reference:\n\n**Next.js-Specific Note:**\n\nIn Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:\n\n- Database queries (Prisma, Drizzle, etc.)\n\n- Heavy computations\n\n- Authentication checks\n\n- File system operations\n\n- Any non-fetch async work\n\nUse `React.cache()` to deduplicate these operations across your component tree.\n\nReference: [https://react.dev/reference/react/cache](https://react.dev/reference/react/cache)\n\n### 3.7 Use after() for Non-Blocking Operations\n\n**Impact: MEDIUM (faster response times)**\n\nUse Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.\n\n**Incorrect: blocks response**\n\n```tsx\nimport { logUserAction } from '@/app/utils'\n\nexport async function POST(request: Request) {\n // Perform mutation\n await updateDatabase(request)\n \n // Logging blocks the response\n const userAgent = request.headers.get('user-agent') || 'unknown'\n await logUserAction({ userAgent })\n \n return new Response(JSON.stringify({ status: 'success' }), {\n status: 200,\n headers: { 'Content-Type': 'application/json' }\n })\n}\n```\n\n**Correct: non-blocking**\n\n```tsx\nimport { after } from 'next/server'\nimport { headers, cookies } from 'next/headers'\nimport { logUserAction } from '@/app/utils'\n\nexport async function POST(request: Request) {\n // Perform mutation\n await updateDatabase(request)\n \n // Log after response is sent\n after(async () => {\n const userAgent = (await headers()).get('user-agent') || 'unknown'\n const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'\n \n logUserAction({ sessionCookie, userAgent })\n })\n \n return new Response(JSON.stringify({ status: 'success' }), {\n status: 200,\n headers: { 'Content-Type': 'application/json' }\n })\n}\n```\n\nThe response is sent immediately while logging happens in the background.\n\n**Common use cases:**\n\n- Analytics tracking\n\n- Audit logging\n\n- Sending notifications\n\n- Cache invalidation\n\n- Cleanup tasks\n\n**Important notes:**\n\n- `after()` runs even if the response fails or redirects\n\n- Works in Server Actions, Route Handlers, and Server Components\n\nReference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)\n\n---\n\n## 4. Client-Side Data Fetching\n\n**Impact: MEDIUM-HIGH**\n\nAutomatic deduplication and efficient data fetching patterns reduce redundant network requests.\n\n### 4.1 Deduplicate Global Event Listeners\n\n**Impact: LOW (single listener for N components)**\n\nUse `useSWRSubscription()` to share global event listeners across component instances.\n\n**Incorrect: N instances = N listeners**\n\n```tsx\nfunction useKeyboardShortcut(key: string, callback: () => void) {\n useEffect(() => {\n const handler = (e: KeyboardEvent) => {\n if (e.metaKey && e.key === key) {\n callback()\n }\n }\n window.addEventListener('keydown', handler)\n return () => window.removeEventListener('keydown', handler)\n }, [key, callback])\n}\n```\n\nWhen using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.\n\n**Correct: N instances = 1 listener**\n\n```tsx\nimport useSWRSubscription from 'swr/subscription'\n\n// Module-level Map to track callbacks per key\nconst keyCallbacks = new Map void>>()\n\nfunction useKeyboardShortcut(key: string, callback: () => void) {\n // Register this callback in the Map\n useEffect(() => {\n if (!keyCallbacks.has(key)) {\n keyCallbacks.set(key, new Set())\n }\n keyCallbacks.get(key)!.add(callback)\n\n return () => {\n const set = keyCallbacks.get(key)\n if (set) {\n set.delete(callback)\n if (set.size === 0) {\n keyCallbacks.delete(key)\n }\n }\n }\n }, [key, callback])\n\n useSWRSubscription('global-keydown', () => {\n const handler = (e: KeyboardEvent) => {\n if (e.metaKey && keyCallbacks.has(e.key)) {\n keyCallbacks.get(e.key)!.forEach(cb => cb())\n }\n }\n window.addEventListener('keydown', handler)\n return () => window.removeEventListener('keydown', handler)\n })\n}\n\nfunction Profile() {\n // Multiple shortcuts will share the same listener\n useKeyboardShortcut('p', () => { /* ... */ }) \n useKeyboardShortcut('k', () => { /* ... */ })\n // ...\n}\n```\n\n### 4.2 Use Passive Event Listeners for Scrolling Performance\n\n**Impact: MEDIUM (eliminates scroll delay caused by event listeners)**\n\nAdd `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.\n\n**Incorrect:**\n\n```typescript\nuseEffect(() => {\n const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)\n const handleWheel = (e: WheelEvent) => console.log(e.deltaY)\n \n document.addEventListener('touchstart', handleTouch)\n document.addEventListener('wheel', handleWheel)\n \n return () => {\n document.removeEventListener('touchstart', handleTouch)\n document.removeEventListener('wheel', handleWheel)\n }\n}, [])\n```\n\n**Correct:**\n\n```typescript\nuseEffect(() => {\n const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)\n const handleWheel = (e: WheelEvent) => console.log(e.deltaY)\n \n document.addEventListener('touchstart', handleTouch, { passive: true })\n document.addEventListener('wheel', handleWheel, { passive: true })\n \n return () => {\n document.removeEventListener('touchstart', handleTouch)\n document.removeEventListener('wheel', handleWheel)\n }\n}, [])\n```\n\n**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.\n\n**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.\n\n### 4.3 Use SWR for Automatic Deduplication\n\n**Impact: MEDIUM-HIGH (automatic deduplication)**\n\nSWR enables request deduplication, caching, and revalidation across component instances.\n\n**Incorrect: no deduplication, each instance fetches**\n\n```tsx\nfunction UserList() {\n const [users, setUsers] = useState([])\n useEffect(() => {\n fetch('/api/users')\n .then(r => r.json())\n .then(setUsers)\n }, [])\n}\n```\n\n**Correct: multiple instances share one request**\n\n```tsx\nimport useSWR from 'swr'\n\nfunction UserList() {\n const { data: users } = useSWR('/api/users', fetcher)\n}\n```\n\n**For immutable data:**\n\n```tsx\nimport { useImmutableSWR } from '@/lib/swr'\n\nfunction StaticContent() {\n const { data } = useImmutableSWR('/api/config', fetcher)\n}\n```\n\n**For mutations:**\n\n```tsx\nimport { useSWRMutation } from 'swr/mutation'\n\nfunction UpdateButton() {\n const { trigger } = useSWRMutation('/api/user', updateUser)\n return \n}\n```\n\nReference: [https://swr.vercel.app](https://swr.vercel.app)\n\n### 4.4 Version and Minimize localStorage Data\n\n**Impact: MEDIUM (prevents schema conflicts, reduces storage size)**\n\nAdd version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.\n\n**Incorrect:**\n\n```typescript\n// No version, stores everything, no error handling\nlocalStorage.setItem('userConfig', JSON.stringify(fullUserObject))\nconst data = localStorage.getItem('userConfig')\n```\n\n**Correct:**\n\n```typescript\nconst VERSION = 'v2'\n\nfunction saveConfig(config: { theme: string; language: string }) {\n try {\n localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))\n } catch {\n // Throws in incognito/private browsing, quota exceeded, or disabled\n }\n}\n\nfunction loadConfig() {\n try {\n const data = localStorage.getItem(`userConfig:${VERSION}`)\n return data ? JSON.parse(data) : null\n } catch {\n return null\n }\n}\n\n// Migration from v1 to v2\nfunction migrate() {\n try {\n const v1 = localStorage.getItem('userConfig:v1')\n if (v1) {\n const old = JSON.parse(v1)\n saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })\n localStorage.removeItem('userConfig:v1')\n }\n } catch {}\n}\n```\n\n**Store minimal fields from server responses:**\n\n```typescript\n// User object has 20+ fields, only store what UI needs\nfunction cachePrefs(user: FullUser) {\n try {\n localStorage.setItem('prefs:v1', JSON.stringify({\n theme: user.preferences.theme,\n notifications: user.preferences.notifications\n }))\n } catch {}\n}\n```\n\n**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.\n\n**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.\n\n---\n\n## 5. Re-render Optimization\n\n**Impact: MEDIUM**\n\nReducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.\n\n### 5.1 Defer State Reads to Usage Point\n\n**Impact: MEDIUM (avoids unnecessary subscriptions)**\n\nDon't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.\n\n**Incorrect: subscribes to all searchParams changes**\n\n```tsx\nfunction ShareButton({ chatId }: { chatId: string }) {\n const searchParams = useSearchParams()\n\n const handleShare = () => {\n const ref = searchParams.get('ref')\n shareChat(chatId, { ref })\n }\n\n return \n}\n```\n\n**Correct: reads on demand, no subscription**\n\n```tsx\nfunction ShareButton({ chatId }: { chatId: string }) {\n const handleShare = () => {\n const params = new URLSearchParams(window.location.search)\n const ref = params.get('ref')\n shareChat(chatId, { ref })\n }\n\n return \n}\n```\n\n### 5.2 Do not wrap a simple expression with a primitive result type in useMemo\n\n**Impact: LOW-MEDIUM (wasted computation on every render)**\n\nWhen an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`.\n\nCalling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.\n\n**Incorrect:**\n\n```tsx\nfunction Header({ user, notifications }: Props) {\n const isLoading = useMemo(() => {\n return user.isLoading || notifications.isLoading\n }, [user.isLoading, notifications.isLoading])\n\n if (isLoading) return \n // return some markup\n}\n```\n\n**Correct:**\n\n```tsx\nfunction Header({ user, notifications }: Props) {\n const isLoading = user.isLoading || notifications.isLoading\n\n if (isLoading) return \n // return some markup\n}\n```\n\n### 5.3 Extract Default Non-primitive Parameter Value from Memoized Component to Constant\n\n**Impact: MEDIUM (restores memoization by using a constant for default value)**\n\nWhen memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict equality comparison in `memo()`.\n\nTo address this issue, extract the default value into a constant.\n\n**Incorrect: `onClick` has different values on every rerender**\n\n```tsx\nconst UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {\n // ...\n})\n\n// Used without optional onClick\n\n```\n\n**Correct: stable default value**\n\n```tsx\nconst NOOP = () => {};\n\nconst UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) {\n // ...\n})\n\n// Used without optional onClick\n\n```\n\n### 5.4 Extract to Memoized Components\n\n**Impact: MEDIUM (enables early returns)**\n\nExtract expensive work into memoized components to enable early returns before computation.\n\n**Incorrect: computes avatar even when loading**\n\n```tsx\nfunction Profile({ user, loading }: Props) {\n const avatar = useMemo(() => {\n const id = computeAvatarId(user)\n return \n }, [user])\n\n if (loading) return \n return
{avatar}
\n}\n```\n\n**Correct: skips computation when loading**\n\n```tsx\nconst UserAvatar = memo(function UserAvatar({ user }: { user: User }) {\n const id = useMemo(() => computeAvatarId(user), [user])\n return \n})\n\nfunction Profile({ user, loading }: Props) {\n if (loading) return \n return (\n
\n \n
\n )\n}\n```\n\n**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.\n\n### 5.5 Narrow Effect Dependencies\n\n**Impact: LOW (minimizes effect re-runs)**\n\nSpecify primitive dependencies instead of objects to minimize effect re-runs.\n\n**Incorrect: re-runs on any user field change**\n\n```tsx\nuseEffect(() => {\n console.log(user.id)\n}, [user])\n```\n\n**Correct: re-runs only when id changes**\n\n```tsx\nuseEffect(() => {\n console.log(user.id)\n}, [user.id])\n```\n\n**For derived state, compute outside effect:**\n\n```tsx\n// Incorrect: runs on width=767, 766, 765...\nuseEffect(() => {\n if (width < 768) {\n enableMobileMode()\n }\n}, [width])\n\n// Correct: runs only on boolean transition\nconst isMobile = width < 768\nuseEffect(() => {\n if (isMobile) {\n enableMobileMode()\n }\n}, [isMobile])\n```\n\n### 5.6 Subscribe to Derived State\n\n**Impact: MEDIUM (reduces re-render frequency)**\n\nSubscribe to derived boolean state instead of continuous values to reduce re-render frequency.\n\n**Incorrect: re-renders on every pixel change**\n\n```tsx\nfunction Sidebar() {\n const width = useWindowWidth() // updates continuously\n const isMobile = width < 768\n return