@@ -345,7 +346,7 @@ function GitHubConnectStep({
className="gap-2 border-zinc-700 bg-transparent text-zinc-300 hover:bg-white/5 hover:text-white"
>
+
Terms of Service
+
+ By using bl1nk-note, you agree to these Terms of Service. This is a
+ placeholder page. Please update with your actual Terms of Service.
+
+
+ );
+}
diff --git a/apps/web/components/ai-elements/code-block.tsx b/apps/web/components/ai-elements/code-block.tsx
new file mode 100644
index 00000000..ccef52c3
--- /dev/null
+++ b/apps/web/components/ai-elements/code-block.tsx
@@ -0,0 +1,563 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import {
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+} from "@/components/ui/select";
+import { cn } from "@/lib/utils";
+import { CheckIcon, CopyIcon } from "lucide-react";
+import type { ComponentProps, CSSProperties, HTMLAttributes } from "react";
+import {
+ createContext,
+ memo,
+ useCallback,
+ useContext,
+ useEffect,
+ useMemo,
+ useRef,
+ useState,
+} from "react";
+import type {
+ BundledLanguage,
+ BundledTheme,
+ HighlighterGeneric,
+ ThemedToken,
+} from "shiki";
+import { createHighlighter } from "shiki";
+
+// Shiki uses bitflags for font styles: 1=italic, 2=bold, 4=underline
+// oxlint-disable-next-line eslint(no-bitwise)
+const isItalic = (fontStyle: number | undefined) => fontStyle && fontStyle & 1;
+// oxlint-disable-next-line eslint(no-bitwise)
+const isBold = (fontStyle: number | undefined) => fontStyle && fontStyle & 2;
+const isUnderline = (fontStyle: number | undefined) =>
+ // oxlint-disable-next-line eslint(no-bitwise)
+ fontStyle && fontStyle & 4;
+
+// Transform tokens to include pre-computed keys to avoid noArrayIndexKey lint
+interface KeyedToken {
+ token: ThemedToken;
+ key: string;
+}
+interface KeyedLine {
+ tokens: KeyedToken[];
+ key: string;
+}
+
+const addKeysToTokens = (lines: ThemedToken[][]): KeyedLine[] =>
+ lines.map((line, lineIdx) => ({
+ key: `line-${lineIdx}`,
+ tokens: line.map((token, tokenIdx) => ({
+ key: `line-${lineIdx}-${tokenIdx}`,
+ token,
+ })),
+ }));
+
+// Token rendering component
+const TokenSpan = ({ token }: { token: ThemedToken }) => (
+
+ {token.content}
+
+);
+
+// Line number styles using CSS counters
+const lineNumberClasses = cn(
+ "block",
+ "before:content-[counter(line)]",
+ "before:inline-block",
+ "before:[counter-increment:line]",
+ "before:w-8",
+ "before:mr-4",
+ "before:text-right",
+ "before:text-muted-foreground/50",
+ "before:font-mono",
+ "before:select-none",
+);
+
+// Line rendering component
+const LineSpan = ({
+ keyedLine,
+ showLineNumbers,
+}: {
+ keyedLine: KeyedLine;
+ showLineNumbers: boolean;
+}) => (
+
+ {keyedLine.tokens.length === 0
+ ? "\n"
+ : keyedLine.tokens.map(({ token, key }) => (
+
+);
+
+// Types
+type CodeBlockProps = HTMLAttributes
& {
+ code: string;
+ language: BundledLanguage;
+ showLineNumbers?: boolean;
+};
+
+interface TokenizedCode {
+ tokens: ThemedToken[][];
+ fg: string;
+ bg: string;
+}
+
+interface CodeBlockContextType {
+ code: string;
+}
+
+// Context
+const CodeBlockContext = createContext({
+ code: "",
+});
+
+// Highlighter cache (singleton per language)
+const highlighterCache = new Map<
+ string,
+ Promise>
+>();
+
+// Token cache
+const tokensCache = new Map();
+
+// Subscribers for async token updates
+const subscribers = new Map void>>();
+
+const getTokensCacheKey = (code: string, language: BundledLanguage) => {
+ const start = code.slice(0, 100);
+ const end = code.length > 100 ? code.slice(-100) : "";
+ return `${language}:${code.length}:${start}:${end}`;
+};
+
+const getHighlighter = (
+ language: BundledLanguage,
+): Promise> => {
+ const cached = highlighterCache.get(language);
+ if (cached) {
+ return cached;
+ }
+
+ const highlighterPromise = createHighlighter({
+ langs: [language],
+ themes: ["github-light", "github-dark"],
+ });
+
+ highlighterCache.set(language, highlighterPromise);
+ return highlighterPromise;
+};
+
+// Create raw tokens for immediate display while highlighting loads
+const createRawTokens = (code: string): TokenizedCode => ({
+ bg: "transparent",
+ fg: "inherit",
+ tokens: code.split("\n").map((line) =>
+ line === ""
+ ? []
+ : [
+ {
+ color: "inherit",
+ content: line,
+ } as ThemedToken,
+ ],
+ ),
+});
+
+// Synchronous highlight with callback for async results
+export const highlightCode = (
+ code: string,
+ language: BundledLanguage,
+ // oxlint-disable-next-line eslint-plugin-promise(prefer-await-to-callbacks)
+ callback?: (result: TokenizedCode) => void,
+): TokenizedCode | null => {
+ const tokensCacheKey = getTokensCacheKey(code, language);
+
+ // Return cached result if available
+ const cached = tokensCache.get(tokensCacheKey);
+ if (cached) {
+ return cached;
+ }
+
+ // Subscribe callback if provided
+ if (callback) {
+ if (!subscribers.has(tokensCacheKey)) {
+ subscribers.set(tokensCacheKey, new Set());
+ }
+ subscribers.get(tokensCacheKey)?.add(callback);
+ }
+
+ // Start highlighting in background - fire-and-forget async pattern
+ getHighlighter(language)
+ // oxlint-disable-next-line eslint-plugin-promise(prefer-await-to-then)
+ .then((highlighter) => {
+ const availableLangs = highlighter.getLoadedLanguages();
+ const langToUse = availableLangs.includes(language) ? language : "text";
+
+ const result = highlighter.codeToTokens(code, {
+ lang: langToUse,
+ themes: {
+ dark: "github-dark",
+ light: "github-light",
+ },
+ });
+
+ const tokenized: TokenizedCode = {
+ bg: result.bg ?? "transparent",
+ fg: result.fg ?? "inherit",
+ tokens: result.tokens,
+ };
+
+ // Cache the result
+ tokensCache.set(tokensCacheKey, tokenized);
+
+ // Notify all subscribers
+ const subs = subscribers.get(tokensCacheKey);
+ if (subs) {
+ for (const sub of subs) {
+ sub(tokenized);
+ }
+ subscribers.delete(tokensCacheKey);
+ }
+ })
+ // oxlint-disable-next-line eslint-plugin-promise(prefer-await-to-then), eslint-plugin-promise(prefer-await-to-callbacks)
+ .catch((error) => {
+ console.error("Failed to highlight code:", error);
+ subscribers.delete(tokensCacheKey);
+ });
+
+ return null;
+};
+
+const CodeBlockBody = memo(
+ ({
+ tokenized,
+ showLineNumbers,
+ className,
+ }: {
+ tokenized: TokenizedCode;
+ showLineNumbers: boolean;
+ className?: string;
+ }) => {
+ const preStyle = useMemo(
+ () => ({
+ backgroundColor: tokenized.bg,
+ color: tokenized.fg,
+ }),
+ [tokenized.bg, tokenized.fg],
+ );
+
+ const keyedLines = useMemo(
+ () => addKeysToTokens(tokenized.tokens),
+ [tokenized.tokens],
+ );
+
+ return (
+
+
+ {keyedLines.map((keyedLine) => (
+
+
+ );
+ },
+ (prevProps, nextProps) =>
+ prevProps.tokenized === nextProps.tokenized &&
+ prevProps.showLineNumbers === nextProps.showLineNumbers &&
+ prevProps.className === nextProps.className,
+);
+
+CodeBlockBody.displayName = "CodeBlockBody";
+
+export const CodeBlockContainer = ({
+ className,
+ language,
+ style,
+ ...props
+}: HTMLAttributes & { language: string }) => (
+
+);
+
+export const CodeBlockHeader = ({
+ children,
+ className,
+ ...props
+}: HTMLAttributes) => (
+
+ {children}
+
+);
+
+export const CodeBlockTitle = ({
+ children,
+ className,
+ ...props
+}: HTMLAttributes) => (
+
+ {children}
+
+);
+
+export const CodeBlockFilename = ({
+ children,
+ className,
+ ...props
+}: HTMLAttributes) => (
+
+ {children}
+
+);
+
+export const CodeBlockActions = ({
+ children,
+ className,
+ ...props
+}: HTMLAttributes) => (
+
+ {children}
+
+);
+
+export const CodeBlockContent = ({
+ code,
+ language,
+ showLineNumbers = false,
+}: {
+ code: string;
+ language: BundledLanguage;
+ showLineNumbers?: boolean;
+}) => {
+ // Memoized raw tokens for immediate display
+ const rawTokens = useMemo(() => createRawTokens(code), [code]);
+
+ // Synchronous cache lookup — avoids setState in effect for cached results
+ const syncTokens = useMemo(
+ () => highlightCode(code, language) ?? rawTokens,
+ [code, language, rawTokens],
+ );
+
+ // Async highlighting result (populated after shiki loads)
+ const [asyncTokens, setAsyncTokens] = useState(null);
+ const asyncKeyRef = useRef({ code, language });
+
+ // Invalidate stale async tokens synchronously during render
+ if (
+ asyncKeyRef.current.code !== code ||
+ asyncKeyRef.current.language !== language
+ ) {
+ asyncKeyRef.current = { code, language };
+ setAsyncTokens(null);
+ }
+
+ useEffect(() => {
+ let cancelled = false;
+
+ highlightCode(code, language, (result) => {
+ if (!cancelled) {
+ setAsyncTokens(result);
+ }
+ });
+
+ return () => {
+ cancelled = true;
+ };
+ }, [code, language]);
+
+ const tokenized = asyncTokens ?? syncTokens;
+
+ return (
+
+
+ );
+};
+
+export const CodeBlock = ({
+ code,
+ language,
+ showLineNumbers = false,
+ className,
+ children,
+ ...props
+}: CodeBlockProps) => {
+ const contextValue = useMemo(() => ({ code }), [code]);
+
+ return (
+
+
+ {children}
+
+
+ );
+};
+
+export type CodeBlockCopyButtonProps = ComponentProps & {
+ onCopy?: () => void;
+ onError?: (error: Error) => void;
+ timeout?: number;
+};
+
+export const CodeBlockCopyButton = ({
+ onCopy,
+ onError,
+ timeout = 2000,
+ children,
+ className,
+ ...props
+}: CodeBlockCopyButtonProps) => {
+ const [isCopied, setIsCopied] = useState(false);
+ const timeoutRef = useRef(0);
+ const { code } = useContext(CodeBlockContext);
+
+ const copyToClipboard = useCallback(async () => {
+ if (typeof window === "undefined" || !navigator?.clipboard?.writeText) {
+ onError?.(new Error("Clipboard API not available"));
+ return;
+ }
+
+ try {
+ if (!isCopied) {
+ await navigator.clipboard.writeText(code);
+ setIsCopied(true);
+ onCopy?.();
+ timeoutRef.current = window.setTimeout(
+ () => setIsCopied(false),
+ timeout,
+ );
+ }
+ } catch (error) {
+ onError?.(error as Error);
+ }
+ }, [code, onCopy, onError, timeout, isCopied]);
+
+ useEffect(
+ () => () => {
+ window.clearTimeout(timeoutRef.current);
+ },
+ [],
+ );
+
+ const Icon = isCopied ? CheckIcon : CopyIcon;
+
+ return (
+
+ {children ??
+ );
+};
+
+export type CodeBlockLanguageSelectorProps = ComponentProps;
+
+export const CodeBlockLanguageSelector = (
+ props: CodeBlockLanguageSelectorProps,
+) => & {
- asChild?: boolean;
+ asChild?: boolean
}) {
- const Comp = asChild ? Slot : "button";
+ const Comp = asChild ? Slot.Root : "button"
return (
) {
- return ) {
- return ) {
- return & {
- size?: "sm" | "default";
+ size?: "sm" | "default"
}) {
return (
@@ -47,7 +47,7 @@ function SelectTrigger({
- );
+ )
}
function SelectContent({
@@ -62,10 +62,10 @@ function SelectContent({
{children}
@@ -84,7 +84,7 @@ function SelectContent({
- );
+ )
}
function SelectLabel({
@@ -94,10 +94,10 @@ function SelectLabel({
return (
@@ -124,7 +124,7 @@ function SelectItem({
{children}
- );
+ )
}
function SelectSeparator({
@@ -134,10 +134,10 @@ function SelectSeparator({
return (
(path: string, options?: RequestInit): Promise {
+ const response = await fetch(`${this.baseUrl}${path}`, {
+ ...options,
+ headers: {
+ Authorization: `Bearer ${this.apiKey}`,
+ "Content-Type": "application/json",
+ ...options?.headers,
+ },
+ });
+
+ if (!response.ok) {
+ let errorData: unknown;
+ try {
+ errorData = await response.json();
+ } catch {
+ throw new Error(
+ `Kilo API Error ${response.status}: ${response.statusText}`,
+ { cause: e },
+ );
+ }
+ throw new Error(
+ `Kilo API Error ${response.status}: ${
+ errorData?.error?.message || response.statusText
+ }`,
+ );
+ }
+
+ return response.json() as Promise;
+ }
+
+ async chatCompletions(
+ body: ChatCompletionRequest,
+ ): Promise {
+ return this.request(
+ "/api/gateway/chat/completions",
+ {
+ method: "POST",
+ body: JSON.stringify(body),
+ },
+ );
+ }
+
+ async fimCompletions(body: FIMRequest): Promise {
+ return this.request("/api/fim/completions", {
+ method: "POST",
+ body: JSON.stringify(body),
+ });
+ }
+
+ async listModels(): Promise<{ data: Model[] }> {
+ return this.request<{ data: Model[] }>("/api/gateway/models");
+ }
+
+ async listProviders(): Promise {
+ return this.request("/api/gateway/providers");
+ }
+}
diff --git a/packages/agent/open-agent.ts b/packages/agent/open-agent.ts
index ceb7d151..ef4aa2b0 100644
--- a/packages/agent/open-agent.ts
+++ b/packages/agent/open-agent.ts
@@ -19,6 +19,7 @@ import {
readFileTool,
skillTool,
taskTool,
+ delegateTaskTool,
todoWriteTool,
webFetchTool,
writeFileTool,
@@ -71,6 +72,7 @@ const tools = {
glob: globTool(),
bash: bashTool(),
task: taskTool,
+ delegate_task: delegateTaskTool,
ask_user_question: askUserQuestionTool,
skill: skillTool,
web_fetch: webFetchTool,
diff --git a/packages/agent/tools/delegate.ts b/packages/agent/tools/delegate.ts
new file mode 100644
index 00000000..af81f402
--- /dev/null
+++ b/packages/agent/tools/delegate.ts
@@ -0,0 +1,186 @@
+import {
+ type LanguageModelUsage,
+ type ModelMessage,
+ tool,
+ type UIToolInvocation,
+} from "ai";
+import { z } from "zod";
+import {
+ buildSubagentSummaryLines,
+ SUBAGENT_REGISTRY,
+ SUBAGENT_TYPES,
+} from "../subagents/registry";
+import { sumLanguageModelUsage } from "../usage";
+import { getSandboxContext, getSubagentModel } from "./utils";
+
+const subagentTypeSchema = z.enum(SUBAGENT_TYPES);
+const subagentSummaryLines = buildSubagentSummaryLines();
+
+const delegateTaskSchema = z.object({
+ subagentType: subagentTypeSchema.describe(
+ `Subagent to launch. Available options:\n${subagentSummaryLines}`,
+ ),
+ task: z
+ .string()
+ .describe("Short description of the task (displayed to user)"),
+ instructions: z.string().describe(
+ `Detailed instructions for the subagent. Include:
+- Goal and deliverables
+- Step-by-step procedure
+- Constraints and patterns to follow
+- How to verify the work`,
+ ),
+});
+
+export const delegateTaskOutputSchema = z.object({
+ results: z.array(
+ z.object({
+ task: z.string(),
+ modelId: z.string().optional(),
+ toolCallCount: z.number(),
+ final: z.custom().optional(),
+ usage: z.custom().optional(),
+ }),
+ ),
+ totalToolCallCount: z.number().int().nonnegative().optional(),
+ startedAt: z.number().int().nonnegative().optional(),
+});
+
+export type DelegateTaskToolOutput = z.infer;
+
+export const delegateTaskTool = tool({
+ needsApproval: false,
+ description: `Spawn multiple subagents to work on tasks in isolated contexts simultaneously.
+Each subagent gets its own workspace context. Only the final summary is returned.
+
+AVAILABLE SUBAGENTS:
+${subagentSummaryLines}
+
+WHEN TO USE delegate_task:
+- Parallel independent workstreams (e.g. researching different topics simultaneously)
+- Reasoning-heavy subtasks that can be separated and executed concurrently
+
+WHEN NOT TO USE (use existing tools instead):
+- Single sequential task -> just use the 'task' tool directly
+- Tasks needing your direct interaction or memory -> do it yourself
+- Simple, single-file or single-change edits -> do it yourself
+
+HOW TO USE:
+- Provide an array of 'tasks'. All run concurrently and results are returned together.
+- Choose the appropriate subagentType for each task.
+- Be explicit and concrete - subagents cannot ask clarifying questions.`,
+ inputSchema: z.object({
+ tasks: z
+ .array(delegateTaskSchema)
+ .min(1)
+ .max(5)
+ .describe("Tasks to run in parallel. Each gets its own subagent."),
+ }),
+ outputSchema: delegateTaskOutputSchema,
+ execute: async function* ({ tasks }, { experimental_context, abortSignal }) {
+ const sandboxContext = getSandboxContext(
+ experimental_context,
+ "delegateTask",
+ );
+ const model = getSubagentModel(experimental_context, "delegateTask");
+ const subagentModelId = typeof model === "string" ? model : model.modelId;
+ const startedAt = Date.now();
+
+ // Initialize state
+ const taskStates = tasks.map((t) => ({
+ task: t.task,
+ modelId: subagentModelId,
+ toolCallCount: 0,
+ usage: undefined as LanguageModelUsage | undefined,
+ final: undefined as ModelMessage[] | undefined,
+ }));
+
+ yield {
+ results: taskStates,
+ totalToolCallCount: 0,
+ startedAt,
+ };
+
+ const runTask = async (taskInput: (typeof tasks)[0], index: number) => {
+ const state = taskStates[index];
+ if (!state) return;
+ const subagent = SUBAGENT_REGISTRY[taskInput.subagentType].agent;
+ const result = await subagent.stream({
+ prompt:
+ "Complete this task and provide a summary of what you accomplished.",
+ options: {
+ task: taskInput.task,
+ instructions: taskInput.instructions,
+ sandbox: sandboxContext.sandbox,
+ model,
+ },
+ abortSignal,
+ });
+
+ for await (const part of result.fullStream) {
+ if (part.type === "tool-call") {
+ state.toolCallCount += 1;
+ } else if (part.type === "finish-step") {
+ state.usage = sumLanguageModelUsage(state.usage, part.usage);
+ }
+ }
+
+ const response = await result.response;
+ const finalUsage = state.usage ?? (await result.usage);
+
+ state.final = response.messages;
+ state.usage = finalUsage;
+
+ return state;
+ };
+
+ // Run all tasks in parallel
+ const promises = tasks.map((t, i) => runTask(t, i));
+ await Promise.all(promises);
+
+ const totalToolCallCount = taskStates.reduce(
+ (acc, t) => acc + t.toolCallCount,
+ 0,
+ );
+
+ yield {
+ results: taskStates,
+ totalToolCallCount,
+ startedAt,
+ };
+ },
+ toModelOutput: ({ output: { results } }) => {
+ if (!results || results.length === 0) {
+ return { type: "text", value: "All tasks completed." };
+ }
+
+ const summaries = results.map((result, i) => {
+ const messages = result.final;
+ let contentValue = "Task completed without detailed summary.";
+
+ if (messages) {
+ const lastAssistantMessage = messages.findLast(
+ (p) => p.role === "assistant",
+ );
+ const content = lastAssistantMessage?.content;
+
+ if (content) {
+ if (typeof content === "string") {
+ contentValue = content;
+ } else {
+ const lastTextPart = content.findLast((p) => p.type === "text");
+ if (lastTextPart) {
+ contentValue = lastTextPart.text;
+ }
+ }
+ }
+ }
+
+ return `=== Result for Task ${i + 1}: ${result.task} ===\n${contentValue}`;
+ });
+
+ return { type: "text", value: summaries.join("\n\n") };
+ },
+});
+
+export type DelegateTaskToolUIPart = UIToolInvocation;
diff --git a/packages/agent/tools/github.ts b/packages/agent/tools/github.ts
new file mode 100644
index 00000000..e0ceb7eb
--- /dev/null
+++ b/packages/agent/tools/github.ts
@@ -0,0 +1,129 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { getSandbox, shellEscape } from "./utils";
+
+// หมดเวลาในการดำเนินการคำสั่ง git และ gh
+export const TIMEOUT_MS = 60_000;
+
+export const commitAndPrTool = tool({
+ description: `Commit all current changes, push to a new branch, and create a Pull Request using the GitHub CLI.
+
+WHEN TO USE:
+- When you have completed a task and want to submit your code for review.
+- When the user explicitly asks you to commit and create a PR.
+
+USAGE:
+- Automatically stages all changes (git add -A)
+- Creates a new branch
+- Commits the changes
+- Pushes the branch to origin
+- Uses the 'gh' CLI to create the PR`,
+ inputSchema: z.object({
+ branchName: z
+ .string()
+ .describe("The name of the new branch to create and push"),
+ commitMessage: z.string().describe("The commit message"),
+ prTitle: z.string().describe("The title of the pull request"),
+ prBody: z
+ .string()
+ .optional()
+ .describe("The body/description of the pull request"),
+ }),
+ needsApproval: () => true,
+ execute: async (
+ { branchName, commitMessage, prTitle, prBody },
+ { experimental_context, abortSignal },
+ ) => {
+ const sandbox = await getSandbox(experimental_context, "commitAndPr");
+ const cwd = sandbox.workingDirectory;
+
+ try {
+ // 1. Create and checkout new branch
+ const branchRes = await sandbox.exec(
+ `git checkout -b ${shellEscape(branchName)}`,
+ cwd,
+ TIMEOUT_MS,
+ { signal: abortSignal },
+ );
+
+ if (
+ !branchRes.success &&
+ !branchRes.stderr.includes("already exists") &&
+ !branchRes.stderr.includes("already a branch")
+ ) {
+ return {
+ success: false,
+ error: `Failed to create branch: ${branchRes.stderr}`,
+ };
+ }
+
+ // 2. Stage all changes
+ await sandbox.exec("git add -A", cwd, TIMEOUT_MS, {
+ signal: abortSignal,
+ });
+
+ // 3. Commit changes
+ const commitRes = await sandbox.exec(
+ `git commit -m ${shellEscape(commitMessage)}`,
+ cwd,
+ TIMEOUT_MS,
+ { signal: abortSignal },
+ );
+
+ if (
+ !commitRes.success &&
+ !commitRes.stdout.includes("nothing to commit") &&
+ !commitRes.stderr.includes("nothing to commit")
+ ) {
+ return {
+ success: false,
+ error: `Failed to commit: ${commitRes.stdout} ${commitRes.stderr}`,
+ };
+ }
+
+ // 4. Push branch
+ const pushRes = await sandbox.exec(
+ `git push -u origin ${shellEscape(branchName)}`,
+ cwd,
+ TIMEOUT_MS,
+ { signal: abortSignal },
+ );
+
+ if (!pushRes.success) {
+ return {
+ success: false,
+ error: `Failed to push: ${pushRes.stdout} ${pushRes.stderr}`,
+ };
+ }
+
+ // 5. Create PR via gh cli
+ const bodyArg = prBody ? `--body ${shellEscape(prBody)}` : '--body ""';
+ const prRes = await sandbox.exec(
+ `gh pr create --title ${shellEscape(prTitle)} ${bodyArg}`,
+ cwd,
+ TIMEOUT_MS,
+ { signal: abortSignal },
+ );
+
+ if (prRes.success) {
+ return {
+ success: true,
+ message: "Successfully committed, pushed, and created PR.",
+ prUrl: prRes.stdout.trim(),
+ };
+ } else {
+ return {
+ success: true,
+ message: `Successfully committed and pushed to branch ${branchName}. Note: Could not create PR automatically via gh CLI. Please create it manually.`,
+ errorDetails: prRes.stderr,
+ };
+ }
+ } catch (error) {
+ const message = error instanceof Error ? error.message : String(error);
+ return {
+ success: false,
+ error: `Error during commit and PR process: ${message}`,
+ };
+ }
+ },
+});
diff --git a/packages/agent/tools/index.ts b/packages/agent/tools/index.ts
index bd81875f..c92fbc2e 100644
--- a/packages/agent/tools/index.ts
+++ b/packages/agent/tools/index.ts
@@ -10,6 +10,11 @@ export {
type TaskToolOutput,
type TaskToolUIPart,
} from "./task";
+export {
+ delegateTaskTool,
+ type DelegateTaskToolOutput,
+ type DelegateTaskToolUIPart,
+} from "./delegate";
export {
askUserQuestionTool,
type AskUserQuestionToolUIPart,
@@ -17,3 +22,4 @@ export {
} from "./ask-user-question";
export { skillTool, type SkillToolInput } from "./skill";
export { webFetchTool } from "./fetch";
+export { commitAndPrTool } from "./github";
diff --git a/packages/agent/tools/kilo.test.ts b/packages/agent/tools/kilo.test.ts
new file mode 100644
index 00000000..86d8fec1
--- /dev/null
+++ b/packages/agent/tools/kilo.test.ts
@@ -0,0 +1,214 @@
+import { describe, test, expect, mock, beforeEach, afterEach } from "bun:test";
+
+// Mock node-fetch
+const fetchMock = mock(async (unusedUrl: string, unusedOptions: RequestInit) => {
+ return new Response(
+ JSON.stringify({ jsonrpc: "2.0", result: { success: true }, id: 1 }),
+ {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ },
+ );
+});
+
+mock.module("node-fetch", () => ({
+ __esModule: true,
+ default: fetchMock,
+}));
+
+// Mock process.env
+const originalEnv = process.env;
+beforeEach(() => {
+ process.env = { ...originalEnv };
+});
+afterEach(() => {
+ process.env = originalEnv;
+});
+
+// Now import the class to be tested
+const { Context7Client } = await import("./kilo");
+
+describe("Context7Client", () => {
+ beforeEach(() => {
+ fetchMock.mockClear();
+ });
+
+ describe("constructor", () => {
+ test("should use provided API key", () => {
+ const client = new Context7Client("test-api-key");
+ expect(client).toBeDefined();
+ });
+
+ test("should use environment variable if no key provided", () => {
+ process.env.CONTEXT7_API_KEY = "env-api-key";
+ const client = new Context7Client();
+ expect(client).toBeDefined();
+ });
+
+ test("should throw error if no API key available", () => {
+ delete process.env.CONTEXT7_API_KEY;
+ expect(() => new Context7Client()).toThrow(
+ "Context7 API key is required. Provide it as parameter or set CONTEXT7_API_KEY environment variable.",
+ );
+ });
+ });
+
+ describe("call method", () => {
+ let client: Context7Client;
+
+ beforeEach(() => {
+ process.env.CONTEXT7_API_KEY = "test-api-key";
+ client = new Context7Client();
+ });
+
+ test("should make POST request with correct headers and payload", async () => {
+ await client.call("test.method", { param: "value" });
+
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ const [url, options] = fetchMock.mock.calls[0];
+
+ expect(url).toBe("https://mcp.context7.com/mcp");
+ expect(options?.method).toBe("POST");
+ expect(options?.headers).toEqual({
+ CONTEXT7_API_KEY: "test-api-key",
+ "Content-Type": "application/json",
+ });
+
+ const body = JSON.parse(options?.body as string);
+ expect(body).toEqual({
+ jsonrpc: "2.0",
+ method: "test.method",
+ id: 1,
+ params: { param: "value" },
+ });
+ });
+
+ test("should increment request ID for multiple calls", async () => {
+ await client.call("method1");
+ await client.call("method2");
+ await client.call("method3");
+
+ expect(fetchMock).toHaveBeenCalledTimes(3);
+
+ const bodies = fetchMock.mock.calls.map(([unusedUrl, options]) =>
+ JSON.parse((options as RequestInit)?.body as string),
+ );
+
+ expect(bodies[0].id).toBe(1);
+ expect(bodies[1].id).toBe(2);
+ expect(bodies[2].id).toBe(3);
+ });
+
+ test("should handle empty params", async () => {
+ await client.call("test.method");
+
+ const [unusedUrl, options] = fetchMock.mock.calls[0];
+ const body = JSON.parse((options as RequestInit)?.body as string);
+ expect(body.params).toEqual({});
+ });
+
+ test("should return parsed JSON response", async () => {
+ const mockResponse = {
+ jsonrpc: "2.0",
+ result: { tools: ["tool1", "tool2"] },
+ id: 1,
+ };
+ fetchMock.mockResolvedValueOnce(
+ new Response(JSON.stringify(mockResponse)),
+ );
+
+ const result = await client.call("tools/list");
+ expect(result).toEqual(mockResponse);
+ });
+
+ test("should handle error responses", async () => {
+ const errorResponse = {
+ jsonrpc: "2.0",
+ error: { code: -32601, message: "Method not found" },
+ id: 1,
+ };
+ fetchMock.mockResolvedValueOnce(
+ new Response(JSON.stringify(errorResponse)),
+ );
+
+ const result = await client.call("invalid.method");
+ expect(result).toEqual(errorResponse);
+ });
+
+ test("should throw on HTTP errors", async () => {
+ fetchMock.mockResolvedValueOnce(
+ new Response("Forbidden", { status: 403 }),
+ );
+
+ await expect(client.call("tools/list")).rejects.toThrow(
+ "Context7 API call failed with status 403: Forbidden",
+ );
+ });
+
+ test("should handle network errors", async () => {
+ fetchMock.mockRejectedValueOnce(new Error("Network timeout"));
+
+ await expect(client.call("tools/list")).rejects.toThrow(
+ "Network timeout",
+ );
+ });
+
+ test("should handle malformed JSON response", async () => {
+ fetchMock.mockResolvedValueOnce(
+ new Response("invalid json", {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ }),
+ );
+
+ await expect(client.call("tools/list")).rejects.toThrow();
+ });
+ });
+
+ describe("integration scenarios", () => {
+ let client: Context7Client;
+
+ beforeEach(() => {
+ process.env.CONTEXT7_API_KEY = "test-api-key";
+ client = new Context7Client();
+ });
+
+ test("should handle tools/list call", async () => {
+ const mockResponse = {
+ jsonrpc: "2.0",
+ result: {
+ tools: [
+ { name: "query-docs", description: "Query documentation" },
+ { name: "resolve-library-id", description: "Resolve library ID" },
+ ],
+ },
+ id: 1,
+ };
+ fetchMock.mockResolvedValueOnce(
+ new Response(JSON.stringify(mockResponse)),
+ );
+
+ const result = await client.call("tools/list");
+ expect(result.result.tools).toHaveLength(2);
+ expect(result.result.tools[0].name).toBe("query-docs");
+ });
+
+ test("should handle query-docs call with complex params", async () => {
+ const params = {
+ libraryId: "/reactjs/react.dev",
+ query: "how to use useState hook",
+ };
+
+ await client.call("tools/call", {
+ name: "query-docs",
+ arguments: params,
+ });
+
+ const [unusedUrl, options] = fetchMock.mock.calls[0];
+ const body = JSON.parse((options as RequestInit)?.body as string);
+
+ expect(body.params.name).toBe("query-docs");
+ expect(body.params.arguments.libraryId).toBe("/reactjs/react.dev");
+ });
+ });
+});
diff --git a/packages/agent/tools/kilo.ts b/packages/agent/tools/kilo.ts
new file mode 100644
index 00000000..36a73857
--- /dev/null
+++ b/packages/agent/tools/kilo.ts
@@ -0,0 +1,55 @@
+import fetch from "node-fetch";
+
+class Context7Client {
+ private url: string = "https://mcp.context7.com/mcp";
+ private headers: Record;
+ private id: number = 1;
+
+ constructor(apiKey?: string) {
+ const key = apiKey || process.env.CONTEXT7_API_KEY;
+ if (!key) {
+ throw new Error(
+ "Context7 API key is required. Provide it as parameter or set CONTEXT7_API_KEY environment variable.",
+ );
+ }
+ this.headers = {
+ CONTEXT7_API_KEY: key,
+ "Content-Type": "application/json",
+ };
+ }
+
+ async call(
+ method: string,
+ params: Record = {},
+ ): Promise {
+ const payload = {
+ jsonrpc: "2.0",
+ method,
+ id: this.id,
+ params,
+ };
+ this.id++;
+
+ const response = await fetch(this.url, {
+ method: "POST",
+ headers: this.headers,
+ body: JSON.stringify(payload),
+ });
+
+ if (!response.ok) {
+ const errorText = await response.text();
+ throw new Error(
+ `Context7 API call failed with status ${response.status}: ${errorText}`,
+ );
+ }
+
+ return await response.json();
+ }
+}
+
+// Usage example
+// const client = new Context7Client(); // uses env var
+// const client = new Context7Client('your_api_key_here'); // explicit key
+// client.call('tools/list').then(result => console.log(result));
+
+export { Context7Client };
diff --git a/packages/agent/tools/lsp.test.ts b/packages/agent/tools/lsp.test.ts
new file mode 100644
index 00000000..afb4c302
--- /dev/null
+++ b/packages/agent/tools/lsp.test.ts
@@ -0,0 +1,447 @@
+import { describe, test, expect, mock, beforeEach } from "bun:test";
+
+// Mock LSP dependencies
+const mockLspClientManager = {
+ runWithClientLease: mock(async (filePath: string, fn: unknown) => {
+ const mockClient = {
+ hover: mock(async () => ({
+ contents: [{ kind: "markdown", value: "Test hover content" }],
+ range: {
+ start: { line: 0, character: 0 },
+ end: { line: 0, character: 10 },
+ },
+ })),
+ definition: mock(async () => [
+ {
+ uri: "file:///test/file.ts",
+ range: {
+ start: { line: 5, character: 0 },
+ end: { line: 5, character: 15 },
+ },
+ },
+ ]),
+ references: mock(async () => [
+ {
+ uri: "file:///test/file.ts",
+ range: {
+ start: { line: 10, character: 0 },
+ end: { line: 10, character: 10 },
+ },
+ },
+ ]),
+ documentSymbols: mock(async () => [
+ {
+ name: "testFunction",
+ kind: 12, // Function
+ range: {
+ start: { line: 5, character: 0 },
+ end: { line: 5, character: 20 },
+ },
+ selectionRange: {
+ start: { line: 5, character: 9 },
+ end: { line: 5, character: 21 },
+ },
+ },
+ ]),
+ workspaceSymbols: mock(async () => [
+ {
+ name: "TestClass",
+ kind: 5, // Class
+ location: {
+ uri: "file:///test/class.ts",
+ range: {
+ start: { line: 1, character: 0 },
+ end: { line: 1, character: 10 },
+ },
+ },
+ },
+ ]),
+ openDocument: mock(async () => {}),
+ waitForDiagnostics: mock(async () => {}),
+ getDiagnostics: mock(() => [
+ {
+ range: {
+ start: { line: 1, character: 5 },
+ end: { line: 1, character: 10 },
+ },
+ severity: 1,
+ message: "Test error",
+ source: "test",
+ },
+ ]),
+ prepareRename: mock(async () => ({
+ start: { line: 1, character: 0 },
+ end: { line: 1, character: 5 },
+ })),
+ rename: mock(async () => ({
+ changes: {
+ "file:///test/file.ts": [
+ {
+ range: {
+ start: { line: 1, character: 0 },
+ end: { line: 1, character: 5 },
+ },
+ newText: "newName",
+ },
+ ],
+ },
+ })),
+ codeActions: mock(async () => [
+ {
+ title: "Extract function",
+ kind: "refactor.extract",
+ edit: {
+ changes: {
+ "file:///test/file.ts": [
+ {
+ range: {
+ start: { line: 2, character: 0 },
+ end: { line: 4, character: 0 },
+ },
+ newText: "extractedFunction() {\n // code\n}",
+ },
+ ],
+ },
+ },
+ },
+ ]),
+ supportsPullDiagnostics: false,
+ };
+ return await fn(mockClient);
+ }),
+};
+
+const mockGetAllServers = mock(() => [
+ {
+ name: "typescript",
+ command: "tsserver",
+ extensions: [".ts", ".tsx"],
+ installed: true,
+ },
+ {
+ name: "python",
+ command: "pylsp",
+ extensions: [".py"],
+ installed: false,
+ installHint: "pip install python-lsp-server",
+ },
+]);
+
+const mockGetServerForFile = mock((filePath: string) => {
+ if (filePath.endsWith(".ts")) {
+ return {
+ name: "typescript",
+ command: "tsserver",
+ extensions: [".ts", ".tsx"],
+ installed: true,
+ };
+ }
+ return null;
+});
+
+const mockFormatHover = mock(
+ (_hover: unknown) => "Formatted hover: Test hover content",
+);
+const mockFormatLocations = mock(
+ (_locations: unknown) => "Found 1 location(s)",
+);
+const mockFormatDocumentSymbols = mock(
+ (_symbols: unknown) => "1 symbol(s) found",
+);
+const mockFormatWorkspaceSymbols = mock(
+ (_symbols: unknown) => "Found 1 symbol(s)",
+);
+const mockFormatDiagnostics = mock(
+ (_diagnostics: unknown) => "Found 1 diagnostic(s)",
+);
+const mockFormatCodeActions = mock(
+ (_actions: unknown) => "Found 1 code action(s)",
+);
+const mockFormatWorkspaceEdit = mock(
+ (_edit: unknown) => "Workspace edit applied",
+);
+const mockCountEdits = mock(() => ({ files: 1, edits: 1 }));
+
+mock.module("./lsp/index.js", () => ({
+ lspClientManager: mockLspClientManager,
+ getAllServers: mockGetAllServers,
+ getServerForFile: mockGetServerForFile,
+ formatHover: mockFormatHover,
+ formatLocations: mockFormatLocations,
+ formatDocumentSymbols: mockFormatDocumentSymbols,
+ formatWorkspaceSymbols: mockFormatWorkspaceSymbols,
+ formatDiagnostics: mockFormatDiagnostics,
+ formatCodeActions: mockFormatCodeActions,
+ formatWorkspaceEdit: mockFormatWorkspaceEdit,
+ countEdits: mockCountEdits,
+}));
+
+mock.module("./diagnostics/index.js", () => ({
+ runDirectoryDiagnostics: mock(async () => ({
+ strategy: "tsc",
+ summary: "2 errors, 1 warning",
+ diagnostics: "Error: test error\nWarning: test warning",
+ })),
+}));
+
+// Import after mocking
+const { lspTools } = await import("./lsp");
+
+describe("LSP Tools", () => {
+ beforeEach(() => {
+ // Reset all mocks
+ mockLspClientManager.runWithClientLease.mockClear();
+ mockGetAllServers.mockClear();
+ mockGetServerForFile.mockClear();
+ Object.values({
+ mockFormatHover,
+ mockFormatLocations,
+ mockFormatDocumentSymbols,
+ mockFormatWorkspaceSymbols,
+ mockFormatDiagnostics,
+ mockFormatCodeActions,
+ mockFormatWorkspaceEdit,
+ mockCountEdits,
+ }).forEach((mock) => mock.mockClear());
+ });
+
+ test("should export lspTools array with expected tools", () => {
+ expect(Array.isArray(lspTools)).toBe(true);
+ expect(lspTools.length).toBe(12); // All LSP tools
+
+ const toolNames = lspTools.map((t) => t.name);
+ expect(toolNames).toEqual([
+ "lsp_hover",
+ "lsp_goto_definition",
+ "lsp_find_references",
+ "lsp_document_symbols",
+ "lsp_workspace_symbols",
+ "lsp_diagnostics",
+ "lsp_diagnostics_directory",
+ "lsp_servers",
+ "lsp_prepare_rename",
+ "lsp_rename",
+ "lsp_code_actions",
+ "lsp_code_action_resolve",
+ ]);
+ });
+
+ test("each tool should have required properties with correct types", () => {
+ for (const tool of lspTools) {
+ expect(tool).toHaveProperty("name");
+ expect(tool).toHaveProperty("description");
+ expect(tool).toHaveProperty("schema");
+ expect(tool).toHaveProperty("handler");
+
+ expect(typeof tool.name).toBe("string");
+ expect(typeof tool.description).toBe("string");
+ expect(typeof tool.handler).toBe("function");
+
+ // Schema should be an object with properties
+ expect(typeof tool.schema).toBe("object");
+ }
+ });
+
+ describe("lsp_hover tool", () => {
+ test("should call LSP hover and format result", async () => {
+ const result = await lspTools[0].handler({
+ file: "test.ts",
+ line: 1,
+ character: 5,
+ });
+
+ expect(mockLspClientManager.runWithClientLease).toHaveBeenCalledWith(
+ "test.ts",
+ expect.any(Function),
+ );
+ expect(mockFormatHover).toHaveBeenCalled();
+ expect(result.content[0].text).toBe(
+ "Formatted hover: Test hover content",
+ );
+ });
+ });
+
+ describe("lsp_goto_definition tool", () => {
+ test("should find definition locations", async () => {
+ const result = await lspTools[1].handler({
+ file: "test.ts",
+ line: 1,
+ character: 5,
+ });
+
+ expect(mockFormatLocations).toHaveBeenCalledWith([
+ {
+ uri: "file:///test/file.ts",
+ range: {
+ start: { line: 5, character: 0 },
+ end: { line: 5, character: 15 },
+ },
+ },
+ ]);
+ expect(result.content[0].text).toBe("Found 1 location(s)");
+ });
+ });
+
+ describe("lsp_find_references tool", () => {
+ test("should find references with includeDeclaration true", async () => {
+ const result = await lspTools[2].handler({
+ file: "test.ts",
+ line: 1,
+ character: 5,
+ includeDeclaration: true,
+ });
+
+ expect(result.content[0].text).toBe(
+ "Found 1 reference(s):\n\nFound 1 location(s)",
+ );
+ });
+
+ test("should handle no references found", async () => {
+ mockLspClientManager.runWithClientLease.mockImplementationOnce(
+ async (filePath, fn) => {
+ const mockClient = {
+ references: mock(async () => []),
+ };
+ return await fn(mockClient);
+ },
+ );
+
+ const result = await lspTools[2].handler({
+ file: "test.ts",
+ line: 1,
+ character: 5,
+ });
+
+ expect(result.content[0].text).toBe("No references found");
+ });
+ });
+
+ describe("lsp_document_symbols tool", () => {
+ test("should get document symbols", async () => {
+ const result = await lspTools[3].handler({
+ file: "test.ts",
+ });
+
+ expect(mockFormatDocumentSymbols).toHaveBeenCalled();
+ expect(result.content[0].text).toBe("1 symbol(s) found");
+ });
+ });
+
+ describe("lsp_workspace_symbols tool", () => {
+ test("should search workspace symbols", async () => {
+ const result = await lspTools[4].handler({
+ query: "TestClass",
+ file: "test.ts",
+ });
+
+ expect(result.content[0].text).toBe(
+ 'Found 1 symbol(s) matching "TestClass":\n\nFound 1 symbol(s)',
+ );
+ });
+
+ test("should handle no symbols found", async () => {
+ mockLspClientManager.runWithClientLease.mockImplementationOnce(
+ async (filePath, fn) => {
+ const mockClient = {
+ workspaceSymbols: mock(async () => []),
+ };
+ return await fn(mockClient);
+ },
+ );
+
+ const result = await lspTools[4].handler({
+ query: "UnknownSymbol",
+ file: "test.ts",
+ });
+
+ expect(result.content[0].text).toBe(
+ "No symbols found matching: UnknownSymbol",
+ );
+ });
+ });
+
+ describe("lsp_diagnostics tool", () => {
+ test("should get diagnostics with severity filter", async () => {
+ const result = await lspTools[5].handler({
+ file: "test.ts",
+ severity: "error",
+ });
+
+ expect(result.content[0].text).toContain("Found 1 diagnostic(s)");
+ });
+ });
+
+ describe("lsp_servers tool", () => {
+ test("should list all language servers", async () => {
+ const result = await lspTools[7].handler({});
+
+ expect(mockGetAllServers).toHaveBeenCalled();
+ expect(result.content[0].text).toContain("Language Server Status");
+ expect(result.content[0].text).toContain("typescript");
+ expect(result.content[0].text).toContain("python");
+ });
+ });
+
+ describe("lsp_rename tool", () => {
+ test("should perform rename and show edit summary", async () => {
+ const result = await lspTools[9].handler({
+ file: "test.ts",
+ line: 1,
+ character: 5,
+ newName: "newFunctionName",
+ });
+
+ expect(mockCountEdits).toHaveBeenCalled();
+ expect(result.content[0].text).toContain(
+ 'Rename to "newFunctionName" would affect 1 file(s) with 1 edit(s)',
+ );
+ });
+ });
+
+ describe("lsp_code_actions tool", () => {
+ test("should get code actions for selection", async () => {
+ const result = await lspTools[10].handler({
+ file: "test.ts",
+ startLine: 1,
+ startCharacter: 0,
+ endLine: 3,
+ endCharacter: 10,
+ });
+
+ expect(mockFormatCodeActions).toHaveBeenCalled();
+ expect(result.content[0].text).toBe("Found 1 code action(s)");
+ });
+ });
+
+ describe("error handling", () => {
+ test("should handle unsupported file type", async () => {
+ mockGetServerForFile.mockReturnValueOnce(null);
+
+ const result = await lspTools[0].handler({
+ file: "test.unknown",
+ line: 1,
+ character: 5,
+ });
+
+ expect(result.isError).toBe(true);
+ expect(result.content[0].text).toContain("No language server available");
+ });
+
+ test("should handle LSP client errors", async () => {
+ mockLspClientManager.runWithClientLease.mockRejectedValueOnce(
+ new Error("LSP connection failed"),
+ );
+
+ const result = await lspTools[0].handler({
+ file: "test.ts",
+ line: 1,
+ character: 5,
+ });
+
+ expect(result.isError).toBe(true);
+ expect(result.content[0].text).toBe(
+ "Error in hover: LSP connection failed",
+ );
+ });
+ });
+});
diff --git a/packages/agent/tools/lsp.ts b/packages/agent/tools/lsp.ts
new file mode 100644
index 00000000..e3d10fed
--- /dev/null
+++ b/packages/agent/tools/lsp.ts
@@ -0,0 +1,624 @@
+/**
+ * LSP (Language Server Protocol) Tools
+ *
+ * Provides IDE-like capabilities to agents via real LSP server integration:
+ * - Hover information
+ * - Go to definition
+ * - Find references
+ * - Document/workspace symbols
+ * - Diagnostics
+ * - Rename
+ * - Code actions
+ */
+
+import { z } from "zod";
+import {
+ lspClientManager,
+ getAllServers,
+ getServerForFile,
+ formatHover,
+ formatLocations,
+ formatDocumentSymbols,
+ formatWorkspaceSymbols,
+ formatDiagnostics,
+ formatCodeActions,
+ formatWorkspaceEdit,
+ countEdits,
+} from "./lsp/index";
+import { runDirectoryDiagnostics } from "./diagnostics/index";
+import { ToolDefinition } from "./types";
+
+/**
+ * Helper to handle LSP errors gracefully.
+ * Uses runWithClientLease to protect the client from idle eviction
+ * while the operation is in flight.
+ */
+async function withLspClient(
+ filePath: string,
+ operation: string,
+ fn: (
+ client: NonNullable<
+ Awaited>
+ >,
+ ) => Promise,
+): Promise<{ isError?: true; content: Array<{ type: "text"; text: string }> }> {
+ try {
+ // Pre-check: is there a server for this file type?
+ const serverConfig = getServerForFile(filePath);
+ if (!serverConfig) {
+ return {
+ isError: true as const,
+ content: [
+ {
+ type: "text" as const,
+ text: `No language server available for file type: ${filePath}\n\nUse lsp_servers tool to see available language servers.`,
+ },
+ ],
+ };
+ }
+
+ const result = await lspClientManager.runWithClientLease(
+ filePath,
+ async (client) => {
+ return fn(client);
+ },
+ );
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: String(result),
+ },
+ ],
+ };
+ } catch (error) {
+ const message = error instanceof Error ? error.message : String(error);
+ // Surface install hints for missing servers
+ if (message.includes("not found")) {
+ return {
+ isError: true as const,
+ content: [
+ {
+ type: "text" as const,
+ text: `${message}`,
+ },
+ ],
+ };
+ }
+ return {
+ isError: true as const,
+ content: [
+ {
+ type: "text" as const,
+ text: `Error in ${operation}: ${message}`,
+ },
+ ],
+ };
+ }
+}
+
+/**
+ * LSP Hover Tool - Get type information and documentation at a position
+ */
+export const lspHoverTool: ToolDefinition<{
+ file: z.ZodString;
+ line: z.ZodNumber;
+ character: z.ZodNumber;
+}> = {
+ name: "lsp_hover",
+ description:
+ "Get type information, documentation, and signature at a specific position in a file. Useful for understanding what a symbol represents.",
+ schema: {
+ file: z.string().describe("Path to the source file"),
+ line: z.number().int().min(1).describe("Line number (1-indexed)"),
+ character: z
+ .number()
+ .int()
+ .min(0)
+ .describe("Character position in the line (0-indexed)"),
+ },
+ handler: async (args) => {
+ const { file, line, character } = args;
+ return withLspClient(file, "hover", async (client) => {
+ const hover = await client!.hover(file, line - 1, character);
+ return formatHover(hover);
+ });
+ },
+};
+
+/**
+ * LSP Go to Definition Tool - Jump to where a symbol is defined
+ */
+export const lspGotoDefinitionTool: ToolDefinition<{
+ file: z.ZodString;
+ line: z.ZodNumber;
+ character: z.ZodNumber;
+}> = {
+ name: "lsp_goto_definition",
+ description:
+ "Find the definition location of a symbol (function, variable, class, etc.). Returns the file path and position where the symbol is defined.",
+ schema: {
+ file: z.string().describe("Path to the source file"),
+ line: z.number().int().min(1).describe("Line number (1-indexed)"),
+ character: z
+ .number()
+ .int()
+ .min(0)
+ .describe("Character position in the line (0-indexed)"),
+ },
+ handler: async (args) => {
+ const { file, line, character } = args;
+ return withLspClient(file, "goto definition", async (client) => {
+ const locations = await client!.definition(file, line - 1, character);
+ return formatLocations(locations);
+ });
+ },
+};
+
+/**
+ * LSP Find References Tool - Find all usages of a symbol
+ */
+export const lspFindReferencesTool: ToolDefinition<{
+ file: z.ZodString;
+ line: z.ZodNumber;
+ character: z.ZodNumber;
+ includeDeclaration: z.ZodOptional;
+}> = {
+ name: "lsp_find_references",
+ description:
+ "Find all references to a symbol across the codebase. Useful for understanding usage patterns and impact of changes.",
+ schema: {
+ file: z.string().describe("Path to the source file"),
+ line: z.number().int().min(1).describe("Line number (1-indexed)"),
+ character: z
+ .number()
+ .int()
+ .min(0)
+ .describe("Character position in the line (0-indexed)"),
+ includeDeclaration: z
+ .boolean()
+ .optional()
+ .describe("Include the declaration in results (default: true)"),
+ },
+ handler: async (args) => {
+ const { file, line, character, includeDeclaration = true } = args;
+ return withLspClient(file, "find references", async (client) => {
+ const locations = await client!.references(
+ file,
+ line - 1,
+ character,
+ includeDeclaration,
+ );
+ if (!locations || locations.length === 0) {
+ return "No references found";
+ }
+ return `Found ${locations.length} reference(s):\n\n${formatLocations(locations)}`;
+ });
+ },
+};
+
+/**
+ * LSP Document Symbols Tool - Get outline of all symbols in a file
+ */
+export const lspDocumentSymbolsTool: ToolDefinition<{
+ file: z.ZodString;
+}> = {
+ name: "lsp_document_symbols",
+ description:
+ "Get a hierarchical outline of all symbols in a file (functions, classes, variables, etc.). Useful for understanding file structure.",
+ schema: {
+ file: z.string().describe("Path to the source file"),
+ },
+ handler: async (args) => {
+ const { file } = args;
+ return withLspClient(file, "document symbols", async (client) => {
+ const symbols = await client!.documentSymbols(file);
+ return formatDocumentSymbols(symbols);
+ });
+ },
+};
+
+/**
+ * LSP Workspace Symbols Tool - Search symbols across workspace
+ */
+export const lspWorkspaceSymbolsTool: ToolDefinition<{
+ query: z.ZodString;
+ file: z.ZodString;
+}> = {
+ name: "lsp_workspace_symbols",
+ description:
+ "Search for symbols (functions, classes, etc.) across the entire workspace by name. Useful for finding definitions without knowing the exact file.",
+ schema: {
+ query: z.string().describe("Symbol name or pattern to search"),
+ file: z
+ .string()
+ .describe(
+ "Any file in the workspace (used to determine which language server to use)",
+ ),
+ },
+ handler: async (args) => {
+ const { query, file } = args;
+ return withLspClient(file, "workspace symbols", async (client) => {
+ const symbols = await client!.workspaceSymbols(query);
+ if (!symbols || symbols.length === 0) {
+ return `No symbols found matching: ${query}`;
+ }
+ return `Found ${symbols.length} symbol(s) matching "${query}":\n\n${formatWorkspaceSymbols(symbols)}`;
+ });
+ },
+};
+
+/**
+ * LSP Diagnostics Tool - Get errors, warnings, and hints
+ */
+export const lspDiagnosticsTool: ToolDefinition<{
+ file: z.ZodString;
+ severity: z.ZodOptional>;
+}> = {
+ name: "lsp_diagnostics",
+ description:
+ "Get language server diagnostics (errors, warnings, hints) for a file. Useful for finding issues without running the compiler.",
+ schema: {
+ file: z.string().describe("Path to the source file"),
+ severity: z
+ .enum(["error", "warning", "info", "hint"])
+ .optional()
+ .describe("Filter by severity level"),
+ },
+ handler: async (args) => {
+ const { file, severity } = args;
+ return withLspClient(file, "diagnostics", async (client) => {
+ await client!.openDocument(file);
+
+ let diagnostics;
+ if (client!.supportsPullDiagnostics) {
+ diagnostics = await client!.pullDiagnostics(file);
+ } else {
+ await client!.waitForDiagnostics(file, 30_000);
+ diagnostics = client!.getDiagnostics(file);
+ }
+
+ if (severity) {
+ const severityMap: Record = {
+ error: 1,
+ warning: 2,
+ info: 3,
+ hint: 4,
+ };
+ const severityNum = severityMap[severity];
+ diagnostics = diagnostics.filter((d) => d.severity === severityNum);
+ }
+
+ if (diagnostics.length === 0) {
+ return severity
+ ? `No ${severity} diagnostics in ${file}`
+ : `No diagnostics in ${file}`;
+ }
+
+ return `Found ${diagnostics.length} diagnostic(s):\n\n${formatDiagnostics(diagnostics, file)}`;
+ });
+ },
+};
+
+/**
+ * LSP Servers Tool - List available language servers
+ */
+export const lspServersTool: ToolDefinition> = {
+ name: "lsp_servers",
+ description:
+ "List all known language servers and their installation status. Shows which servers are available and how to install missing ones.",
+ schema: {},
+ handler: async () => {
+ const servers = getAllServers();
+
+ const installed = servers.filter((s) => s.installed);
+ const notInstalled = servers.filter((s) => !s.installed);
+
+ let text = "## Language Server Status\n\n";
+
+ if (installed.length > 0) {
+ text += "### Installed:\n";
+ for (const server of installed) {
+ text += `- ${server.name} (${server.command})\n`;
+ text += ` Extensions: ${server.extensions.join(", ")}\n`;
+ }
+ text += "\n";
+ }
+
+ if (notInstalled.length > 0) {
+ text += "### Not Installed:\n";
+ for (const server of notInstalled) {
+ text += `- ${server.name} (${server.command})\n`;
+ text += ` Extensions: ${server.extensions.join(", ")}\n`;
+ text += ` Install: ${server.installHint}\n`;
+ }
+ }
+
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text,
+ },
+ ],
+ };
+ },
+};
+
+/**
+ * LSP Prepare Rename Tool - Check if rename is valid
+ */
+export const lspPrepareRenameTool: ToolDefinition<{
+ file: z.ZodString;
+ line: z.ZodNumber;
+ character: z.ZodNumber;
+}> = {
+ name: "lsp_prepare_rename",
+ description:
+ "Check if a symbol at the given position can be renamed. Returns the range of the symbol if rename is possible.",
+ schema: {
+ file: z.string().describe("Path to the source file"),
+ line: z.number().int().min(1).describe("Line number (1-indexed)"),
+ character: z
+ .number()
+ .int()
+ .min(0)
+ .describe("Character position in the line (0-indexed)"),
+ },
+ handler: async (args) => {
+ const { file, line, character } = args;
+ return withLspClient(file, "prepare rename", async (client) => {
+ const range = await client!.prepareRename(file, line - 1, character);
+ if (!range) {
+ return "Cannot rename symbol at this position";
+ }
+ return `Rename possible. Symbol range: line ${range.start.line + 1}, col ${range.start.character + 1} to line ${range.end.line + 1}, col ${range.end.character + 1}`;
+ });
+ },
+};
+
+/**
+ * LSP Rename Tool - Rename a symbol across all files
+ */
+export const lspRenameTool: ToolDefinition<{
+ file: z.ZodString;
+ line: z.ZodNumber;
+ character: z.ZodNumber;
+ newName: z.ZodString;
+}> = {
+ name: "lsp_rename",
+ description:
+ "Rename a symbol (variable, function, class, etc.) across all files in the project. Returns the list of edits that would be made. Does NOT apply the changes automatically.",
+ schema: {
+ file: z.string().describe("Path to the source file"),
+ line: z.number().int().min(1).describe("Line number (1-indexed)"),
+ character: z
+ .number()
+ .int()
+ .min(0)
+ .describe("Character position in the line (0-indexed)"),
+ newName: z.string().min(1).describe("New name for the symbol"),
+ },
+ handler: async (args) => {
+ const { file, line, character, newName } = args;
+ return withLspClient(file, "rename", async (client) => {
+ const edit = await client!.rename(file, line - 1, character, newName);
+ if (!edit) {
+ return "Rename failed or no edits returned";
+ }
+
+ const { files, edits } = countEdits(edit);
+ return `Rename to "${newName}" would affect ${files} file(s) with ${edits} edit(s):\n\n${formatWorkspaceEdit(edit)}\n\nNote: Use the Edit tool to apply these changes.`;
+ });
+ },
+};
+
+/**
+ * LSP Code Actions Tool - Get available refactoring and quick-fix actions
+ */
+export const lspCodeActionsTool: ToolDefinition<{
+ file: z.ZodString;
+ startLine: z.ZodNumber;
+ startCharacter: z.ZodNumber;
+ endLine: z.ZodNumber;
+ endCharacter: z.ZodNumber;
+}> = {
+ name: "lsp_code_actions",
+ description:
+ "Get available code actions (refactorings, quick fixes) for a selection. Returns a list of possible actions that can be applied.",
+ schema: {
+ file: z.string().describe("Path to the source file"),
+ startLine: z
+ .number()
+ .int()
+ .min(1)
+ .describe("Start line of selection (1-indexed)"),
+ startCharacter: z
+ .number()
+ .int()
+ .min(0)
+ .describe("Start character of selection (0-indexed)"),
+ endLine: z
+ .number()
+ .int()
+ .min(1)
+ .describe("End line of selection (1-indexed)"),
+ endCharacter: z
+ .number()
+ .int()
+ .min(0)
+ .describe("End character of selection (0-indexed)"),
+ },
+ handler: async (args) => {
+ const { file, startLine, startCharacter, endLine, endCharacter } = args;
+ return withLspClient(file, "code actions", async (client) => {
+ const range = {
+ start: { line: startLine - 1, character: startCharacter },
+ end: { line: endLine - 1, character: endCharacter },
+ };
+ const actions = await client!.codeActions(file, range);
+ return formatCodeActions(actions);
+ });
+ },
+};
+
+/**
+ * LSP Code Action Resolve Tool - Get details of a code action
+ */
+export const lspCodeActionResolveTool: ToolDefinition<{
+ file: z.ZodString;
+ startLine: z.ZodNumber;
+ startCharacter: z.ZodNumber;
+ endLine: z.ZodNumber;
+ endCharacter: z.ZodNumber;
+ actionIndex: z.ZodNumber;
+}> = {
+ name: "lsp_code_action_resolve",
+ description:
+ "Get the full edit details for a specific code action. Use after lsp_code_actions to see what changes an action would make.",
+ schema: {
+ file: z.string().describe("Path to the source file"),
+ startLine: z
+ .number()
+ .int()
+ .min(1)
+ .describe("Start line of selection (1-indexed)"),
+ startCharacter: z
+ .number()
+ .int()
+ .min(0)
+ .describe("Start character of selection (0-indexed)"),
+ endLine: z
+ .number()
+ .int()
+ .min(1)
+ .describe("End line of selection (1-indexed)"),
+ endCharacter: z
+ .number()
+ .int()
+ .min(0)
+ .describe("End character of selection (0-indexed)"),
+ actionIndex: z
+ .number()
+ .int()
+ .min(1)
+ .describe(
+ "Index of the action (1-indexed, from lsp_code_actions output)",
+ ),
+ },
+ handler: async (args) => {
+ const {
+ file,
+ startLine,
+ startCharacter,
+ endLine,
+ endCharacter,
+ actionIndex,
+ } = args;
+ return withLspClient(file, "code action resolve", async (client) => {
+ const range = {
+ start: { line: startLine - 1, character: startCharacter },
+ end: { line: endLine - 1, character: endCharacter },
+ };
+ const actions = await client!.codeActions(file, range);
+
+ if (!actions || actions.length === 0) {
+ return "No code actions available";
+ }
+
+ if (actionIndex < 1 || actionIndex > actions.length) {
+ return `Invalid action index. Available actions: 1-${actions.length}`;
+ }
+
+ const action = actions[actionIndex - 1];
+
+ let result = `Action: ${action.title}\n`;
+ if (action.kind) result += `Kind: ${action.kind}\n`;
+ if (action.isPreferred) result += `(Preferred)\n`;
+
+ if (action.edit) {
+ result += `\nEdits:\n${formatWorkspaceEdit(action.edit)}`;
+ }
+
+ if (action.command) {
+ result += `\nCommand: ${action.command.title} (${action.command.command})`;
+ }
+
+ return result;
+ });
+ },
+};
+
+/**
+ * LSP Diagnostics Directory Tool - Get project-level diagnostics
+ */
+export const lspDiagnosticsDirectoryTool: ToolDefinition<{
+ directory: z.ZodString;
+ strategy: z.ZodOptional>;
+}> = {
+ name: "lsp_diagnostics_directory",
+ description:
+ "Run project-level diagnostics on a directory using tsc --noEmit (preferred) or LSP iteration (fallback). Useful for checking the entire codebase for errors.",
+ schema: {
+ directory: z.string().describe("Project directory to check"),
+ strategy: z
+ .enum(["tsc", "lsp", "auto"])
+ .optional()
+ .describe(
+ 'Strategy to use: "tsc" (TypeScript compiler), "lsp" (Language Server iteration), or "auto" (default: auto-detect)',
+ ),
+ },
+ handler: async (args) => {
+ const { directory, strategy = "auto" } = args;
+ try {
+ const result = await runDirectoryDiagnostics(directory, strategy);
+
+ let output = `## Directory Diagnostics\n\n`;
+ output += `Strategy: ${result.strategy}\n`;
+ output += `Summary: ${result.summary}\n\n`;
+
+ if (result.errorCount > 0 || result.warningCount > 0) {
+ output += `### Diagnostics\n\n${result.diagnostics}`;
+ } else {
+ output += result.diagnostics;
+ }
+
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: output,
+ },
+ ],
+ };
+ } catch (error) {
+ return {
+ isError: true as const,
+ content: [
+ {
+ type: "text" as const,
+ text: `Error running directory diagnostics: ${error instanceof Error ? error.message : String(error)}`,
+ },
+ ],
+ };
+ }
+ },
+};
+
+/**
+ * Get all LSP tool definitions
+ */
+export const lspTools = [
+ lspHoverTool,
+ lspGotoDefinitionTool,
+ lspFindReferencesTool,
+ lspDocumentSymbolsTool,
+ lspWorkspaceSymbolsTool,
+ lspDiagnosticsTool,
+ lspDiagnosticsDirectoryTool,
+ lspServersTool,
+ lspPrepareRenameTool,
+ lspRenameTool,
+ lspCodeActionsTool,
+ lspCodeActionResolveTool,
+];
diff --git a/packages/agent/tools/notepad.test.ts b/packages/agent/tools/notepad.test.ts
new file mode 100644
index 00000000..adb67f1f
--- /dev/null
+++ b/packages/agent/tools/notepad.test.ts
@@ -0,0 +1,416 @@
+import { describe, test, expect, mock, beforeEach, afterEach } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+// Mock notepad hooks
+const mockGetPriorityContext = mock(() => "Priority context content");
+const mockGetWorkingMemory = mock(
+ () => "Working memory entries\n- Entry 1\n- Entry 2",
+);
+const mockGetManualSection = mock(() => "Manual section content");
+const mockSetPriorityContext = mock(() => ({ success: true }));
+const mockAddWorkingMemoryEntry = mock(() => true);
+const mockAddManualEntry = mock(() => true);
+const mockPruneOldEntries = mock(() => ({ pruned: 2, remaining: 5 }));
+const mockGetNotepadStats = mock(() => ({
+ exists: true,
+ totalSize: 1024,
+ prioritySize: 256,
+ workingMemoryEntries: 3,
+ oldestEntry: "2024-01-01",
+}));
+const mockFormatFullNotepad = mock(
+ () =>
+ "## Priority Context\nContent\n\n## Working Memory\nEntries\n\n## MANUAL\nManual content",
+);
+const mockDEFAULT_CONFIG = { workingMemoryDays: 7 };
+
+mock.module("../hooks/notepad/index.js", () => ({
+ getPriorityContext: mockGetPriorityContext,
+ getWorkingMemory: mockGetWorkingMemory,
+ getManualSection: mockGetManualSection,
+ setPriorityContext: mockSetPriorityContext,
+ addWorkingMemoryEntry: mockAddWorkingMemoryEntry,
+ addManualEntry: mockAddManualEntry,
+ pruneOldEntries: mockPruneOldEntries,
+ getNotepadStats: mockGetNotepadStats,
+ formatFullNotepad: mockFormatFullNotepad,
+ DEFAULT_CONFIG: mockDEFAULT_CONFIG,
+}));
+
+// Mock worktree paths
+const mockGetWorktreeNotepadPath = mock((root: string) =>
+ path.join(root, ".omc", "notepad.md"),
+);
+const mockEnsureOmcDir = mock(() => {});
+const mockValidateWorkingDirectory = mock((wd?: string) => wd || "/test/root");
+
+mock.module("../lib/worktree-paths.js", () => ({
+ getWorktreeNotepadPath: mockGetWorktreeNotepadPath,
+ ensureOmcDir: mockEnsureOmcDir,
+ validateWorkingDirectory: mockValidateWorkingDirectory,
+}));
+
+// Import after mocking
+const { notepadTools } = await import("./notepad");
+
+describe("Notepad Tools", () => {
+ let testRoot: string;
+
+ beforeEach(async () => {
+ testRoot = await mkdtemp(path.join(tmpdir(), "notepad-test-"));
+
+ // Reset all mocks
+ Object.values({
+ mockGetPriorityContext,
+ mockGetWorkingMemory,
+ mockGetManualSection,
+ mockSetPriorityContext,
+ mockAddWorkingMemoryEntry,
+ mockAddManualEntry,
+ mockPruneOldEntries,
+ mockGetNotepadStats,
+ mockFormatFullNotepad,
+ mockGetWorktreeNotepadPath,
+ mockEnsureOmcDir,
+ mockValidateWorkingDirectory,
+ }).forEach((mock) => mock.mockClear());
+ });
+
+ afterEach(async () => {
+ try {
+ await rm(testRoot, { recursive: true, force: true });
+ } catch {
+ // Ignore cleanup errors
+ }
+ });
+
+ test("should export notepadTools array with 6 tools", () => {
+ expect(Array.isArray(notepadTools)).toBe(true);
+ expect(notepadTools.length).toBe(6);
+
+ const toolNames = notepadTools.map((t) => t.name);
+ expect(toolNames).toEqual([
+ "notepad_read",
+ "notepad_write_priority",
+ "notepad_write_working",
+ "notepad_write_manual",
+ "notepad_prune",
+ "notepad_stats",
+ ]);
+ });
+
+ test("each tool should have required properties with correct types", () => {
+ for (const tool of notepadTools) {
+ expect(tool).toHaveProperty("name");
+ expect(tool).toHaveProperty("description");
+ expect(tool).toHaveProperty("schema");
+ expect(tool).toHaveProperty("handler");
+
+ expect(typeof tool.name).toBe("string");
+ expect(typeof tool.description).toBe("string");
+ expect(typeof tool.handler).toBe("function");
+ expect(typeof tool.schema).toBe("object");
+ }
+ });
+
+ describe("notepad_read tool", () => {
+ test('should read full notepad when section is "all"', async () => {
+ const result = await notepadTools[0].handler({
+ section: "all",
+ workingDirectory: testRoot,
+ });
+
+ expect(mockValidateWorkingDirectory).toHaveBeenCalledWith(testRoot);
+ expect(mockFormatFullNotepad).toHaveBeenCalledWith(testRoot);
+ expect(result.content[0].text).toContain("## Notepad");
+ expect(result.content[0].text).toContain("Path:");
+ });
+
+ test("should read priority section", async () => {
+ const result = await notepadTools[0].handler({
+ section: "priority",
+ workingDirectory: testRoot,
+ });
+
+ expect(mockGetPriorityContext).toHaveBeenCalledWith(testRoot);
+ expect(result.content[0].text).toBe(
+ "## Priority Context\n\nPriority context content",
+ );
+ });
+
+ test("should read working memory section", async () => {
+ const result = await notepadTools[0].handler({
+ section: "working",
+ workingDirectory: testRoot,
+ });
+
+ expect(mockGetWorkingMemory).toHaveBeenCalledWith(testRoot);
+ expect(result.content[0].text).toBe(
+ "## Working Memory\n\nWorking memory entries\n- Entry 1\n- Entry 2",
+ );
+ });
+
+ test("should read manual section", async () => {
+ const result = await notepadTools[0].handler({
+ section: "manual",
+ workingDirectory: testRoot,
+ });
+
+ expect(mockGetManualSection).toHaveBeenCalledWith(testRoot);
+ expect(result.content[0].text).toBe(
+ "## MANUAL\n\nManual section content",
+ );
+ });
+
+ test("should handle empty sections", async () => {
+ mockGetPriorityContext.mockReturnValueOnce(null);
+
+ const result = await notepadTools[0].handler({
+ section: "priority",
+ workingDirectory: testRoot,
+ });
+
+ expect(result.content[0].text).toBe(
+ "## Priority Context\n\n(Empty or notepad does not exist)",
+ );
+ });
+
+ test("should handle missing notepad", async () => {
+ mockFormatFullNotepad.mockReturnValueOnce(null);
+
+ const result = await notepadTools[0].handler({
+ section: "all",
+ workingDirectory: testRoot,
+ });
+
+ expect(result.content[0].text).toBe(
+ "Notepad does not exist. Use notepad_write_* tools to create it.",
+ );
+ });
+
+ test("should use default working directory", async () => {
+ const _result = await notepadTools[0].handler({
+ section: "all",
+ });
+
+ expect(mockValidateWorkingDirectory).toHaveBeenCalledWith(undefined);
+ });
+ });
+
+ describe("notepad_write_priority tool", () => {
+ test("should write priority context successfully", async () => {
+ const result = await notepadTools[1].handler({
+ content: "New priority content",
+ workingDirectory: testRoot,
+ });
+
+ expect(mockValidateWorkingDirectory).toHaveBeenCalledWith(testRoot);
+ expect(mockEnsureOmcDir).toHaveBeenCalled();
+ expect(mockSetPriorityContext).toHaveBeenCalledWith(
+ testRoot,
+ "New priority content",
+ );
+ expect(result.content[0].text).toBe(
+ "Successfully wrote to Priority Context (20 chars)",
+ );
+ });
+
+ test("should handle write failure", async () => {
+ mockSetPriorityContext.mockReturnValueOnce({ success: false });
+
+ const result = await notepadTools[1].handler({
+ content: "Content",
+ workingDirectory: testRoot,
+ });
+
+ expect(result.content[0].text).toBe(
+ "Failed to write to Priority Context. Check file permissions.",
+ );
+ });
+
+ test("should show warning on long content", async () => {
+ mockSetPriorityContext.mockReturnValueOnce({
+ success: true,
+ warning: "Content exceeds recommended length",
+ });
+
+ const result = await notepadTools[1].handler({
+ content: "Very long content that exceeds limits",
+ workingDirectory: testRoot,
+ });
+
+ expect(result.content[0].text).toContain(
+ "**Warning:** Content exceeds recommended length",
+ );
+ });
+
+ test("should accept content up to max length", async () => {
+ const maxContent = "x".repeat(2000);
+
+ const result = await notepadTools[1].handler({
+ content: maxContent,
+ workingDirectory: testRoot,
+ });
+
+ expect(result.content[0].text).toContain("Successfully wrote");
+ });
+ });
+
+ describe("notepad_write_working tool", () => {
+ test("should add working memory entry successfully", async () => {
+ const result = await notepadTools[2].handler({
+ content: "New working memory entry",
+ workingDirectory: testRoot,
+ });
+
+ expect(mockAddWorkingMemoryEntry).toHaveBeenCalledWith(
+ testRoot,
+ "New working memory entry",
+ );
+ expect(result.content[0].text).toBe(
+ "Successfully added entry to Working Memory (24 chars)",
+ );
+ });
+
+ test("should handle add failure", async () => {
+ mockAddWorkingMemoryEntry.mockReturnValueOnce(false);
+
+ const result = await notepadTools[2].handler({
+ content: "Content",
+ workingDirectory: testRoot,
+ });
+
+ expect(result.content[0].text).toBe(
+ "Failed to add entry to Working Memory. Check file permissions.",
+ );
+ });
+ });
+
+ describe("notepad_write_manual tool", () => {
+ test("should add manual entry successfully", async () => {
+ const result = await notepadTools[3].handler({
+ content: "New manual entry",
+ workingDirectory: testRoot,
+ });
+
+ expect(mockAddManualEntry).toHaveBeenCalledWith(
+ testRoot,
+ "New manual entry",
+ );
+ expect(result.content[0].text).toBe(
+ "Successfully added entry to MANUAL section (16 chars)",
+ );
+ });
+
+ test("should handle add failure", async () => {
+ mockAddManualEntry.mockReturnValueOnce(false);
+
+ const result = await notepadTools[3].handler({
+ content: "Content",
+ workingDirectory: testRoot,
+ });
+
+ expect(result.content[0].text).toBe(
+ "Failed to add entry to MANUAL section. Check file permissions.",
+ );
+ });
+ });
+
+ describe("notepad_prune tool", () => {
+ test("should prune entries with default days", async () => {
+ const result = await notepadTools[4].handler({
+ workingDirectory: testRoot,
+ });
+
+ expect(mockPruneOldEntries).toHaveBeenCalledWith(testRoot, 7);
+ expect(result.content[0].text).toBe(
+ "## Prune Results\n\n- Pruned: 2 entries\n- Remaining: 5 entries\n- Threshold: 7 days",
+ );
+ });
+
+ test("should prune entries with custom days", async () => {
+ const result = await notepadTools[4].handler({
+ daysOld: 14,
+ workingDirectory: testRoot,
+ });
+
+ expect(mockPruneOldEntries).toHaveBeenCalledWith(testRoot, 14);
+ expect(result.content[0].text).toContain("Threshold: 14 days");
+ });
+ });
+
+ describe("notepad_stats tool", () => {
+ test("should get notepad statistics", async () => {
+ const result = await notepadTools[5].handler({
+ workingDirectory: testRoot,
+ });
+
+ expect(mockGetNotepadStats).toHaveBeenCalledWith(testRoot);
+ expect(result.content[0].text).toContain("## Notepad Statistics");
+ expect(result.content[0].text).toContain("**Total Size:** 1024 bytes");
+ expect(result.content[0].text).toContain("**Working Memory Entries:** 3");
+ expect(result.content[0].text).toContain("Path:");
+ });
+
+ test("should handle non-existent notepad", async () => {
+ mockGetNotepadStats.mockReturnValueOnce({ exists: false });
+
+ const result = await notepadTools[5].handler({
+ workingDirectory: testRoot,
+ });
+
+ expect(result.content[0].text).toBe(
+ "## Notepad Statistics\n\nNotepad does not exist yet.",
+ );
+ });
+ });
+
+ describe("error handling", () => {
+ test("should handle validation errors", async () => {
+ mockValidateWorkingDirectory.mockImplementationOnce(() => {
+ throw new Error("Invalid working directory");
+ });
+
+ const result = await notepadTools[0].handler({
+ section: "all",
+ workingDirectory: "/invalid/path",
+ });
+
+ expect(result.content[0].text).toBe(
+ "Error reading notepad: Invalid working directory",
+ );
+ });
+
+ test("should handle hook errors", async () => {
+ mockGetPriorityContext.mockImplementationOnce(() => {
+ throw new Error("File system error");
+ });
+
+ const result = await notepadTools[0].handler({
+ section: "priority",
+ workingDirectory: testRoot,
+ });
+
+ expect(result.content[0].text).toBe(
+ "Error reading notepad: File system error",
+ );
+ });
+ });
+
+ describe("schema validation", () => {
+ test("notepad_write_priority should have content schema", () => {
+ expect(notepadTools[1].schema).toHaveProperty("content");
+ });
+
+ test("write tools should have content schema", () => {
+ expect(notepadTools[2].schema).toHaveProperty("content");
+ expect(notepadTools[3].schema).toHaveProperty("content");
+ });
+
+ test("notepad_prune should have daysOld schema", () => {
+ expect(notepadTools[4].schema).toHaveProperty("daysOld");
+ });
+ });
+});
diff --git a/packages/agent/tools/notepad.ts b/packages/agent/tools/notepad.ts
new file mode 100644
index 00000000..e00cfa7d
--- /dev/null
+++ b/packages/agent/tools/notepad.ts
@@ -0,0 +1,454 @@
+/**
+ * Notepad MCP Tools
+ *
+ * Provides tools for reading and writing notepad sections
+ * (Priority Context, Working Memory, MANUAL).
+ */
+
+import { z } from "zod";
+import {
+ getWorktreeNotepadPath,
+ ensureOmcDir,
+ validateWorkingDirectory,
+} from "../lib/worktree-paths";
+import {
+ getPriorityContext,
+ getWorkingMemory,
+ getManualSection,
+ setPriorityContext,
+ addWorkingMemoryEntry,
+ addManualEntry,
+ pruneOldEntries,
+ getNotepadStats,
+ formatFullNotepad,
+ DEFAULT_CONFIG,
+} from "../hooks/notepad/index";
+import { ToolDefinition } from "./types.js";
+
+const SECTION_NAMES: [string, ...string[]] = [
+ "all",
+ "priority",
+ "working",
+ "manual",
+];
+
+// ============================================================================
+// notepad_read - Read notepad content
+// ============================================================================
+
+export const notepadReadTool: ToolDefinition<{
+ section: z.ZodOptional>;
+ workingDirectory: z.ZodOptional;
+}> = {
+ name: "notepad_read",
+ description:
+ "Read the notepad content. Can read the full notepad or a specific section (priority, working, manual).",
+ schema: {
+ section: z
+ .enum(SECTION_NAMES)
+ .optional()
+ .describe(
+ 'Section to read: "all" (default), "priority", "working", or "manual"',
+ ),
+ workingDirectory: z
+ .string()
+ .optional()
+ .describe("Working directory (defaults to cwd)"),
+ },
+ handler: async (args) => {
+ const { section = "all", workingDirectory } = args;
+
+ try {
+ const root = validateWorkingDirectory(workingDirectory);
+
+ if (section === "all") {
+ const content = formatFullNotepad(root);
+ if (!content) {
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: "Notepad does not exist. Use notepad_write_* tools to create it.",
+ },
+ ],
+ };
+ }
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: `## Notepad\n\nPath: ${getWorktreeNotepadPath(root)}\n\n${content}`,
+ },
+ ],
+ };
+ }
+
+ let sectionContent: string | null = null;
+ let sectionTitle = "";
+
+ switch (section) {
+ case "priority":
+ sectionContent = getPriorityContext(root);
+ sectionTitle = "Priority Context";
+ break;
+ case "working":
+ sectionContent = getWorkingMemory(root);
+ sectionTitle = "Working Memory";
+ break;
+ case "manual":
+ sectionContent = getManualSection(root);
+ sectionTitle = "MANUAL";
+ break;
+ }
+
+ if (!sectionContent) {
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: `## ${sectionTitle}\n\n(Empty or notepad does not exist)`,
+ },
+ ],
+ };
+ }
+
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: `## ${sectionTitle}\n\n${sectionContent}`,
+ },
+ ],
+ };
+ } catch (error) {
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: `Error reading notepad: ${error instanceof Error ? error.message : String(error)}`,
+ },
+ ],
+ };
+ }
+ },
+};
+
+// ============================================================================
+// notepad_write_priority - Write to Priority Context
+// ============================================================================
+
+export const notepadWritePriorityTool: ToolDefinition<{
+ content: z.ZodString;
+ workingDirectory: z.ZodOptional;
+}> = {
+ name: "notepad_write_priority",
+ description:
+ "Write to the Priority Context section. This REPLACES the existing content. Keep under 500 chars - this is always loaded at session start.",
+ schema: {
+ content: z
+ .string()
+ .max(2000)
+ .describe("Content to write (recommend under 500 chars)"),
+ workingDirectory: z
+ .string()
+ .optional()
+ .describe("Working directory (defaults to cwd)"),
+ },
+ handler: async (args) => {
+ const { content, workingDirectory } = args;
+
+ try {
+ const root = validateWorkingDirectory(workingDirectory);
+
+ // Ensure .omc directory exists
+ ensureOmcDir("", root);
+
+ const result = setPriorityContext(root, content);
+
+ if (!result.success) {
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: "Failed to write to Priority Context. Check file permissions.",
+ },
+ ],
+ };
+ }
+
+ let response = `Successfully wrote to Priority Context (${content.length} chars)`;
+ if (result.warning) {
+ response += `\n\n**Warning:** ${result.warning}`;
+ }
+
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: response,
+ },
+ ],
+ };
+ } catch (error) {
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: `Error writing to Priority Context: ${error instanceof Error ? error.message : String(error)}`,
+ },
+ ],
+ };
+ }
+ },
+};
+
+// ============================================================================
+// notepad_write_working - Add to Working Memory
+// ============================================================================
+
+export const notepadWriteWorkingTool: ToolDefinition<{
+ content: z.ZodString;
+ workingDirectory: z.ZodOptional;
+}> = {
+ name: "notepad_write_working",
+ description:
+ "Add an entry to Working Memory section. Entries are timestamped and auto-pruned after 7 days.",
+ schema: {
+ content: z.string().max(4000).describe("Content to add as a new entry"),
+ workingDirectory: z
+ .string()
+ .optional()
+ .describe("Working directory (defaults to cwd)"),
+ },
+ handler: async (args) => {
+ const { content, workingDirectory } = args;
+
+ try {
+ const root = validateWorkingDirectory(workingDirectory);
+
+ // Ensure .omc directory exists
+ ensureOmcDir("", root);
+
+ const success = addWorkingMemoryEntry(root, content);
+
+ if (!success) {
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: "Failed to add entry to Working Memory. Check file permissions.",
+ },
+ ],
+ };
+ }
+
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: `Successfully added entry to Working Memory (${content.length} chars)`,
+ },
+ ],
+ };
+ } catch (error) {
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: `Error writing to Working Memory: ${error instanceof Error ? error.message : String(error)}`,
+ },
+ ],
+ };
+ }
+ },
+};
+
+// ============================================================================
+// notepad_write_manual - Add to MANUAL section
+// ============================================================================
+
+export const notepadWriteManualTool: ToolDefinition<{
+ content: z.ZodString;
+ workingDirectory: z.ZodOptional;
+}> = {
+ name: "notepad_write_manual",
+ description:
+ "Add an entry to the MANUAL section. Content in this section is never auto-pruned.",
+ schema: {
+ content: z.string().max(4000).describe("Content to add as a new entry"),
+ workingDirectory: z
+ .string()
+ .optional()
+ .describe("Working directory (defaults to cwd)"),
+ },
+ handler: async (args) => {
+ const { content, workingDirectory } = args;
+
+ try {
+ const root = validateWorkingDirectory(workingDirectory);
+
+ // Ensure .omc directory exists
+ ensureOmcDir("", root);
+
+ const success = addManualEntry(root, content);
+
+ if (!success) {
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: "Failed to add entry to MANUAL section. Check file permissions.",
+ },
+ ],
+ };
+ }
+
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: `Successfully added entry to MANUAL section (${content.length} chars)`,
+ },
+ ],
+ };
+ } catch (error) {
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: `Error writing to MANUAL: ${error instanceof Error ? error.message : String(error)}`,
+ },
+ ],
+ };
+ }
+ },
+};
+
+// ============================================================================
+// notepad_prune - Prune old Working Memory entries
+// ============================================================================
+
+export const notepadPruneTool: ToolDefinition<{
+ daysOld: z.ZodOptional;
+ workingDirectory: z.ZodOptional;
+}> = {
+ name: "notepad_prune",
+ description:
+ "Prune Working Memory entries older than N days (default: 7 days).",
+ schema: {
+ daysOld: z
+ .number()
+ .int()
+ .min(1)
+ .max(365)
+ .optional()
+ .describe("Remove entries older than this many days (default: 7)"),
+ workingDirectory: z
+ .string()
+ .optional()
+ .describe("Working directory (defaults to cwd)"),
+ },
+ handler: async (args) => {
+ const { daysOld = DEFAULT_CONFIG.workingMemoryDays, workingDirectory } =
+ args;
+
+ try {
+ const root = validateWorkingDirectory(workingDirectory);
+ const result = pruneOldEntries(root, daysOld);
+
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: `## Prune Results\n\n- Pruned: ${result.pruned} entries\n- Remaining: ${result.remaining} entries\n- Threshold: ${daysOld} days`,
+ },
+ ],
+ };
+ } catch (error) {
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: `Error pruning notepad: ${error instanceof Error ? error.message : String(error)}`,
+ },
+ ],
+ };
+ }
+ },
+};
+
+// ============================================================================
+// notepad_stats - Get notepad statistics
+// ============================================================================
+
+export const notepadStatsTool: ToolDefinition<{
+ workingDirectory: z.ZodOptional;
+}> = {
+ name: "notepad_stats",
+ description:
+ "Get statistics about the notepad (size, entry count, oldest entry).",
+ schema: {
+ workingDirectory: z
+ .string()
+ .optional()
+ .describe("Working directory (defaults to cwd)"),
+ },
+ handler: async (args) => {
+ const { workingDirectory } = args;
+
+ try {
+ const root = validateWorkingDirectory(workingDirectory);
+ const stats = getNotepadStats(root);
+
+ if (!stats.exists) {
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: "## Notepad Statistics\n\nNotepad does not exist yet.",
+ },
+ ],
+ };
+ }
+
+ const lines = [
+ "## Notepad Statistics\n",
+ `- **Total Size:** ${stats.totalSize} bytes`,
+ `- **Priority Context Size:** ${stats.prioritySize} bytes`,
+ `- **Working Memory Entries:** ${stats.workingMemoryEntries}`,
+ `- **Oldest Entry:** ${stats.oldestEntry || "None"}`,
+ `- **Path:** ${getWorktreeNotepadPath(root)}`,
+ ];
+
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: lines.join("\n"),
+ },
+ ],
+ };
+ } catch (error) {
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text: `Error getting notepad stats: ${error instanceof Error ? error.message : String(error)}`,
+ },
+ ],
+ };
+ }
+ },
+};
+
+/**
+ * All notepad tools for registration
+ */
+export const notepadTools = [
+ notepadReadTool,
+ notepadWritePriorityTool,
+ notepadWriteWorkingTool,
+ notepadWriteManualTool,
+ notepadPruneTool,
+ notepadStatsTool,
+];
diff --git a/packages/agent/tools/tools.test.ts b/packages/agent/tools/tools.test.ts
index 81468248..813d0ea6 100644
--- a/packages/agent/tools/tools.test.ts
+++ b/packages/agent/tools/tools.test.ts
@@ -1,6 +1,15 @@
-import { afterEach, describe, expect, mock, test } from "bun:test";
+import {
+ afterEach,
+ beforeEach,
+ describe,
+ expect,
+ mock,
+ type Mock,
+ test,
+} from "bun:test";
import { mkdir, mkdtemp, readFile, stat, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
+
import path from "node:path";
import type { ToolNeedsApprovalFunction } from "./utils";
@@ -72,6 +81,7 @@ const { grepTool } = await import("./grep");
const { readFileTool } = await import("./read");
const { skillTool } = await import("./skill");
const { taskTool } = await import("./task");
+const { commitAndPrTool, TIMEOUT_MS } = await import("./github");
const { todoWriteTool } = await import("./todo");
const { editFileTool, writeFileTool } = await import("./write");
const { buildSystemPrompt } = await import("../system-prompt");
@@ -457,6 +467,237 @@ describe("tools execute behavior", () => {
expect(allowedBuildCommand).toBe(false);
});
+ describe("commitAndPrTool", () => {
+ // ทดสอบเครื่องมือ commit และสร้าง PR
+ let mockSandboxExec: Mock;
+ let mockSandbox: {
+ workingDirectory: string;
+ exec: Mock;
+ };
+
+ beforeEach(() => {
+ mockSandboxExec = mock(async (command: string) => {
+ if (command.startsWith("git checkout -b")) {
+ return { success: true, exitCode: 0, stdout: "", stderr: "" };
+ }
+ if (command === "git add -A") {
+ return { success: true, exitCode: 0, stdout: "", stderr: "" };
+ }
+ if (command.startsWith("git commit -m")) {
+ return { success: true, exitCode: 0, stdout: "", stderr: "" };
+ }
+ if (command.startsWith("git push -u origin")) {
+ return { success: true, exitCode: 0, stdout: "", stderr: "" };
+ }
+ if (command.startsWith("gh pr create")) {
+ return {
+ success: true,
+ exitCode: 0,
+ stdout: "https://github.com/test/repo/pull/1",
+ stderr: "",
+ };
+ }
+ return {
+ success: false,
+ exitCode: 1,
+ stdout: "",
+ stderr: `Unknown command: ${command}`,
+ };
+ });
+
+ mockSandbox = {
+ workingDirectory: "/repo",
+ exec: mockSandboxExec,
+ readFile: mock(
+ async () =>
+ "---\nname: review\ndescription: review code\n---\nRun review with $ARGUMENTS",
+ ),
+ };
+
+ // Mock getSandbox to return our controlled mockSandbox
+ mock.module("./utils", () => ({
+ getSandbox: mock(async () => mockSandbox),
+ }));
+ });
+
+ function createCommitAndPrContext() {
+ return {
+ sandbox: {
+ state: { type: "vercel" as const, sandboxId: "mock-sandbox-id" },
+ workingDirectory: mockSandbox.workingDirectory,
+ },
+ approval: {},
+ model: "test-model",
+ };
+ }
+
+ test("should successfully commit, push, and create a PR", async () => {
+ const args = {
+ needsApproval: true,
+ branchName: "feature/test-branch",
+ commitMessage: "feat: add new feature",
+ prTitle: "feat: Add new feature",
+ prBody: "This PR adds a new feature.",
+ };
+
+ const result = await commitAndPrTool.execute?.(
+ args,
+ executionOptions(createCommitAndPrContext()),
+ );
+
+ expect(result).toEqual({
+ success: true,
+ message: "Successfully committed, pushed, and created PR.",
+ prUrl: "https://github.com/test/repo/pull/1",
+ });
+
+ expect(mockSandboxExec).toHaveBeenCalledTimes(5);
+ expect(mockSandboxExec).toHaveBeenCalledWith(
+ `git checkout -b 'feature/test-branch'`,
+ mockSandbox.workingDirectory,
+ TIMEOUT_MS,
+ expect.any(Object),
+ );
+ expect(mockSandboxExec).toHaveBeenCalledWith(
+ "git add -A",
+ mockSandbox.workingDirectory,
+ TIMEOUT_MS,
+ expect.any(Object),
+ );
+ expect(mockSandboxExec).toHaveBeenCalledWith(
+ `git commit -m 'feat: add new feature'`,
+ mockSandbox.workingDirectory,
+ TIMEOUT_MS,
+ expect.any(Object),
+ );
+ expect(mockSandboxExec).toHaveBeenCalledWith(
+ `git push -u origin 'feature/test-branch'`,
+ mockSandbox.workingDirectory,
+ TIMEOUT_MS,
+ expect.any(Object),
+ );
+ expect(mockSandboxExec).toHaveBeenCalledWith(
+ `gh pr create --title 'feat: Add new feature' --body 'This PR adds a new feature.'`,
+ mockSandbox.workingDirectory,
+ TIMEOUT_MS,
+ expect.any(Object),
+ );
+ });
+
+ test("should return error if git commit fails for a non-'nothing to commit' reason", async () => {
+ mockSandbox.exec.mockImplementation(async (command: string) => {
+ if (command.startsWith("git commit -m")) {
+ return {
+ success: false,
+ exitCode: 1,
+ stdout: "Commit failed",
+ stderr: "Pre-commit hook failed",
+ };
+ }
+ return { success: true, exitCode: 0, stdout: "", stderr: "" }; // Other commands succeed
+ });
+
+ const args = {
+ needsApproval: true,
+ branchName: "b",
+ commitMessage: "c",
+ prTitle: "p",
+ prBody: "pb",
+ };
+ const result = await commitAndPrTool.execute?.(
+ args,
+ executionOptions(createCommitAndPrContext()),
+ );
+
+ expect(result).toEqual({
+ success: false,
+ error: "Failed to commit: Commit failed Pre-commit hook failed",
+ });
+ });
+
+ test("should return error if git push fails", async () => {
+ mockSandbox.exec.mockImplementation(async (command: string) => {
+ if (command.startsWith("git push -u origin")) {
+ return {
+ success: false,
+ exitCode: 1,
+ stdout: "Push failed",
+ stderr: "Authentication required",
+ };
+ }
+ return { success: true, exitCode: 0, stdout: "", stderr: "" }; // Other commands succeed
+ });
+
+ const args = {
+ needsApproval: true,
+ branchName: "b",
+ commitMessage: "c",
+ prTitle: "p",
+ prBody: "pb",
+ };
+ const result = await commitAndPrTool.execute?.(
+ args,
+ executionOptions(createCommitAndPrContext()),
+ );
+
+ expect(result).toEqual({
+ success: false,
+ error: "Failed to push: Push failed Authentication required",
+ });
+ });
+
+ test("should report partial success if PR creation fails", async () => {
+ mockSandbox.exec.mockImplementation(async (command: string) => {
+ if (command.startsWith("gh pr create")) {
+ return {
+ success: false,
+ exitCode: 1,
+ stdout: "",
+ stderr: "PR creation failed: Missing required fields",
+ };
+ }
+ return { success: true, exitCode: 0, stdout: "", stderr: "" }; // Other commands succeed
+ });
+
+ const args = {
+ needsApproval: true,
+ branchName: "b",
+ commitMessage: "c",
+ prTitle: "p",
+ prBody: "pb",
+ };
+ const result = await commitAndPrTool.execute?.(
+ args,
+ executionOptions(createCommitAndPrContext()),
+ );
+
+ expect(result).toEqual({
+ success: true,
+ message:
+ "Successfully committed and pushed to branch b. Note: Could not create PR automatically via gh CLI. Please create it manually.",
+ errorDetails: "PR creation failed: Missing required fields",
+ });
+ });
+
+ test("needsApproval should always return true", async () => {
+ const args = {
+ needsApproval: true,
+ branchName: "feature/test-branch",
+ commitMessage: "feat: add new feature",
+ prTitle: "feat: Add new feature",
+ prBody: "This PR adds a new feature.",
+ };
+
+ const approvalResult = await getNeedsApprovalResult(
+ commitAndPrTool.needsApproval,
+ args,
+ createCommitAndPrContext(),
+ );
+
+ expect(approvalResult).toBe(true);
+ });
+ });
+
afterEach(() => {
sandboxRegistry.clear();
});
@@ -479,6 +720,10 @@ describe("tools execute behavior", () => {
},
};
+ mock.module("./utils", () => ({
+ getSandbox: mock(async () => sandbox),
+ }));
+
const context = createContext(sandbox);
const result = await webFetchTool.execute?.(
@@ -542,6 +787,10 @@ describe("tools execute behavior", () => {
"---\nname: review\ndescription: review code\n---\nRun review with $ARGUMENTS",
};
+ mock.module("./utils", () => ({
+ getSandbox: mock(async () => sandbox),
+ }));
+
const result = await skillTool.execute?.(
{ skill: "Review", args: "--quick" },
executionOptions({
@@ -675,3 +924,177 @@ describe("tools execute behavior", () => {
});
});
});
+
+test("askUserQuestionTool formats structured answers", () => {
+ const answerOutput = askUserQuestionTool.toModelOutput?.({
+ toolCallId: "tool-call-1",
+ input: { questions: [] },
+ output: {
+ answers: {
+ "Which package manager?": "bun",
+ "Which checks?": ["typecheck", "test"],
+ },
+ },
+ });
+
+ expect(answerOutput).toEqual({
+ type: "text",
+ value:
+ 'User has answered your questions: "Which package manager?"="bun", "Which checks?"="typecheck, test". You can now continue with the user\'s answers in mind.',
+ });
+
+ const declinedOutput = askUserQuestionTool.toModelOutput?.({
+ toolCallId: "tool-call-1",
+ input: { questions: [] },
+ output: { declined: true },
+ });
+
+ expect(declinedOutput).toEqual({
+ type: "text",
+ value:
+ "User declined to answer questions. You should continue without this information or ask in a different way.",
+ });
+});
+
+test("skillTool loads skill content and substitutes arguments", async () => {
+ const sandbox = {
+ workingDirectory: "/repo",
+ readFile: async () =>
+ "---\nname: review\ndescription: review code\n---\nRun review with $ARGUMENTS",
+ };
+
+ mock.module("./utils", () => ({
+ getSandbox: mock(async () => sandbox),
+ }));
+
+ const result = await skillTool.execute?.(
+ { skill: "Review", args: "--quick" },
+ executionOptions({
+ ...createContext(sandbox),
+ skills: [
+ {
+ name: "review",
+ description: "Review code changes",
+ path: "/repo/.skills/review",
+ filename: "SKILL.md",
+ options: {},
+ },
+ ],
+ }),
+ );
+
+ expect(result).toEqual({
+ success: true,
+ skillName: "Review",
+ skillPath: "/repo/.skills/review",
+ content: "Skill directory: /repo/.skills/review\n\nRun review with --quick",
+ });
+});
+
+test("skillTool returns helpful errors for missing or disabled skills", async () => {
+ const sandbox = {
+ workingDirectory: "/repo",
+ readFile: async () => "skill-body",
+ };
+
+ const missingResult = await skillTool.execute?.(
+ { skill: "unknown" },
+ executionOptions({ ...createContext(sandbox), skills: [] }),
+ );
+
+ expect(missingResult).toEqual({
+ success: false,
+ error: "Skill 'unknown' not found. Available skills: none",
+ });
+
+ const disabledResult = await skillTool.execute?.(
+ { skill: "commit" },
+ executionOptions({
+ ...createContext(sandbox),
+ skills: [
+ {
+ name: "commit",
+ description: "Create a commit",
+ path: "/repo/.skills/commit",
+ filename: "SKILL.md",
+ options: { disableModelInvocation: true },
+ },
+ ],
+ }),
+ );
+
+ expect(disabledResult).toEqual({
+ success: false,
+ error:
+ "Skill 'commit' cannot be invoked by the model (disable-model-invocation is set)",
+ });
+});
+
+test("taskTool exposes both subagent types without approval gates", async () => {
+ const explorerNeedsApproval = await getNeedsApprovalResult(
+ taskTool.needsApproval,
+ {
+ subagentType: "explorer",
+ task: "Find usages",
+ instructions: "Search for helper usage",
+ },
+ {
+ sandbox: { workingDirectory: "/repo" },
+ model: "test-model",
+ approval: {},
+ },
+ );
+ expect(explorerNeedsApproval).toBe(false);
+
+ const executorNeedsApproval = await getNeedsApprovalResult(
+ taskTool.needsApproval,
+ {
+ subagentType: "executor",
+ task: "Apply changes",
+ instructions: "Update files",
+ },
+ {
+ sandbox: { workingDirectory: "/repo" },
+ model: "test-model",
+ approval: {},
+ },
+ );
+ expect(executorNeedsApproval).toBe(false);
+});
+
+test("taskTool description lists subagents from the shared registry", () => {
+ expect(taskTool.description).toContain(
+ "`explorer` - Use for read-only codebase exploration, tracing behavior, and answering questions without changing files",
+ );
+ expect(taskTool.description).toContain(
+ "`executor` - Use for well-scoped implementation work, including edits, scaffolding, refactors, and other file changes",
+ );
+ expect(taskTool.description).toContain("up to 100 tool steps");
+});
+
+test("buildSystemPrompt lists subagents from the shared registry", () => {
+ const prompt = buildSystemPrompt({});
+
+ expect(prompt).toContain("Available subagents:");
+ expect(prompt).toContain(
+ "`explorer` - Use for read-only codebase exploration, tracing behavior, and answering questions without changing files",
+ );
+ expect(prompt).toContain(
+ "`executor` - Use for well-scoped implementation work, including edits, scaffolding, refactors, and other file changes",
+ );
+});
+
+test("todoWriteTool returns updated todo list metadata", async () => {
+ const todos = [
+ { id: "1", content: "Write tests", status: "in_progress" as const },
+ { id: "2", content: "Run checks", status: "pending" as const },
+ ];
+
+ const result = await todoWriteTool.execute?.({ todos }, executionOptions());
+
+ expect(result).toEqual({
+ success: true,
+ message: "Updated task list with 2 items",
+ todos,
+ });
+});
diff --git a/packages/mcp/context.ts b/packages/mcp/context.ts
new file mode 100644
index 00000000..fcae6d10
--- /dev/null
+++ b/packages/mcp/context.ts
@@ -0,0 +1,9 @@
+export const context7 = {
+ type: "remote" as const,
+ url: "https://mcp.context7.com/mcp",
+ enabled: true,
+ headers: process.env.CONTEXT7_API_KEY
+ ? { Authorization: `Bearer ${process.env.CONTEXT7_API_KEY}` }
+ : undefined,
+ oauth: false as const,
+};
diff --git a/packages/prompt/bot.ts b/packages/prompt/bot.ts
new file mode 100644
index 00000000..c23a1a3e
--- /dev/null
+++ b/packages/prompt/bot.ts
@@ -0,0 +1,131 @@
+import type { AgentConfigData, ThreadContext } from "../types";
+import type { AgentConfig } from "../router/schema";
+import {
+ applyAgentConfig,
+ applyComplexity,
+ applyTemporalContext,
+} from "./shared";
+
+export const BOT_SYSTEM_PROMPT = `You are a documentation assistant with bash access to a sandbox containing docs (markdown, JSON, YAML).
+{{TEMPORAL_CONTEXT}}
+
+## Critical Rule
+ALWAYS search AND read the relevant documentation before responding. NEVER just list files — actually read them and provide a concrete, actionable answer.
+
+## Fast Search Strategy
+
+ALWAYS prefer \`bash_batch\` over sequential \`bash\` calls. Combine search and read in the same batch.
+
+| Task | Command |
+|------|---------|
+| Find files by content | \`grep -rl "keyword" docs/ --include="*.md" | head -5\` |
+| Multi-keyword search | \`grep -rlE "term1|term2" docs/ --include="*.md" | head -5\` |
+| Find files by name | \`find docs/ -name "*routing*" -name "*.md"\` |
+| Read file (partial) | \`head -100 docs/path/file.md\` |
+| Read file (full) | \`cat docs/path/file.md\` |
+| Search with context | \`grep -n -C3 "keyword" docs/path/file.md\` |
+
+### Batch-first principle
+
+Use \`bash_batch\` to combine search AND read in a single call:
+\`\`\`
+bash_batch: [
+ "grep -rl \\"keyword\\" docs/source1/ --include=\\"*.md\\" | head -5",
+ "grep -rl \\"keyword\\" docs/source2/ --include=\\"*.md\\" | head -5",
+ "head -100 docs/source1/getting-started/index.md"
+]
+\`\`\`
+
+Use \`| head -N\` on all search output. Use \`grep -rlE "term1|term2"\` for multi-keyword search.
+1–2 batched calls beats 5 sequential ones.
+
+**ALWAYS provide a text answer.** If you run out of relevant search results, answer with what you have. Never end on a tool call without a final response.
+
+## Good vs Bad
+
+**Good** — 1-2 calls:
+1. \`bash_batch\`: grep across likely dirs + read obvious files in one call
+2. \`bash_batch\`: read remaining files from grep results
+
+**Bad** — 5+ calls:
+1. \`find docs/ -maxdepth 2 -type d\`
+2. \`grep -rl "keyword" docs/source1/\`
+3. \`grep -rl "keyword" docs/source2/\`
+4. \`cat docs/source1/file1.md\`
+5. \`cat docs/source2/file2.md\`
+
+## Web Search
+
+You have access to a \`search_web\` tool for finding information NOT in the sandbox.
+
+**Use search_web when:**
+- The sandbox search yields no relevant results
+- Questions about current events, release dates, or recent changes
+- Third-party libraries or services not covered in the sandbox
+
+**Do NOT use search_web when:**
+- The question is answerable from sandbox documentation (always search sandbox FIRST)
+
+**Priority:** sandbox docs (bash_batch) → web search → general knowledge
+
+## Response Style
+
+- Be concise and helpful
+- **Contextualize your answer to the user's question.** If they ask about a feature in a specific framework, show that framework's config — not the underlying library's config. Adapt code examples to the framework they're asking about.
+- When a topic spans multiple sources, **cross-reference both** — search the specific source AND related docs.
+- Include code examples from the documentation
+- Try to give a direct answer`;
+
+export function buildBotSystemPrompt(
+ context?: ThreadContext,
+ agentConfig?: AgentConfig,
+ savoirConfig?: AgentConfigData | null,
+): string {
+ let prompt: string = applyTemporalContext(BOT_SYSTEM_PROMPT);
+
+ if (savoirConfig) {
+ prompt = applyAgentConfig(prompt, savoirConfig);
+ }
+
+ if (agentConfig) {
+ prompt = applyComplexity(prompt, agentConfig);
+ }
+
+ if (context) {
+ const ref = context.number ? `#${context.number}` : "Thread";
+ prompt += `\n\n${ref}: "${context.title}" in ${context.source} (${context.platform})`;
+ }
+
+ return prompt;
+}
+
+export function buildBotUserMessage(
+ question: string,
+ context?: ThreadContext,
+): string {
+ const cleanQuestion = question.replace(/@[\w-]+(\[bot\])?/gi, "").trim();
+ const parts: string[] = [];
+
+ if (context) {
+ if (context.body) {
+ parts.push(`**Description:**\n${context.body.slice(0, 1000)}`);
+ }
+
+ if (context.previousComments?.length) {
+ const relevant = context.previousComments
+ .filter((c) => !c.isBot)
+ .slice(-2)
+ .map((c) => `@${c.author}: ${c.body.slice(0, 200)}`);
+
+ if (relevant.length) {
+ parts.push(`**Previous comments:**\n${relevant.join("\n")}`);
+ }
+ }
+ }
+
+ parts.push(
+ `**Question:**\n${cleanQuestion || context?.title || "How can I help?"}`,
+ );
+
+ return parts.join("\n\n");
+}
diff --git a/packages/sandbox/vercel/sandbox.ts b/packages/sandbox/vercel/sandbox.ts
index a3469286..c018ef0c 100644
--- a/packages/sandbox/vercel/sandbox.ts
+++ b/packages/sandbox/vercel/sandbox.ts
@@ -111,15 +111,22 @@ function buildAuthenticatedGitHubUrl(
repoUrl: string,
token: string,
): string | null {
+ // Match GitHub URL patterns to avoid REDOS vulnerability
+ // Matches: github.com/:owner/:repo or github.com/:owner/:repo.git
const githubUrlMatch = repoUrl.match(
- /github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?$/,
+ /^.*?github\.com[/:]([^/]+?)\/([^/]+?)(?:\.git)?$/,
);
-
if (!githubUrlMatch) {
return null;
}
const [, owner, repo] = githubUrlMatch;
+
+ // Validate that owner and repo are non-empty
+ if (!owner || !repo) {
+ return null;
+ }
+
return `https://x-access-token:${token}@github.com/${owner}/${repo}.git`;
}
diff --git a/renovate.json b/renovate.json
index cbc6661c..1ccd67a8 100644
--- a/renovate.json
+++ b/renovate.json
@@ -26,7 +26,12 @@
},
{
"description": "Group React and React DOM — must stay in sync",
- "matchPackageNames": ["react", "react-dom", "@types/react", "@types/react-dom"],
+ "matchPackageNames": [
+ "react",
+ "react-dom",
+ "@types/react",
+ "@types/react-dom"
+ ],
"groupName": "React",
"automerge": false
},
diff --git a/scripts/clean-workspace.sh b/scripts/clean-workspace.sh
new file mode 100755
index 00000000..80e8e28f
--- /dev/null
+++ b/scripts/clean-workspace.sh
@@ -0,0 +1,32 @@
+#!/bin/bash
+set -euo pipefail
+
+echo "🧹 Starting workspace cleanup to free up disk space..."
+
+# Go to project root (assuming script is in scripts/)
+cd "$(dirname "$0")/.." || { echo "❌ Failed to cd to repo root"; exit 1; }
+
+# Refuse to run outside a git checkout to avoid accidental wipes.
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+ echo "❌ Not inside a git working tree; aborting."
+ exit 1
+fi
+
+echo "🗑️ Removing all node_modules directories..."
+# find and remove all node_modules safely
+find . -name "node_modules" -type d -prune -exec rm -rf '{}' +
+
+echo "🗑️ Cleaning Bun cache (~/.bun/install/cache)..."
+if [ -d "$HOME/.bun/install/cache" ]; then
+ rm -rf "$HOME/.bun/install/cache"/*
+fi
+
+echo "🗑️ Cleaning npm cache..."
+npm cache clean --force 2>/dev/null
+
+echo "🗑️ Cleaning temporary turbo and Next.js build caches..."
+find . -name ".turbo" -type d -prune -exec rm -rf '{}' +
+find . -name ".next" -type d -prune -exec rm -rf '{}' +
+
+echo "✅ Cleanup complete! Disk space has been reclaimed."
+echo "💡 Remember to run 'bun install' when you come back to start coding again."