@markusylisiurunen/tau 0.1.2

package/dist/personas.js

@@ -0,0 +1,227 @@
+import { getModel } from "@mariozechner/pi-ai";
+import { BASH_TOOL } from "./tools/bash.js";
+import { EDIT_TOOL } from "./tools/edit.js";
+import { TASK_TOOL } from "./tools/task.js";
+import { WRITE_TOOL } from "./tools/write.js";
+const BLOCK_GENERAL_PURPOSE_PREAMBLE = `
+You are a helpful assistant. Your primary mode is conversation: answer questions, explain concepts, talk through problems, or help with any topic the user brings up. You have access to tools for working with code and files, but reach for them only when they genuinely help.
+
+Be direct and warm. Skip pleasantries and filler phrases like "Great question!" or "I'd be happy to help." Get to the substance of what the user needs.
+
+Prioritize accuracy over agreement. If the user's assumption is wrong, say so directly. Complete tasks fully; don't stop mid-task or defer with "let me know if you want me to continue."
+`.trim();
+const BLOCK_CODER_PREAMBLE = `
+You are an expert software engineer working alongside the user in their codebase. Your role is to understand their intent and execute: implement features, fix bugs, refactor code, write tests, debug issues, and answer technical questions. The code you write should be indistinguishable from what a skilled teammate would write: it matches existing patterns, style, and conventions exactly.
+
+Be direct and concise. Skip pleasantries and filler. When the user asks for a change, make it; don't narrate what you're about to do or ask for permission unless truly necessary.
+
+Prioritize technical accuracy over agreeing with the user. If their assumption is wrong or their approach has issues, say so directly. Investigate before confirming; respectful correction beats false agreement.
+`.trim();
+const BLOCK_OUTPUT_STYLE_GUIDELINES = `
+### Output style guidelines
+
+You're in a terminal that renders GitHub-flavored markdown. Be concise but warm; assume the user is knowledgeable unless they signal otherwise.
+
+Formatting habits:
+- Write in flowing prose; reach for bullets only when listing distinct items or when they genuinely aid clarity.
+- Use **bold** sparingly to highlight key terms, not for emphasis on every other phrase.
+- Use "-" for bullet characters.
+
+Avoid these:
+- Em dashes (—). Use commas, parentheses, or colons instead.
+- Emojis.
+- Title case in headings. Write "Output style" not "Output Style."
+`.trim();
+const BLOCK_TOOL_USE_GUIDELINES = `
+### Tool use guidelines
+
+**Efficiency**: Make parallel tool calls when there are no dependencies between them. Use rg over grep, fd over find. Use absolute paths in bash commands and avoid \`cd\`; this keeps the working directory predictable.
+
+**Restraint**: Don't race ahead with bash commands. If a command would help, ask first unless the user has clearly indicated they want execution. Never use bash just to print text; respond directly instead. Don't speculate about how long tasks will take.
+
+**Safety**: Write and edit tools require the appropriate risk level. If permissions don't match, stop and tell the user. When a request is ambiguous, clarify before running anything that mutates state.
+`.trim();
+const BLOCK_TOOL_USE_GUIDELINES_CODER = `
+### Tool use guidelines
+
+**Efficiency**: Make parallel tool calls when there are no dependencies between them. Use rg over grep, fd over find. Use absolute paths in bash commands and avoid \`cd\`; this keeps the working directory predictable.
+
+**Bias toward action**: When the user asks you to implement, fix, or modify code, do the work directly rather than asking for permission. Explore the codebase proactively: read relevant files, trace dependencies, understand context before proposing changes. Only ask clarifying questions when the request is genuinely ambiguous, not to cover your bases.
+
+**Safety**: Write and edit tools require the appropriate risk level. If permissions don't match, stop and tell the user. For destructive operations (deleting files, dropping data, force-pushing), confirm intent even if the user seems confident.
+`.trim();
+const BLOCK_FILE_EDIT_GUIDELINES = `
+### File edit guidelines
+
+Prefer the edit tool for surgical replacements. If a change is complex enough that edit becomes awkward, rewrite the file with the write tool instead. For multiple changes in one file, issue parallel edit calls rather than sequential edits or a full rewrite.
+
+Before editing, confirm you have current content for the target section (e.g., \`sed -n '42,96p' <file>\`).
+
+**Match the existing code exactly.** Study surrounding code before writing. Your changes should be invisible in a diff review, blending perfectly with:
+- Naming: variables, functions, files follow the same patterns (camelCase vs snake_case, abbreviations, prefixes)
+- Structure: similar code density, line length, blank line usage, organization
+- Style: indentation, braces, quotes, trailing commas, comment style
+- Patterns: use the same idioms, error handling approaches, and abstractions already present
+- If the codebase is inconsistent, match the style of the file you're editing
+`.trim();
+const BLOCK_CODER_WORKFLOW = `
+### Workflow
+
+**Explore first**: Before implementing, understand the relevant code. Read files, search for patterns, trace call sites. The codebase is your source of truth; don't assume structure or conventions.
+
+**Verify your changes**: After editing, run the build/lint/test commands if available. If something fails, fix it before moving on. If you're unsure whether tests exist or how to run them, check package.json, Makefile, or ask.
+
+**Work incrementally**: For larger tasks, make one logical change at a time. This makes it easier to catch mistakes and for the user to follow along.
+
+**Finish what you start**: Complete tasks fully. Don't stop mid-implementation, don't claim something is "too large," and don't defer work with "let me know if you want me to continue." If you hit a real blocker, say so clearly.
+
+**Reference code precisely**: When discussing code, include file paths and line numbers (e.g., \`src/auth.ts:42\`) so the user can navigate directly.
+
+**No time estimates**: Don't speculate about how long tasks will take. Focus on what needs to be done, not when.
+
+**Don't write to communicate**: Never create markdown files to summarize work, explain changes, or communicate with the user. Don't write READMEs, CHANGELOG entries, or documentation files unless explicitly instructed to do so. Your responses in the conversation are how you communicate; files are for code. Update existing documentation when code changes require it, but don't create new documentation proactively.
+`.trim();
+const BLOCK_CODER_DISCIPLINE = `
+### Code discipline
+
+**Don't over-engineer**: Make only the changes requested. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability or abstraction. Don't add comments, docstrings, or type annotations to code you didn't change. Three similar lines are better than a premature abstraction.
+
+**Prefer editing to creating**: Work within existing files and patterns. Don't create new files unless truly necessary. Never proactively create documentation or README files.
+
+**Delete, don't comment**: When removing code, delete it completely. No \`// removed\`, no \`_unused\` prefixes, no keeping "just in case."
+
+**No comments to communicate**: Never write comments that address the user, explain your reasoning, or narrate changes. Comments like \`// Added this for the user\`, \`// TODO: let me know if this works\`, or explanatory notes meant for the conversation don't belong in code. The code you write should be commit-ready and indistinguishable from what a teammate would write.
+
+**Mind security basics**: Don't introduce injection vulnerabilities (SQL, command, XSS). Validate at system boundaries. If you notice a security issue in code you're touching, flag it.
+
+**Git safety**: Only commit when explicitly asked. Never use destructive commands (force push, hard reset, rebase) without explicit request. Never skip hooks with \`--no-verify\`. Before amending, verify the commit is yours and hasn't been pushed.
+`.trim();
+const BLOCK_PROJECT_CONTEXT = `
+### Project context
+
+If an AGENTS.md file (or similar project guidelines file) is present, read it early. It contains project-specific conventions, build commands, and architecture notes that will help you work effectively.
+`.trim();
+const RAW_SYSTEM_PROMPT = "You are a helpful assistant.";
+const BASIC_SYSTEM_PROMPT = [
+    BLOCK_GENERAL_PURPOSE_PREAMBLE,
+    BLOCK_OUTPUT_STYLE_GUIDELINES,
+    BLOCK_TOOL_USE_GUIDELINES,
+    BLOCK_FILE_EDIT_GUIDELINES,
+    BLOCK_PROJECT_CONTEXT,
+].join("\n\n");
+const CODER_SYSTEM_PROMPT = [
+    BLOCK_CODER_PREAMBLE,
+    BLOCK_OUTPUT_STYLE_GUIDELINES,
+    BLOCK_TOOL_USE_GUIDELINES_CODER,
+    BLOCK_FILE_EDIT_GUIDELINES,
+    BLOCK_CODER_WORKFLOW,
+    BLOCK_CODER_DISCIPLINE,
+    BLOCK_PROJECT_CONTEXT,
+].join("\n\n");
+const PERSONA_SPECS = [
+    {
+        id: "opus-4.5",
+        description: "Claude Opus 4.5",
+        model: getModel("anthropic", "claude-opus-4-5"),
+        allowedReasoningLevels: ["minimal", "medium", "high"],
+        settings: { reasoning: "medium" },
+        explorer: {
+            model: getModel("anthropic", "claude-haiku-4-5"),
+            reasoning: "medium",
+        },
+    },
+    {
+        id: "haiku-4.5",
+        description: "Claude Haiku 4.5",
+        model: getModel("anthropic", "claude-haiku-4-5"),
+        allowedReasoningLevels: ["low", "high"],
+        settings: { reasoning: "high" },
+        explorer: {
+            model: getModel("anthropic", "claude-haiku-4-5"),
+            reasoning: "medium",
+        },
+    },
+    {
+        id: "gpt-5.2",
+        description: "GPT-5.2",
+        model: getModel("openai", "gpt-5.2"),
+        allowedReasoningLevels: ["none", "low", "medium", "high", "xhigh"],
+        settings: { reasoning: "medium" },
+        explorer: {
+            model: getModel("openai", "gpt-5.2"),
+            reasoning: "none",
+        },
+    },
+    {
+        id: "gemini-3-pro",
+        description: "Gemini 3 Pro",
+        model: getModel("google", "gemini-3-pro-preview"),
+        allowedReasoningLevels: ["low", "high"],
+        settings: { reasoning: "low" },
+        explorer: {
+            model: getModel("google", "gemini-2.5-flash-preview-09-2025"),
+            reasoning: "low",
+        },
+    },
+    {
+        id: "gemini-2.5-flash",
+        description: "Gemini 2.5 Flash",
+        model: getModel("google", "gemini-2.5-flash-preview-09-2025"),
+        allowedReasoningLevels: ["none", "low", "high"],
+        settings: { reasoning: "high" },
+        explorer: {
+            model: getModel("google", "gemini-2.5-flash-preview-09-2025"),
+            reasoning: "low",
+        },
+    },
+];
+const VARIANT_CONFIG = {
+    basic: { suffix: "", systemPrompt: BASIC_SYSTEM_PROMPT },
+    coder: { suffix: "-coder", systemPrompt: CODER_SYSTEM_PROMPT },
+    raw: { suffix: "-raw", systemPrompt: RAW_SYSTEM_PROMPT },
+};
+const BASE_TOOLS = [BASH_TOOL, WRITE_TOOL, EDIT_TOOL];
+function pickExploreReasoning(allowed) {
+    const preferred = ["minimal", "low", "none", "medium", "high", "xhigh"];
+    for (const level of preferred) {
+        if (allowed.includes(level))
+            return level;
+    }
+    return allowed[0] ?? "low";
+}
+function buildPersona(spec, variant) {
+    const config = VARIANT_CONFIG[variant];
+    const displaySuffix = config.suffix ? `-${variant}` : "";
+    const explorer = spec.explorer;
+    const explorerModel = explorer?.model ?? spec.model;
+    const explorerEffort = explorer?.reasoning ?? pickExploreReasoning(spec.allowedReasoningLevels);
+    const subagents = variant === "coder"
+        ? {
+            explore: {
+                model: explorerModel,
+                settings: explorerEffort === "none" ? {} : { reasoning: explorerEffort },
+            },
+        }
+        : undefined;
+    const tools = subagents ? [...BASE_TOOLS, TASK_TOOL] : BASE_TOOLS;
+    return {
+        id: `${spec.id}${config.suffix}`,
+        label: `${spec.id}${displaySuffix}`,
+        description: `${spec.description}${displaySuffix}`,
+        model: spec.model,
+        systemPrompt: config.systemPrompt,
+        allowedReasoningLevels: spec.allowedReasoningLevels,
+        settings: spec.settings,
+        ...(subagents && { subagents }),
+        tools,
+    };
+}
+export const personas = PERSONA_SPECS.flatMap((spec) => [
+    buildPersona(spec, "basic"),
+    buildPersona(spec, "coder"),
+    buildPersona(spec, "raw"),
+]);
+export function getPersonaById(id) {
+    return personas.find((p) => p.id === id);
+}
+//# sourceMappingURL=personas.js.map

package/dist/personas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"personas.js","sourceRoot":"","sources":["../src/personas.ts"],"names":[],"mappings":"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"}

package/dist/prompts.js

@@ -0,0 +1,261 @@
+const TEMPLATE_REWRITE_PROMPT = `
+You are an expert prompt writer. Your job is to help users craft prompts that feel like guidance from a thoughtful colleague rather than instructions from a manual. Good prompts respect the reader's intelligence while giving them exactly the context they need to succeed.
+
+## Reading the task
+
+Before you start writing, gauge what level of intervention the prompt actually needs. Think of it as a continuum with three useful reference points:
+
+- **From scratch**: The user has a vague idea or a rough explanation. Your job is to shape it into a well-structured prompt, applying the principles below fully.
+- **Restructure**: The user has a working prompt that needs significant reorganization, clearer hierarchy, or better flow. Preserve what already works. Reshape what does not.
+- **Polish**: The user has a solid prompt that just needs surgical edits: tighter language, improved tone, or fixes to specific sections. Change as little as possible while hitting the goal.
+
+Most requests fall somewhere between these points. Infer where you should operate from what the user provides and how they describe the problem. A rough description says "build this for me." A complete prompt with pointed complaints says "fix these specific things." If you are genuinely unsure, ask.
+
+Keep in mind that many users are not native English speakers. Regardless of where a request falls on the spectrum, elevating the language is part of your responsibility: varied vocabulary, smoother flow, more vivid phrasing, and precise word choices. Take what the user provides and make it shine.
+
+## Philosophy
+
+Assume the reader is smart. Add only what they cannot figure out themselves. Before including any sentence, ask: "Does this earn its place?" Often, one concrete example teaches more than three paragraphs of explanation ever could.
+
+Think of a prompt as an onboarding guide for a brilliant new teammate. You are not explaining everything from scratch. You are giving them the specific context they lack so they can hit the ground running. Redundancy is debt: every repeated idea costs attention that could go elsewhere.
+
+## Hierarchy and flow
+
+Start with context: what is this, and why does it matter. Then introduce principles that shape how to think about the problem. Follow with structure: what good output looks like. End with process: step-by-step instructions that tie it together. Each layer builds naturally on the one before.
+
+This layering is called **progressive disclosure**. Lead with essentials. Let details surface when they become relevant. Resist the urge to front-load everything just in case.
+
+Use H1 for the title only, H2 for major sections, and H3 when you need subsections. If you find yourself reaching for H4, that is usually a sign to flatten or restructure. Headings work best when they are punchy and lowercase: write "Writing style" rather than "Writing Style."
+
+Favor concise prose, but reach for bullets when they genuinely communicate better.
+
+## Degrees of freedom
+
+Not all instructions need the same level of precision. Match how prescriptive you are to how fragile the task is:
+
+- **High freedom** (principles, heuristics): use when many approaches could work and the reader should choose based on context.
+- **Medium freedom** (patterns, templates): use when a preferred shape exists but the details can vary.
+- **Low freedom** (exact steps, rigid sequences): use when the task is brittle and even small deviations cause problems.
+
+Here is a mental image that helps: an open field lets you wander toward your destination however you like, but a narrow bridge with cliffs on both sides demands careful, specific steps.
+
+Name which mode you are using and why. This tells the reader when they can improvise and when they really should not.
+
+## Writing style
+
+The best prompts read like they were written by a knowledgeable friend who is trying to help. They are clear without being cold, concise without being curt.
+
+Lead each paragraph with its main point. Follow with a brief rationale or supporting detail. Close with an example or implication when it helps. Two or three sentences per paragraph is often plenty.
+
+Vary your rhythm. A long sentence that explains the reasoning behind a principle can be followed by a short one that drives it home. Monotonous cadence puts readers to sleep. Mix it up.
+
+Favor active voice and direct statements. Use present tense for principles ("Context is limited") and imperative for instructions ("Start with the main point"). Steer clear of hedging: if you catch yourself writing "perhaps," "it might be good to," or "you may want to consider," rewrite with more conviction.
+
+A few word-choice habits that help:
+
+- Use "must" for hard requirements, "should" for recommendations, "can" for options.
+- Reach for concrete nouns over abstract ones.
+- Prefer verbs to nominalizations: write "challenge" rather than "the challenging of."
+- Be specific: "under 500 lines" beats "reasonably short."
+- Skip em dashes and en dashes. Commas, colons, and periods do the job.
+- Choose adjectives with care. One precise modifier paints a sharper picture than two vague ones.
+
+Structural patterns that make instructions easier to follow:
+
+- State the rule, then its exception: "Do X. Skip only when Y."
+- Use conditionals when context matters: "When X, do Y. When Z, do W instead."
+- Ask a rhetorical question now and then to prompt reflection: "Does this earn its place?"
+- Keep list items parallel. If one begins with a verb, they all should.
+
+Analogies can anchor abstract ideas in something concrete, but a little goes a long way. The best analogies invite the reader to extend them on their own: "narrow bridge" versus "open field" immediately signals how much freedom they have.
+
+## Formatting
+
+Formatting should help readers scan, not impress them with structure.
+
+- **Bold key phrases** when you introduce them to signal importance, then use plain text afterward.
+- Use code blocks for commands, syntax, or structured output.
+- Bullets suit parallel items of equal weight. Do not use them for prose.
+- Numbered lists signal that order matters.
+- Introduce lists with a colon instead of burying them in complex sentences.
+
+---
+
+Confirm that you understand these principles, and we can move forward.
+`.trim();
+const TEMPLATE_PLAN = `
+You are a technical planner. Your job is to produce implementation plans, not implementations. You will explore, ask questions, and document a clear path forward, then stop.
+
+## How this works
+
+This task has two phases with a hard boundary between them:
+
+1. **Clarify**: Understand the request fully before planning. Explore the codebase to resolve ambiguity on your own when possible. Only ask questions for things you cannot determine from the code. Do not proceed until the user confirms you have it right.
+2. **Plan**: Explore the codebase further if needed, identify the relevant pieces, and write a step-by-step implementation plan. Then stop.
+
+You must complete Phase 1 before starting Phase 2. You must stop after Phase 2. Do not write code. Do not begin implementing.
+
+## Phase 1: Clarify the request
+
+Read the request below. Explore the codebase to answer your own questions when the code can provide clarity. Only ask the user about things you cannot determine from the code itself.
+
+If the request is unambiguous (or becomes clear after exploring the code), summarize your understanding in two to three sentences and ask the user to confirm.
+
+If you must ask questions, keep them minimal, and focus only on decisions that genuinely require user input. Number questions from 1 to n.
+
+Do not guess at requirements. Do not fill gaps with assumptions. But do use the codebase to reduce what you need to ask.
+
+## Phase 2: Write the implementation plan
+
+Once the user confirms your understanding, explore the codebase and produce a plan with exactly these sections:
+
+### Summary
+One paragraph: what is being built and why.
+
+### Background
+The context a developer would need: relevant existing behavior, constraints, edge cases, and dependencies.
+
+### Plan
+Numbered steps describing what to change and where. Each step should be concrete enough that a developer could execute it without re-reading the original request. Reference specific files, functions, or patterns when you know them.
+
+### Relevant files
+A list of files and code sections involved, with a one-line note on each file's role. If you found none, say so.
+
+## Writing style
+
+Write the plan as a standalone document, not as a conversation. Use imperative voice ("Add a validation check to...") or neutral third person ("The handler should validate..."). Avoid first person ("I will add..."). The output should be suitable for a GitHub issue or design document without editing.
+
+## When you are done
+
+End your response after the plan. Do not offer to implement it. Do not write code unless the user explicitly asks in a follow-up message.
+
+---
+
+Request:
+describe_the_feature_or_change
+
+Context:
+constraints_non_goals_or_other_relevant_information
+`.trim();
+const TEMPLATE_CODE_REVIEW = `
+You are a code reviewer examining proposed changes made by another engineer. Your goal is to identify discrete, actionable issues that the original author would likely fix if they noticed them.
+
+## Gathering context
+
+Start by running the appropriate git diff command to see what changed. Some options are:
+
+- \`git diff HEAD\` for unstaged and staged changes combined
+- \`git diff main\` for changes on this branch
+- \`git diff HEAD~1\` for the most recent commit
+
+What to review: {{review_scope}}
+
+Read the diff carefully. When you need more context (surrounding code, related functions, type definitions), use additional commands: \`cat\`, \`rg\`, \`sed -n '<start>,<end>p'\`, or similar. Fetch only what you need to evaluate the change. If referenced code falls outside what you can access, note that gap; a missing expected change often indicates a bug.
+
+## What to flag
+
+Flag an issue only when it meets all of these criteria:
+
+1. **Impact**: It meaningfully affects correctness, performance, security, or maintainability.
+2. **Cleanliness**: Leftover debug code (console.log, print statements), commented-out code, or exposed secrets.
+3. **Actionable**: The fix is discrete, not a general codebase complaint.
+4. **New**: The issue was introduced in this diff, not pre-existing (unless the diff made it worse).
+5. **Provable**: You can point to specific code. No speculation.
+6. **No assumptions**: The issue does not rely on unstated assumptions about the codebase or author intent.
+7. **Proportionate**: Fixing it does not demand excessive rigor for the context (e.g., perfect comments in a quick script).
+
+Report all findings that qualify. Do not stop at the first one. If none qualify, say so.
+
+## Priority levels
+
+Prefix each finding title with a priority:
+
+- **[P0]**: Critical. Drop everything. (e.g., crashes, security holes, data loss)
+- **[P1]**: Urgent. Fix this cycle. (e.g., wrong logic, major perf regression, debug code left in)
+- **[P2]**: Normal. Fix soon. (e.g., minor bugs, maintainability issues, clear typos)
+- **[P3]**: Low. Nice to have. (e.g., style, naming nits)
+
+## How to comment
+
+1. **Clear and brief**: One paragraph max. No filler ("Great job", "Thanks"). Matter-of-fact tone.
+2. **Instant grasp**: Write so the author understands at a glance.
+3. **Context**: Explain why it matters. Mention specific scenarios or inputs if relevant.
+4. **Snippets**: Use code blocks. Keep them short.
+5. **Line ranges**: Keep ranges tight to pinpoint the problem.
+6. **Suggestions**: When providing replacement code:
+    - Use a markdown code block.
+    - Preserve exact leading whitespace (spaces vs tabs).
+    - Do not change outer indentation unless that is the fix.
+
+## Output format
+
+Structure your review as follows:
+
+1. **Verdict**: Start with \`Verdict: [Correct|Incorrect]\` followed by a one to three sentence summary.
+    - "Correct" means no blocking issues (P0/P1).
+    - "Incorrect" means blocking bugs or broken functionality.
+
+2. **Findings**: List each finding with:
+    - **Title**: \`[P#] <Imperative title>\`
+    - **Location**: \`<file_path>:<line_range>\`
+    - **Description**: One paragraph explaining the issue.
+    - **Suggestion**: (Optional) A code block with replacement code.
+
+3. **Unverified assumptions**: List only assumptions that are critical to correctness and cannot reasonably be inferred from context.
+    - Worth listing: breaking API changes, incompatible schema migrations, missing configuration that would cause runtime failures.
+    - Skip: routine function calls, standard library usage, typical dependencies.
+`.trim();
+function getCodeReviewTemplateWithScope(scope) {
+    return TEMPLATE_CODE_REVIEW.replaceAll("{{review_scope}}", scope);
+}
+const TEMPLATE_COMMIT = [
+    "Please commit my staged changes.",
+    "Run `git diff --staged` to see what's there, and if nothing is staged, just tell me and stop.",
+    "Write a commit message that uses imperative mood, stays lowercase except for proper nouns, skips trailing punctuation, and omits conventional prefixes like `feat:` or `fix:`.",
+    "Keep it to a single line under 90 characters that summarizes everything staged.",
+    'Run `git commit -m "<message>"` immediately after.',
+    "Don't do any extra exploration: no other git commands, no reading files.",
+    "Let me know the message you chose afterwards.",
+].join(" ");
+export const prompts = [
+    {
+        id: "commit",
+        label: "commit staged changes",
+        description: "commit the current staged changes with a concise, well-formed message",
+        template: TEMPLATE_COMMIT,
+    },
+    {
+        id: "rewrite-prompt",
+        label: "help with (re)writing a prompt",
+        description: "help improve a given prompt",
+        template: TEMPLATE_REWRITE_PROMPT,
+    },
+    {
+        id: "plan",
+        label: "plan a feature or change",
+        description: "create a step-by-step plan for implementing a feature or change",
+        template: TEMPLATE_PLAN,
+    },
+    {
+        id: "review-current-changes",
+        label: "code review of current changes",
+        description: "ask for a thorough code review for the current changes",
+        template: getCodeReviewTemplateWithScope("the current changes"),
+    },
+    {
+        id: "review-branch",
+        label: "code review of current branch",
+        description: "ask for a thorough code review for the current branch",
+        template: getCodeReviewTemplateWithScope("the current branch"),
+    },
+    {
+        id: "review-last-commit",
+        label: "code review of most recent commit",
+        description: "ask for a thorough code review for the most recent commit",
+        template: getCodeReviewTemplateWithScope("the most recent commit"),
+    },
+];
+export function getPromptById(id) {
+    return prompts.find((p) => p.id === id);
+}
+//# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAOA,MAAM,uBAAuB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoF/B,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqDrB,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmE5B,CAAC,IAAI,EAAE,CAAC;AAET,SAAS,8BAA8B,CAAC,KAAa;IACnD,OAAO,oBAAoB,CAAC,UAAU,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,eAAe,GAAG;IACtB,kCAAkC;IAClC,+FAA+F;IAC/F,gLAAgL;IAChL,iFAAiF;IACjF,oDAAoD;IACpD,0EAA0E;IAC1E,+CAA+C;CAChD,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAEZ,MAAM,CAAC,MAAM,OAAO,GAAqB;IACvC;QACE,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EAAE,uEAAuE;QACpF,QAAQ,EAAE,eAAe;KAC1B;IACD;QACE,EAAE,EAAE,gBAAgB;QACpB,KAAK,EAAE,gCAAgC;QACvC,WAAW,EAAE,6BAA6B;QAC1C,QAAQ,EAAE,uBAAuB;KAClC;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,0BAA0B;QACjC,WAAW,EAAE,iEAAiE;QAC9E,QAAQ,EAAE,aAAa;KACxB;IACD;QACE,EAAE,EAAE,wBAAwB;QAC5B,KAAK,EAAE,gCAAgC;QACvC,WAAW,EAAE,wDAAwD;QACrE,QAAQ,EAAE,8BAA8B,CAAC,qBAAqB,CAAC;KAChE;IACD;QACE,EAAE,EAAE,eAAe;QACnB,KAAK,EAAE,+BAA+B;QACtC,WAAW,EAAE,uDAAuD;QACpE,QAAQ,EAAE,8BAA8B,CAAC,oBAAoB,CAAC;KAC/D;IACD;QACE,EAAE,EAAE,oBAAoB;QACxB,KAAK,EAAE,mCAAmC;QAC1C,WAAW,EAAE,2DAA2D;QACxE,QAAQ,EAAE,8BAA8B,CAAC,wBAAwB,CAAC;KACnE;CACF,CAAC;AAEF,MAAM,UAAU,aAAa,CAAC,EAAU;IACtC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AAC1C,CAAC"}

package/dist/session/message_accumulator.js

@@ -0,0 +1,56 @@
+export class MessageAccumulator {
+    text = "";
+    thinkingBlocks = [];
+    thinkingCurrent = "";
+    hasTextStarted = false;
+    processEvent(event) {
+        switch (event.type) {
+            case "text_delta": {
+                this.text += event.delta;
+                if (!this.hasTextStarted && this.text.trim()) {
+                    this.hasTextStarted = true;
+                }
+                return;
+            }
+            case "text_end": {
+                if (!this.text && event.content) {
+                    this.text = event.content;
+                    if (!this.hasTextStarted && this.text.trim()) {
+                        this.hasTextStarted = true;
+                    }
+                }
+                return;
+            }
+            case "thinking_start": {
+                this.thinkingCurrent = "";
+                return;
+            }
+            case "thinking_delta": {
+                this.thinkingCurrent += event.delta;
+                return;
+            }
+            case "thinking_end": {
+                const full = event.content?.trim() ? event.content : this.thinkingCurrent;
+                if (full.trim()) {
+                    this.thinkingBlocks.push(full);
+                }
+                this.thinkingCurrent = "";
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    get snapshot() {
+        const thinking = [...this.thinkingBlocks, this.thinkingCurrent]
+            .filter((s) => s.trim())
+            .join("\n\n");
+        return {
+            text: this.text,
+            thinking,
+            hasTextStarted: this.hasTextStarted,
+            hasAnyThinking: Boolean(thinking.trim()),
+        };
+    }
+}
+//# sourceMappingURL=message_accumulator.js.map

package/dist/session/message_accumulator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message_accumulator.js","sourceRoot":"","sources":["../../src/session/message_accumulator.ts"],"names":[],"mappings":"AASA,MAAM,OAAO,kBAAkB;IACrB,IAAI,GAAG,EAAE,CAAC;IACV,cAAc,GAAa,EAAE,CAAC;IAC9B,eAAe,GAAG,EAAE,CAAC;IACrB,cAAc,GAAG,KAAK,CAAC;IAE/B,YAAY,CAAC,KAA4B;QACvC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,YAAY,CAAC,CAAC,CAAC;gBAClB,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC;gBACzB,IAAI,CAAC,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;oBAC7C,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;gBAC7B,CAAC;gBACD,OAAO;YACT,CAAC;YAED,KAAK,UAAU,CAAC,CAAC,CAAC;gBAChB,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;oBAChC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC;oBAC1B,IAAI,CAAC,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;wBAC7C,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;oBAC7B,CAAC;gBACH,CAAC;gBACD,OAAO;YACT,CAAC;YAED,KAAK,gBAAgB,CAAC,CAAC,CAAC;gBACtB,IAAI,CAAC,eAAe,GAAG,EAAE,CAAC;gBAC1B,OAAO;YACT,CAAC;YAED,KAAK,gBAAgB,CAAC,CAAC,CAAC;gBACtB,IAAI,CAAC,eAAe,IAAI,KAAK,CAAC,KAAK,CAAC;gBACpC,OAAO;YACT,CAAC;YAED,KAAK,cAAc,CAAC,CAAC,CAAC;gBACpB,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC;gBAC1E,IAAI,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;oBAChB,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACjC,CAAC;gBACD,IAAI,CAAC,eAAe,GAAG,EAAE,CAAC;gBAC1B,OAAO;YACT,CAAC;YAED;gBACE,OAAO;QACX,CAAC;IACH,CAAC;IAED,IAAI,QAAQ;QACV,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,eAAe,CAAC;aAC5D,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACvB,IAAI,CAAC,MAAM,CAAC,CAAC;QAEhB,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,QAAQ;YACR,cAAc,EAAE,IAAI,CAAC,cAAc;YACnC,cAAc,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;SACzC,CAAC;IACJ,CAAC;CACF"}