astrabot 0.1.0

package/modes/plan/orchestrator.ts

@@ -0,0 +1,198 @@
+import { text, isCancel, confirm } from "@clack/prompts";
+import chalk from "chalk";
+import { generatePlan } from "./planner";
+import { printPlan, selectSteps } from "./selection";
+import { defaultAgentConfig } from "../agent/types";
+import { ActionTracker } from "../agent/action-tracker";
+import { ToolExecutor } from "../agent/tool-executor";
+import { createAgentTools } from "../agent/agent-tools";
+import { stepCountIs, ToolLoopAgent } from "ai";
+import { getAgentModel } from "../../ai";
+import type { PlanStep } from "./types";
+import { renderTerminalMarkdown } from "../../tui/terminal-md";
+import { runApprovalFlow } from "../agent/approval";
+import { createWebTools } from "./web-tools";
+import { withSpinner } from "../../tui/spinner";
+import { beginSession, endSession, markSessionInterrupted } from "../../session";
+import { createSessionTools } from "../../session/session-tools";
+import { promptToRetryAiCall } from "../../ai/retry-prompt";
+
+function stepPrompt(goal: string, step: PlanStep): string {
+    return [`Goal: ${goal}`, `Step: ${step.title}`, step.description].join("\n");
+}
+
+export async function runPlanMode(preCapturedGoal?: string): Promise<void> {
+    console.log(chalk.bold("\nPlan Mode\n"));
+
+    const goal = preCapturedGoal ?? await text({
+        message: "What would you like the agent to do for you?",
+        placeholder: "Concrete task for this codebase...",
+    });
+
+    if (isCancel(goal) || !goal.trim()) return;
+
+    const config = defaultAgentConfig();
+    const tracker = new ActionTracker();
+    const executor = new ToolExecutor(tracker, config);
+
+    const approveCreatedFile = async (filePath: string): Promise<string> => {
+        const ok = await runApprovalFlow(tracker, {
+            paths: [filePath],
+            skipBatchPrompt: true,
+        });
+
+        if (!ok) {
+            executor.discardStagedPath(filePath);
+            return `User rejected creating ${filePath}. Do not modify or rely on this file unless you recreate it later.`;
+        }
+
+        const { errors } = executor.applyApprovedFromTracker();
+        if (errors.length) {
+            executor.discardStagedPath(filePath);
+            throw new Error(
+                `Failed to apply approved file ${filePath}: ${errors.join("; ")}`,
+            );
+        }
+
+        return `Created and applied ${filePath} after user approval.`;
+    };
+
+    const { entry: sessionEntry } = beginSession({
+        workspacePath: config.codebasePath,
+        mode: "plan",
+        goal: goal.trim(),
+    });
+
+    let plan;
+    while (true) {
+        try {
+            plan = await generatePlan(goal);
+            break;
+        } catch (error) {
+            const retry = await promptToRetryAiCall(
+                "Plan generation hit a provider error.",
+                error,
+            );
+            if (retry) continue;
+            markSessionInterrupted(sessionEntry.id);
+            await endSession(sessionEntry.id, tracker, "Stopped while generating a plan.");
+            executor.discardChanges();
+            return;
+        }
+    }
+
+    printPlan(plan);
+
+    const selected = await selectSteps(plan);
+    if (selected.length === 0) return;
+
+    const proceed = await confirm({
+        message: `Execute ${selected.length} step(s)`,
+        initialValue: true,
+    });
+
+    if (isCancel(proceed) || !proceed) return;
+
+    const tools = {
+        ...createAgentTools(executor, {
+            afterCreateFile: approveCreatedFile,
+        }),
+        ...createWebTools(tracker),
+        ...createSessionTools(config.codebasePath),
+    };
+
+    let lastResponse = "";
+    for (const step of selected) {
+        console.log(chalk.bold(`\nStep: ${step.title}\n`));
+
+        const agent = new ToolLoopAgent({
+            model: getAgentModel(),
+            stopWhen: stepCountIs(50),
+            tools,
+        });
+
+        while (true) {
+            try {
+                const r = await withSpinner(
+                    {
+                        message: `Executing: ${step.title}`,
+                        doneMessage: "done",
+                        failMessage: "failed",
+                    },
+                    () =>
+                        agent.generate({
+                            prompt: stepPrompt(plan.goal, step),
+                            onStepFinish: ({ toolCalls }) => {
+                                for (const tc of toolCalls) {
+                                    const preview = JSON.stringify(tc.input).slice(0, 160);
+                                    console.log(
+                                        chalk.green("  *"),
+                                        chalk.bold(String(tc.toolName)),
+                                        chalk.dim(
+                                            preview + (preview.length > 160 ? "..." : ""),
+                                        ),
+                                    );
+                                }
+                            },
+                        }),
+                );
+
+                if (r.text.trim()) {
+                    console.log(renderTerminalMarkdown(r.text));
+                    lastResponse = r.text.trim();
+                }
+                break;
+            } catch (error) {
+                const retry = await promptToRetryAiCall(
+                    `Step "${step.title}" hit a provider error.`,
+                    error,
+                );
+                if (retry) continue;
+                markSessionInterrupted(sessionEntry.id);
+                await endSession(
+                    sessionEntry.id,
+                    tracker,
+                    `Stopped during step: ${step.title}`,
+                );
+                executor.discardChanges();
+                return;
+            }
+        }
+    }
+
+    const ok = await runApprovalFlow(tracker);
+
+    if (!ok) {
+        await endSession(
+            sessionEntry.id,
+            tracker,
+            lastResponse || "Plan execution cancelled",
+        );
+        executor.discardChanges();
+        return;
+    }
+
+    await withSpinner(
+        {
+            message: "Applying approved changes...",
+            doneMessage: "all changes applied",
+            failMessage: "some operations failed",
+        },
+        async () => {
+            const { errors } = executor.applyApprovedFromTracker();
+            if (errors.length) {
+                console.log(chalk.red("\nSome operations reported errors:\n"));
+                for (const e of errors) console.log(chalk.red(`  - ${e}`));
+            } else {
+                console.log(chalk.green("\nApplied.\n"));
+            }
+        },
+    );
+
+    await endSession(
+        sessionEntry.id,
+        tracker,
+        lastResponse || "Plan executed with " + selected.length + " step(s).",
+    );
+    executor.discardChanges();
+}

package/modes/plan/planner.ts

@@ -0,0 +1,121 @@
+import {
+  Output,
+  generateText,
+  stepCountIs,
+} from "ai";
+import z from "zod";
+import { getAgentModel } from "../../ai";
+import { ActionTracker } from "../agent/action-tracker";
+import { ToolExecutor } from "../agent/tool-executor";
+import { createAgentTools } from "../agent/agent-tools";
+import { defaultAgentConfig } from "../agent/types";
+import type { Plan, PlanStep } from "./types";
+import { createWebTools } from "./web-tools";
+import { withSpinner } from "../../tui/spinner";
+import { getEnv } from "../../ai/config-loader";
+
+const planSchema = z.object({
+  researchSummary: z.string().optional(),
+  steps: z
+    .array(
+      z.object({
+        title: z.string(),
+        description: z.string(),
+        hints: z.array(z.string()).optional(),
+        complexity: z.enum(["low", "medium", "high"]).optional(),
+      }),
+    )
+    .min(1)
+    .max(20),
+});
+
+/**
+ * Read-only subset of agent tools for the planner.
+ * Strips all mutation, shell, staging, and executor web tools
+ * (web is provided by createWebTools when FIRECRAWL_API_KEY is set).
+ */
+function createPlannerTools(executor: ToolExecutor) {
+  const all = createAgentTools(executor);
+  const {
+    create_file: _cf,
+    modify_file: _mf,
+    delete_file: _df,
+    create_folder: _cfo,
+    replace_in_file: _rif,
+    append_to_file: _atf,
+    insert_at_line: _ial,
+    run_command: _rc,
+    run_background_command: _rbc,
+    execute_shell: _es,
+    discard_changes: _dc,
+    show_pending_changes: _spc,
+    run_tests: _rt,
+    run_test_file: _rtf,
+    lint_project: _lp,
+    format_project: _fp,
+    create_plan: _cp,
+    get_plan: _gp,
+    // strip executor's curl-based web tools — superseded by createWebTools (Firecrawl)
+    web_search: _ws,
+    fetch_url: _fu,
+    ...readOnly
+  } = all;
+  return readOnly;
+}
+
+const PLAN_INSTRUCTIONS = (
+  codebase: string,
+  hasWeb: boolean,
+): string => [
+  "You are Astra, an AI-native development CLI companion tool built to help the user navigate, analyze, and build within their workspace codebase. If the user asks who you are, what your name is, or what model you are running on, you must always identify yourself exclusively as Astra. Do not mention your underlying model architecture or provider.",
+  "You are a Plan-Mode planner. You DO NOT modify files.",
+  `Workspace: ${codebase}`,
+  "Use read-only tools for codebase/skills research.",
+  hasWeb
+    ? "Web tools are available (web_search/web_crawl/fetch_url). Use only when needed."
+    : "Web tools are unavailable.",
+  "Output must match the provided JSON schema.",
+  "Keep it short: 1-20 steps.",
+].join("\n");
+
+export async function generatePlan(goal: string) {
+  const config = defaultAgentConfig();
+  const tracker = new ActionTracker();
+  const executor = new ToolExecutor(tracker, config);
+
+  const hasWeb = !!getEnv("FIRECRAWL_API_KEY");
+
+  const tools = {
+    ...createPlannerTools(executor),
+    ...(hasWeb ? createWebTools(tracker) : {}),
+  };
+
+  const result = await withSpinner(
+    {
+      message: "Researching & drafting plan…",
+      doneMessage: "plan ready",
+      failMessage: "planning failed",
+    },
+    () =>
+      generateText({
+        model: getAgentModel(),
+        tools,
+        stopWhen: stepCountIs(30),
+        system: PLAN_INSTRUCTIONS(config.codebasePath, hasWeb),
+        prompt: `User goal: \n${goal}`,
+        output: Output.object({ schema: planSchema }),
+      }),
+  );
+
+  const validated = planSchema.parse(result.output);
+
+  const steps: PlanStep[] = validated.steps.map((s, i) => ({
+    id: `step-${i + 1}`,
+    title: s.title,
+    description: s.description,
+    hints: s.hints,
+    complexity: s.complexity,
+  }));
+
+  return { goal, researchSummary: validated.researchSummary, steps };
+}

package/modes/plan/selection.ts

@@ -0,0 +1,43 @@
+import chalk from "chalk";
+import { renderTerminalMarkdown } from "../../tui/terminal-md";
+import type { Plan, PlanStep } from "./types";
+import { isCancel, multiselect } from "@clack/prompts";
+
+const COMPLEXITY_COLOR: Record<NonNullable<PlanStep['complexity']>, string> = {
+  low: chalk.green('low'),
+  medium: chalk.yellow('medium'),
+  high: chalk.red('high'),
+};
+
+
+export function printPlan(plan: Plan): void {
+  if (plan.researchSummary?.trim()) {
+    console.log(chalk.bold('\n🔍 Research summary'));
+    console.log(renderTerminalMarkdown(plan.researchSummary));
+  }
+  console.log(chalk.bold('\n📋 Generated Plan\n'));
+  for (const [i, s] of plan.steps.entries()) {
+    const tag = s.complexity ? `[${COMPLEXITY_COLOR[s.complexity]}]` : '';
+    console.log(`  ${chalk.cyan(`Step ${String(i + 1).padStart(2)}`)}. ${chalk.bold(s.title)} ${tag}`);
+  }
+  console.log();
+}
+
+export async function selectSteps(plan: Plan): Promise<PlanStep[]> {
+  const options = plan.steps.map((s) => ({
+    value: s.id,
+    label: s.title,
+    hint: s.complexity ?? '',
+  }));
+
+  const picked = await multiselect<string>({
+    message: 'Select steps to execute (space toggles, enter confirms)',
+    options,
+    initialValues: plan.steps.map((s) => s.id),
+    required: false,
+  });
+
+  if (isCancel(picked)) return [];
+  const set = new Set<string>(picked);
+  return plan.steps.filter((s) => set.has(s.id));
+}

package/modes/plan/types.ts

@@ -0,0 +1,13 @@
+export interface PlanStep{
+    id: string,
+    title: string,
+    description: string,
+    hints?: string[],
+    complexity?: 'low' | 'medium' | 'high'
+}
+
+export interface Plan{
+    goal: string,
+    researchSummary?: string,
+    steps: PlanStep[]
+}

package/modes/plan/web-tools.ts

@@ -0,0 +1,132 @@
+import { tool } from "ai";
+import { z } from "zod";
+import Firecrawl from "@mendable/firecrawl-js";
+import type { ActionTracker } from "../agent/action-tracker";
+import { withSpinner } from "../../tui/spinner";
+import { getEnv } from "../../ai/config-loader";
+
+let client: Firecrawl | null = null;
+
+function getClient(): Firecrawl {
+  if (client) return client;
+  const apiKey = getEnv("FIRECRAWL_API_KEY");
+  if (!apiKey) {
+    throw new Error("FIRECRAWL_API_KEY is not set");
+  }
+  client = new Firecrawl({ apiKey });
+  return client;
+}
+
+function clip(s: string, n = 8000): string {
+  return s.length > n ? s.slice(0, n) + "\n...[truncated]" : s;
+}
+
+export function createWebTools(tracker: ActionTracker) {
+  return {
+    web_search: tool({
+      description: "Search the web. Returns title/url/snippet list.",
+      inputSchema: z.object({
+        query: z.string().min(1),
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(10)
+          .optional()
+          .default(5),
+      }),
+      execute: async ({ query, limit }) => {
+        const short =
+          query.length > 50 ? query.slice(0, 50) + "…" : query;
+        const res = await withSpinner(
+          {
+            message: `Searching the web for "${short}"…`,
+            doneMessage: "results received",
+            failMessage: "search failed",
+          },
+          () =>
+            getClient().search(query, {
+              limit,
+              sources: ["web"],
+            }),
+        );
+
+        const items = (res.web ?? []).slice(0, limit);
+
+        const out = items
+          .map((d, i) => {
+            const title =
+              "title" in d && d.title ? d.title : "(untitled)";
+            const url = "url" in d && d.url ? d.url : "";
+            const snip = "snippet" in d && d.snippet ? d.snippet : "";
+            return `${i + 1}. ${title}\n   ${url}\n   ${snip}`;
+          })
+          .join("\n\n") || "(no result found)";
+
+        tracker.log({
+          type: "code_analysis",
+          path: `web_search:${query}`,
+          details: { after: out, toolName: "web_search" },
+          status: "executed",
+        });
+
+        return clip(out);
+      },
+    }),
+
+    web_crawl: tool({
+      description: "Scrape a URL into markdown text.",
+      inputSchema: z.object({ url: z.string().url() }),
+      execute: async ({ url }) => {
+        const short =
+          url.length > 60 ? url.slice(0, 60) + "…" : url;
+        const doc = await withSpinner(
+          {
+            message: `Crawling ${short}…`,
+            doneMessage: "page scraped",
+            failMessage: "crawl failed",
+          },
+          () =>
+            getClient().scrape(url, { formats: ["markdown"] }),
+        );
+        const md = (doc as { markdown?: string }).markdown ?? "";
+        tracker.log({
+          type: "code_analysis",
+          path: `web_crawl:${url}`,
+          details: { after: clip(md), toolName: "web_crawl" },
+          status: "executed",
+        });
+        return clip(md) || "(empty)";
+      },
+    }),
+
+    fetch_url: tool({
+      description: "HTTP GET for a URL. Returns response body.",
+      inputSchema: z.object({ url: z.string().url() }),
+      execute: async ({ url }) => {
+        const short =
+          url.length > 60 ? url.slice(0, 60) + "…" : url;
+        const r = await withSpinner(
+          {
+            message: `Fetching ${short}…`,
+            doneMessage: "response received",
+            failMessage: "fetch failed",
+          },
+          () => fetch(url, { redirect: "follow" }),
+        );
+        const body = await r.text();
+        const out = clip(body, 16_000);
+        tracker.log({
+          type: "code_analysis",
+          path: `fetch:${url}`,
+          details: {
+            after: `HTTP ${r.status}\n\n${out}`,
+            toolName: "fetch_url",
+          },
+          status: "executed",
+        });
+        return `HTTP ${r.status}\n\n${out}`;
+      },
+    }),
+  };
+}