glitool 1.0.1 → 2.0.0

package/dist/agents/debugger.js

@@ -0,0 +1,111 @@
+import { makeLlm } from '../llm/factory.js';
+import { createReactAgent } from '@langchain/langgraph/prebuilt';
+import { SystemMessage, HumanMessage } from '@langchain/core/messages';
+import { listFilesTool, readFileTool, searchCodeTool, bashTool, editFileTool, } from '../tools/index.js';
+const DEBUG_SYSTEM_PROMPT = `You are a debugging agent. You investigate first, then patch.
+
+═══════════════════════════════════════════════════════
+DEFAULT BEHAVIOR — START INVESTIGATING.
+═══════════════════════════════════════════════════════
+
+For almost every prompt, you SHOULD:
+1. Run the failing command via bash, OR
+2. Read the file the user mentioned, OR
+3. Search the codebase for the symbol they mentioned.
+
+Do NOT ask the user for clarification before trying. A prompt like "npm test is failing", "fix the readFile bug", or "the auth flow throws on logout" is enough signal to begin. Run something concrete first, THEN decide if you need more info.
+
+═══════════════════════════════════════════════════════
+HARD STOPS — apply ONLY after you've started investigating.
+═══════════════════════════════════════════════════════
+
+After your investigation has begun, stop if ANY of these is true:
+
+1. After running the failing command, the output reveals the project is missing setup, not broken:
+   - \`npm test\` returns "Error: no test specified" (npm placeholder)
+   - The named tool/script doesn't exist at all
+   - The user is asking for a feature to be added, not a bug fixed
+   → Tell the user: "This isn't a debugger task — [specifics]. Use /coder to add it."
+   → DO NOT edit package.json, install dependencies, or scaffold new files.
+
+2. You called the same tool with the same arguments twice and got the same result.
+   → Stop. Report what you tried. Ask for more context.
+
+3. \`editFile\` returned an error twice in a row for the same file.
+   → Stop. The file content doesn't match your expectation. Read the file fresh with readFile, OR give up and report.
+
+4. You have used 10 tool calls. → Wrap up with what you have.
+
+5. You investigated for 3+ tool calls and STILL don't know what's failing.
+   → Now you can ask the user for a specific reproduction step. Not before.
+
+═══════════════════════════════════════════════════════
+
+Tool scope:
+- You can: readFile, listFiles, searchCode, bash, editFile
+- You CANNOT: create new files, install dependencies, modify package.json scripts
+- "Minimal patch" = the smallest change that makes the failing thing pass. Adding features is /coder's job. Restructuring code is /refactor's job.
+
+Workflow:
+
+1. REPRODUCE — run the failing command via bash (\`npm test\`, \`npx tsc --noEmit\`, etc.), OR readFile the file the user mentioned. Get concrete output.
+
+2. INVESTIGATE — use searchCode + readFile on the actual error symbols.
+
+3. DIAGNOSE — BEFORE editing anything, output:
+   ## Diagnosis
+   - **Root cause:** one sentence
+   - **Where:** file.ts:LINE
+   - **Why it fails:** short explanation
+
+4. PATCH — one minimal editFile.
+
+5. VERIFY — re-run the exact command from step 1.
+
+Final response format:
+
+## Diagnosis
+...
+
+## Fix
+- file.ts:LINE — what changed
+
+## Verification
+- ran: \`<command>\`
+- result: pass | fail (with details)
+`;
+export async function runDebugger(userMessage, onToolCall, model) {
+    const llm = makeLlm(model);
+    const tools = [
+        listFilesTool,
+        readFileTool,
+        searchCodeTool,
+        bashTool,
+        editFileTool,
+    ];
+    const agent = createReactAgent({
+        llm,
+        tools,
+        stateModifier: new SystemMessage(DEBUG_SYSTEM_PROMPT),
+    });
+    let finalText = '';
+    const stream = agent.streamEvents({ messages: [new HumanMessage(userMessage)] }, { version: 'v2', recursionLimit: 50 });
+    for await (const { event, data, name: eventName } of stream) {
+        if (event === 'on_tool_start') {
+            onToolCall(eventName, data.input);
+        }
+        if (event === 'on_chat_model_end') {
+            const output = data.output;
+            if (typeof output?.content === 'string') {
+                finalText = output.content;
+            }
+            else if (Array.isArray(output?.content)) {
+                finalText = output.content
+                    .filter((c) => c.type === 'text')
+                    .map((c) => c.text ?? '')
+                    .join('');
+            }
+        }
+    }
+    return finalText || 'Debugger produced no output.';
+}

package/dist/agents/explainer.js

@@ -1,9 +1,6 @@
-import { ChatOpenAI } from "@langchain/openai";
+import { makeLlm } from '../llm/factory.js';
 import { SystemMessage, HumanMessage } from "@langchain/core/messages";
-const explainerLlm = new ChatOpenAI({
-    model: 'gpt-4o-mini',
-    apiKey: process.env.OPENAI_API_KEY
-});
+const explainerLlm = makeLlm('meta-llama/Llama-3.3-70B-Instruct-Turbo');
 export async function explainResponse(response) {
     if (!response || response.length < 50)
         return '';

package/dist/agents/git-agent.js

@@ -0,0 +1,90 @@
+import { makeLlm } from '../llm/factory.js';
+import { createReactAgent } from '@langchain/langgraph/prebuilt';
+import { SystemMessage, HumanMessage } from '@langchain/core/messages';
+import { bashTool } from '../tools/index.js';
+const GIT_SYSTEM_PROMPT = `You are a git agent. Your ONLY tool is bash, and you may only use it for git operations.
+
+HARD STOP CONDITIONS:
+- One git command per piece of information you need. Don't re-run git status repeatedly.
+- If you've called bash with the same git command twice, STOP — report what you found.
+- Total tool calls per run: maximum 8.
+
+Strict rules:
+- You cannot read, write, edit, or search files directly. You have no file tools.
+- Every shell command you run must start with \`git\` (or be \`git\` piped through grep/head/tail/wc for filtering output).
+- If the user asks for anything that is not a git operation, refuse and tell them which agent to use:
+  - "what does this file do" → /explain
+  - "fix this bug"           → /debug
+  - "review my code"         → /review
+  - "add a feature"          → /coder
+
+Capabilities:
+- Status: \`git status\`, \`git log --oneline -n 20\`, \`git branch -vv\`
+- Diffs: \`git diff\`, \`git diff --staged\`, \`git diff main..HEAD\`
+- Stage / unstage: \`git add <files>\`, \`git restore --staged <files>\`
+- Commit: \`git commit -m "<message>"\` — only after the user agrees with the message
+- Push / pull / fetch (these will trigger a confirm prompt — that's fine)
+- Branching: \`git switch\`, \`git switch -c\`, \`git branch\`
+- Stash: \`git stash\`, \`git stash pop\`, \`git stash list\`
+- History: \`git show <ref>\`, \`git blame\`
+
+Workflow patterns:
+
+When the user asks to commit (any phrasing: "commit", "commit everything", "save my work", etc.):
+1. Run \`git status\` to see staged, unstaged, and untracked files.
+2. If there are unstaged or untracked files, run \`git add -A\` to stage everything — unless the user specified particular files, in which case stage only those.
+3. Run \`git diff --staged\` to see exactly what will be committed.
+4. Run \`git log --oneline -n 5\` to match the project's commit style.
+5. Compose a concise commit message — imperative mood, one-line subject, optional body.
+6. SHOW the message to the user and ask for confirmation. Do NOT commit silently.
+7. On user confirmation, run \`git commit -m "<message>"\`.
+
+When the user asks to push (any phrasing: "push", "push my changes", "push current state", etc.):
+1. Run \`git status\` to check for unstaged or uncommitted changes.
+2. If there are unstaged or untracked files → run \`git add -A\` to stage everything.
+3. Run \`git diff --staged\` to see what is staged.
+4. If there is anything staged → compose a commit message (imperative mood, one-line subject + optional body).
+   Show the message to the user and ask for confirmation. Do NOT commit silently.
+5. On confirmation → run \`git commit -m "<message>"\`.
+6. Run \`git remote -v\` to confirm a remote exists. If no remote is listed, stop and tell the user to provide a URL.
+7. Run \`git push\` — bashTool will surface the confirm gate.
+
+If there is nothing to commit (working tree clean) → skip steps 2–5 and go straight to step 6.
+
+When the user asks "what changed":
+1. Run \`git status\` first.
+2. Then \`git diff --stat\` for the summary.
+3. Show \`git diff\` only if they ask for details.
+
+Always quote ref names and file paths if they contain spaces.
+
+Response format: short and direct. Show the relevant command output, then a one-line summary. Don't narrate every step.`;
+export async function runGitAgent(userMessage, onToolCall, model) {
+    const llm = makeLlm(model);
+    const tools = [bashTool];
+    const agent = createReactAgent({
+        llm,
+        tools,
+        stateModifier: new SystemMessage(GIT_SYSTEM_PROMPT),
+    });
+    let finalText = '';
+    const stream = agent.streamEvents({ messages: [new HumanMessage(userMessage)] }, { version: 'v2', recursionLimit: 50 });
+    for await (const { event, data, name: eventName } of stream) {
+        if (event === 'on_tool_start') {
+            onToolCall(eventName, data.input);
+        }
+        if (event === 'on_chat_model_end') {
+            const output = data.output;
+            if (typeof output?.content === 'string') {
+                finalText = output.content;
+            }
+            else if (Array.isArray(output?.content)) {
+                finalText = output.content
+                    .filter((c) => c.type === 'text')
+                    .map((c) => c.text ?? '')
+                    .join('');
+            }
+        }
+    }
+    return finalText || 'Git agent produced no output.';
+}

package/dist/agents/graph.js

@@ -1,28 +1,219 @@
-import { runPlanner } from './planner.js';
-import { runCoder } from './coder.js';
-import { runReviewer } from './reviewer.js';
-const MAX_ITERATIONS = 1;
-export async function runAgentGraph(userMessage, systemPrompt, onToolCall, onStatus) {
-    onStatus('Planning...');
-    const plan = await runPlanner(userMessage, systemPrompt);
-    if (plan.trim() === 'SIMPLE') {
+import { Annotation, StateGraph, START, END, MemorySaver } from "@langchain/langgraph";
+import { runPlanner } from "./planner.js";
+import { runCoder } from "./coder.js";
+import { runJudge } from "./judge.js";
+import { runValidator, formatValidationErrors } from "./validator.js";
+import { buildTopology, formatTopologyAsPlan, topologySummary } from "./workflow.js";
+import { getModelForTier } from "../llm/router.js";
+import fg from 'fast-glob';
+const MAX_CODER_RETRY = 2;
+const MAX_JUDGE_ITERATIONS = 3;
+const GraphState = Annotation.Root({
+    userMessage: Annotation({ reducer: (_, b) => b }),
+    systemPrompt: Annotation({ reducer: (_, b) => b }),
+    decision: Annotation({ reducer: (_, b) => b }),
+    steps: Annotation({ reducer: (_, b) => b, default: () => null }),
+    topology: Annotation({ reducer: (_, b) => b, default: () => null }),
+    plan: Annotation({ reducer: (_, b) => b, default: () => '' }),
+    coderOutput: Annotation({ reducer: (_, b) => b, default: () => '' }),
+    validationResult: Annotation({ reducer: (_, b) => b, default: () => null }),
+    judgeResult: Annotation({ reducer: (_, b) => b, default: () => null }),
+    coderRetry: Annotation({ reducer: (_, b) => b, default: () => 0 }),
+    judgeLoop: Annotation({ reducer: (_, b) => b, default: () => 0 }),
+    lastFailurePoint: Annotation({ reducer: (_, b) => b, default: () => null }),
+    plannerHint: Annotation({ reducer: (_, b) => b, default: () => '' }),
+    finalOutput: Annotation({ reducer: (_, b) => b, default: () => null }),
+    trajectory: Annotation({ reducer: (_, b) => b, default: () => [] }),
+    escalated: Annotation({ reducer: (_, b) => b, default: () => false }),
+});
+function extractTarget(args) {
+    if (!args)
         return '';
+    const first = Object.values(args)[0];
+    if (typeof first === 'string') {
+        try {
+            const p = JSON.parse(first);
+            return p.command ?? p.filePath ?? p.pattern ?? p.query ?? first;
+        }
+        catch {
+            return first;
+        }
+    }
+    if (typeof first === 'object' && first !== null) {
+        return first.command ?? first.filePath ?? JSON.stringify(first).slice(0, 50);
+    }
+    return String(first ?? '');
+}
+export async function runAgentGraph(userMessage, systemPrompt, onToolCall, onStatus, decision, onStageEvent) {
+    const plannerModel = getModelForTier('complex');
+    const coderModel = decision.recommendedModel;
+    const judgeModel = getModelForTier('complex');
+    async function plannerNode(state) {
+        onStatus('Planning...');
+        onStageEvent?.({ type: 'stage_start', stage: 'planner' });
+        const files = await fg(['**/*.{ts,tsx,js,jsx}'], {
+            cwd: process.cwd(),
+            ignore: ['node_modules/**', 'dist/**', '.next/**', '.git/**', 'build/**'],
+            onlyFiles: true,
+            suppressErrors: true,
+        });
+        const fileTree = files.slice(0, 200).join('\n');
+        const groundedSystemPrompt = `${state.systemPrompt}\n\n=== Project file tree (use exact paths from this list when planning edits) ===\n${fileTree}`;
+        const prompt = state.plannerHint
+            ? `${state.userMessage}\n\nPrevious attempt failed. Fix hint: ${state.plannerHint}`
+            : state.userMessage;
+        const steps = await runPlanner(prompt, groundedSystemPrompt, plannerModel);
+        if (steps?.length) {
+            const planText = steps
+                .map((s) => `${s.id}. ${s.action} ${s.target} — ${s.why}`)
+                .join('\n');
+            onStageEvent?.({ type: 'reasoning', stage: 'planner', text: planText });
+        }
+        onStageEvent?.({ type: 'stage_done', stage: 'planner' });
+        return { steps, coderRetry: 0, plannerHint: '' };
     }
-    let coderOutPut = '';
-    let finalResponse = '';
-    let approved = false;
-    let iteration = 0;
-    while (!approved && iteration < MAX_ITERATIONS) {
-        onStatus(`Executing plan${iteration > 0 ? ' (fixing issues)' : ''}...`);
-        coderOutPut = await runCoder(plan, userMessage, onToolCall);
-        onStatus('Reviewing...');
-        const review = await runReviewer(plan, coderOutPut, userMessage);
-        approved = review.approved;
-        finalResponse = review.finalResponse;
-        if (!approved) {
-            onStatus(`Reviewer founder issues: ${review.feedback}`);
+    async function workflowNode(state) {
+        onStatus('Building execution plan...');
+        const topology = buildTopology(state.steps);
+        const plan = formatTopologyAsPlan(topology, state.steps);
+        onStatus(`Workflow: ${topologySummary(topology)}`);
+        return { topology, plan };
+    }
+    async function coderNode(state) {
+        onStatus(`Executing plan${state.coderRetry > 0 ? ' (fixing issues)' : ''}...`);
+        onStageEvent?.({ type: 'stage_start', stage: 'coder' });
+        const wrappedOnToolCall = (name, args) => {
+            onStageEvent?.({ type: 'tool', stage: 'coder', tool: name, target: extractTarget(args) });
+            onToolCall(name, args);
+        };
+        const coderOutput = await runCoder(state.plan, state.userMessage, wrappedOnToolCall, coderModel, (text) => onStageEvent?.({ type: 'reasoning', stage: 'coder', text }));
+        onStageEvent?.({ type: 'stage_done', stage: 'coder' });
+        return { coderOutput };
+    }
+    async function validatorNode(state) {
+        onStatus('Validating...');
+        onStageEvent?.({ type: 'stage_start', stage: 'validator' });
+        const validationResult = await runValidator();
+        const errCount = validationResult.tsc.errors.length + validationResult.eslint.errors.length;
+        const summary = validationResult.overallOk
+            ? 'No errors found.'
+            : `${errCount} error(s) found — will retry.`;
+        onStageEvent?.({ type: 'reasoning', stage: 'validator', text: summary });
+        onStageEvent?.({ type: 'stage_done', stage: 'validator' });
+        if (validationResult.overallOk)
+            return { validationResult };
+        const newRetry = state.coderRetry + 1;
+        if (newRetry >= MAX_CODER_RETRY) {
+            return { validationResult, coderRetry: newRetry };
+        }
+        const feedback = formatValidationErrors(validationResult);
+        onStatus(`Validation failed - retry ${newRetry}`);
+        return {
+            validationResult,
+            coderRetry: newRetry,
+            plan: `${state.plan}\n\nFix these issues:\n${feedback}`,
+        };
+    }
+    async function judgeNode(state) {
+        onStatus('Judging...');
+        onStageEvent?.({ type: 'stage_start', stage: 'judge' });
+        const judgment = await runJudge({
+            userMessage: state.userMessage,
+            plan: state.plan,
+            steps: state.steps,
+            topology: state.topology,
+            coderOutput: state.coderOutput,
+            validationResult: state.validationResult,
+            loopCount: state.judgeLoop,
+        }, judgeModel);
+        const verdictText = judgment.verdict === 'ok'
+            ? `All tasks complete. ${judgment.reason}`
+            : `Issue: ${judgment.reason}`;
+        onStageEvent?.({ type: 'reasoning', stage: 'judge', text: verdictText });
+        onStageEvent?.({ type: 'stage_done', stage: 'judge' });
+        const newJudgeLoop = state.judgeLoop + 1;
+        const repeated = judgment.failure_point === state.lastFailurePoint;
+        const escalate = newJudgeLoop >= MAX_JUDGE_ITERATIONS || repeated;
+        const newTrajectory = [
+            ...state.trajectory,
+            {
+                iteration: newJudgeLoop,
+                verdict: judgment.verdict,
+                failure_point: judgment.failure_point,
+                reason: judgment.reason,
+                fix_hint: judgment.fix_hint,
+            },
+        ];
+        if (judgment.verdict === 'ok' || escalate) {
+            const didEscalate = escalate && judgment.verdict !== 'ok';
+            if (didEscalate) {
+                onStatus(`Escalating after ${newJudgeLoop} attempts: ${judgment.reason}`);
+            }
+            return {
+                judgeResult: judgment,
+                finalOutput: judgment.finalResponse || state.coderOutput,
+                judgeLoop: newJudgeLoop,
+                trajectory: newTrajectory,
+                escalated: didEscalate,
+            };
+        }
+        onStatus(`Judge: ${judgment.failure_point} - ${judgment.reason}`);
+        if (judgment.failure_point === 'plan') {
+            return {
+                judgeResult: judgment,
+                judgeLoop: newJudgeLoop,
+                lastFailurePoint: judgment.failure_point,
+                plannerHint: judgment.fix_hint,
+                steps: null,
+                plan: '',
+                coderRetry: 0,
+                trajectory: newTrajectory,
+            };
         }
-        iteration++;
+        return {
+            judgeResult: judgment,
+            judgeLoop: newJudgeLoop,
+            lastFailurePoint: judgment.failure_point,
+            plan: `${state.plan}\n\nJudge feedback (attempt ${state.judgeLoop + 1}): ${judgment.fix_hint}`,
+            coderRetry: 0,
+            trajectory: newTrajectory,
+        };
     }
-    return finalResponse || coderOutPut;
+    const routeAfterPlanner = (state) => state.steps === null ? END : 'workflow';
+    const routeAfterValidator = (state) => {
+        if (state.validationResult?.overallOk)
+            return 'judge';
+        if (state.coderRetry >= MAX_CODER_RETRY)
+            return 'judge';
+        return 'coder';
+    };
+    const routeAfterJudge = (state) => {
+        if (state.finalOutput !== null)
+            return END;
+        if (state.judgeResult?.failure_point === 'plan')
+            return 'planner';
+        return 'coder';
+    };
+    const app = new StateGraph(GraphState)
+        .addNode('planner', plannerNode)
+        .addNode('workflow', workflowNode)
+        .addNode('coder', coderNode)
+        .addNode('validator', validatorNode)
+        .addNode('judge', judgeNode)
+        .addEdge(START, 'planner')
+        .addConditionalEdges('planner', routeAfterPlanner)
+        .addEdge('workflow', 'coder')
+        .addEdge('coder', 'validator')
+        .addConditionalEdges('validator', routeAfterValidator)
+        .addConditionalEdges('judge', routeAfterJudge)
+        .compile({ checkpointer: new MemorySaver() });
+    const threadId = `graph-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+    const result = await app.invoke({ userMessage, systemPrompt, decision }, { configurable: { thread_id: threadId }, recursionLimit: 50 });
+    return {
+        finalOutput: result.finalOutput ?? null,
+        escalated: result.escalated ?? false,
+        trajectory: result.trajectory ?? [],
+        userMessage: result.userMessage,
+        plan: result.plan,
+    };
 }

package/dist/agents/judge.js

@@ -0,0 +1,61 @@
+import { makeLlm } from '../llm/factory.js';
+import { SystemMessage, HumanMessage } from "@langchain/core/messages";
+export async function runJudge(input, model) {
+    const llm = makeLlm(model);
+    const outputSummary = input.coderOutput.length > 500 ? input.coderOutput.slice(0, 500) + '... (truncated)' : input.coderOutput;
+    const tsc = input.validationResult.tsc;
+    const validationSummary = input.validationResult.overallOk
+        ? `All checks passed.${tsc.ran ? ' TypeScript compiled successfully.' : ' (no tsconfig found — skipped)'}`
+        : [
+            !tsc.ok && tsc.ran ? `TS errors: ${tsc.errors.slice(0, 3).join(' | ')}` : '',
+            !input.validationResult.eslint.ok ? `lint errors: ${input.validationResult.eslint.errors.slice(0, 3).join(' | ')}` : '',
+        ].filter(Boolean).join(', ');
+    const response = await llm.invoke([
+        new SystemMessage(`You are a code quality judge for an AI coding agent. Evaluate whether the coder fulfilled the user's request.
+
+IMPORTANT — how the coder works:
+- The coder writes files using tools (writeFile, editFile). It does NOT print file contents in its response.
+- "What the coder did" is a short text summary — the actual code is on disk, not in this text.
+- If validation ran and passed (TypeScript compiled successfully), the files exist and are correct. Trust this.
+- Only fail if: validation found real errors, OR the coder explicitly said it could not complete a step.
+- Do NOT fail because the coder's text response did not show file contents. That is correct behaviour.
+
+Return JSON only:
+{
+  "verdict": "ok" or "fail",
+  "failure_point": "plan" | "workflow" | "executor" | "final_output" | null,
+  "failure_step_id": number or null,
+  "reason": "short explanation",
+  "fix_hint": "specific instruction to fix the problem, empty if ok",
+  "confidence": 0.0 to 1.0,
+  "finalResponse": "message to show the user — summarize what was done or what went wrong"
+}
+
+failure_point meanings:
+- "plan": the plan itself was wrong or incomplete — needs replanning
+- "workflow": wrong execution order caused the failure
+- "executor": a specific step failed — use failure_step_id
+- "final_output": code runs but doesn't meet the requirement
+- null: everything ok, verdict must be ok`),
+        new HumanMessage(`User request: ${input.userMessage}\n\n` +
+            `Plan:\n${input.plan}\n\n` +
+            `What the coder did:\n${outputSummary}\n\n` +
+            `Validation: ${validationSummary}\n\n` +
+            `Attempt: ${input.loopCount + 1}`)
+    ]);
+    try {
+        const cleaned = response.content.replace(/```json|```/g, '').trim();
+        return JSON.parse(cleaned);
+    }
+    catch {
+        return {
+            verdict: 'ok',
+            failure_point: null,
+            failure_step_id: null,
+            reason: '',
+            fix_hint: '',
+            confidence: 0.5,
+            finalResponse: input.coderOutput,
+        };
+    }
+}

package/dist/agents/planner.js

@@ -1,20 +1,39 @@
-import { ChatOpenAI } from "@langchain/openai";
+import { makeLlm } from '../llm/factory.js';
 import { SystemMessage, HumanMessage } from "@langchain/core/messages";
-const plannerLlm = new ChatOpenAI({
-    model: 'gpt-5.4',
-    apiKey: process.env.OPENAI_API_KEY
-});
-export async function runPlanner(userMessage, context) {
-    const response = await plannerLlm.invoke([
-        new SystemMessage(`You are a coding task planner. Given a user request, output a clear numbered plan.
+export async function runPlanner(userMessage, context, model) {
+    const llm = makeLlm(model);
+    const response = await llm.invoke([
+        new SystemMessage(`You are a coding task planner. Output a structured JSON plan.
+
 Rules:
+- If the task is ONLY a question or explanation with NO file creation or code execution needed, output exactly: SIMPLE
+- Otherwise output a JSON array of steps with this shape:
+  [{ "id": 1, "action": "read|edit|create|run|search", "target": "file/path or command", "depends_on": [], "why": "reason" }]
 - Be specific about which files to read, edit, or create
 - Do NOT write any code — only plan the steps
 - Keep it to 3-6 steps maximum
-- If the task is ONLY a question or explanation with NO file creation or code execution needed, output exactly: SIMPLE
-- Any task that requires creating, editing, or writing files must NEVER be SIMPLE
-`),
+- Steps that can run independently should have no shared depends_on
+- depends_on contains the ids of steps that must finish before this one`),
         new HumanMessage(`Context:\n${context}\n\nUser request: ${userMessage}`)
     ]);
-    return response.content;
+    const content = response.content.trim();
+    if (content === 'SIMPLE')
+        return null;
+    try {
+        const cleaned = content.replace(/```json|```/g, '').trim();
+        const steps = JSON.parse(cleaned);
+        if (Array.isArray(steps) && steps.length > 0)
+            return steps;
+        throw new Error('empty array');
+    }
+    catch {
+        // Fallback — treat the whole response as a single unstructured step
+        return [{
+                id: 1,
+                action: 'edit',
+                target: 'project',
+                depends_on: [],
+                why: content,
+            }];
+    }
 }

package/dist/agents/planningAgent.js

@@ -0,0 +1,41 @@
+import { makeLlm } from '../llm/factory.js';
+import { SystemMessage, HumanMessage } from "@langchain/core/messages";
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+const PLAN_FILE = "plan.md";
+const BLOCKED_EXTENSIONS = ['.ts', '.js', '.tsx', '.jsx', '.py', '.go', '.rs'];
+export async function runPlanningAgent(userMessage, onUsage) {
+    const llm = makeLlm('deepseek-ai/DeepSeek-V3');
+    const planPath = join(process.cwd(), PLAN_FILE);
+    const existingPlan = existsSync(planPath) ? readFileSync(planPath, 'utf-8') : null;
+    const systemPrompt = existingPlan ? `...existing logic...` : `You are a planning assistant. Create a clear structured plan based on user's request.
+
+BEFORE writing a plan:
+- Look at the user's request and identify the key feature names, file paths, or concepts mentioned.
+- If the request mentions specific files (e.g. "graph.ts", "EscalationCard"), ASSUME those already exist and may already implement what's described.
+- If the request describes a feature without a clear "build me X" verb (no "design", "create", "implement", "plan"), assume the user is asking for ANALYSIS of an existing thing, not net-new work.
+
+In your plan, do NOT invent assumptions. If you don't know something, write "QUESTION: ..." and ask the user.
+
+Rules:
+- Use Markdown with clear sections and numbered steps
+- Be specific: name files, components, decisions, trade-offs
+- If the request is vague, prefer asking 1-2 clarifying questions over guessing
+- After the plan, write exactly "---" on its own line, then 1-3 bullet points summarising what you created
+`;
+    const userContent = existingPlan ? `Current plan:\n\n${existingPlan}\n\nUser request:${userMessage}` : userMessage;
+    const response = await llm.invoke([
+        new SystemMessage(systemPrompt),
+        new HumanMessage(userContent)
+    ]);
+    const usage = response.usage_metadata;
+    if (usage)
+        onUsage?.(usage.input_tokens ?? 0, usage.output_tokens ?? 0);
+    const content = response.content;
+    const splitIndex = content.lastIndexOf('\n---\n');
+    const planBody = splitIndex !== -1 ? content.slice(0, splitIndex).trim() : content.trim();
+    const changeSummary = splitIndex !== -1 ? content.slice(splitIndex + 5).trim() : 'Plan saved.';
+    writeFileSync(planPath, planBody, 'utf-8');
+    const action = existingPlan ? 'updated' : 'created';
+    return `**plan.md ${action}**\n\n${changeSummary}`;
+}