godspeed-agent 0.1.0

package/src/lib/agent.ts

@@ -0,0 +1,183 @@
+import { askLLMWithMessages, type ChatMessage } from "./llm.js";
+import { executeTool, type ToolAction } from "../tools/registry.js";
+import { buildSystemPrompt } from "../tools/prompt.js";
+import ora from "ora";
+
+type AgentAction = { action: "FINAL"; answer: string } | ToolAction;
+
+export type AgentStep = {
+  step: number;
+  action: string;
+  path?: string;
+  command?: string;
+  pattern?: string;
+  query?: string;
+  from?: string;
+  to?: string;
+  status: "started" | "completed" | "failed";
+  error?: string;
+};
+
+export type RunAgentOptions = {
+  onStep?: (step: AgentStep) => void;
+  showSpinner?: boolean;
+  confirmTool?: (action: ToolAction) => Promise<boolean>;
+  memory?: string;
+};
+
+function extractJson(text: string): AgentAction {
+  const fencedJsonMatch = text.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+
+  if (fencedJsonMatch?.[1]) {
+    return JSON.parse(fencedJsonMatch[1]);
+  }
+
+  const firstBrace = text.indexOf("{");
+  const lastBrace = text.lastIndexOf("}");
+
+  if (firstBrace !== -1 && lastBrace !== -1) {
+    const jsonCandidate = text.slice(firstBrace, lastBrace + 1);
+    return JSON.parse(jsonCandidate);
+  }
+
+  return JSON.parse(text);
+}
+
+const systemPrompt = buildSystemPrompt();
+
+export async function runAgent(prompt: string, options: RunAgentOptions = {}) {
+  const messages: ChatMessage[] = [
+    {
+      role: "user",
+      text: `${systemPrompt}
+
+      Previous summarized context:
+      ${options.memory || "No previous context."}
+
+      User request:
+      ${prompt}`,
+    },
+  ];
+
+  const maxSteps = 10;
+  const showSpinner = options.showSpinner ?? false;
+
+  for (let step = 0; step < maxSteps; step++) {
+    const raw = await askLLMWithMessages(messages);
+
+    let action: AgentAction;
+
+    try {
+      action = extractJson(raw);
+    } catch {
+      messages.push({
+        role: "user",
+        text: `
+You did not return valid JSON.
+
+Return ONLY valid JSON.
+Do not include explanations.
+Do not include markdown.
+`,
+      });
+
+      continue;
+    }
+
+    const stepInfo = {
+      step: step + 1,
+      action: action.action,
+      path: "path" in action ? action.path : undefined,
+      command: "command" in action ? action.command : undefined,
+      pattern: "pattern" in action ? action.pattern : undefined,
+      query: "query" in action ? action.query : undefined,
+      from: "from" in action ? action.from : undefined,
+      to: "to" in action ? action.to : undefined,
+    };
+
+    messages.push({
+      role: "model",
+      text: JSON.stringify(action),
+    });
+
+    if (action.action === "FINAL") {
+      options.onStep?.({
+        step: step + 1,
+        action: "FINAL",
+        status: "completed",
+      });
+
+      return action.answer;
+    }
+
+    options.onStep?.({
+      ...stepInfo,
+      status: "started",
+    });
+
+    const needsConfirmation =
+      action.action === "WRITE_FILE" ||
+      action.action === "EDIT_FILE" ||
+      action.action === "DELETE_FILE" ||
+      action.action === "CREATE_DIRECTORY" ||
+      action.action === "MOVE_FILE" ||
+      action.action === "COPY_FILE" ||
+      action.action === "RUN_COMMAND";
+
+    if (needsConfirmation && options.confirmTool) {
+      const approved = await options.confirmTool(action);
+
+      if (!approved) {
+        options.onStep?.({
+          ...stepInfo,
+          status: "failed",
+          error: "Denied by user",
+        });
+
+        messages.push({
+          role: "user",
+          text: `Tool denied by user: ${action.action}`,
+        });
+
+        continue;
+      }
+    }
+
+    const spinner = showSpinner
+      ? ora(`Running ${action.action}...`).start()
+      : null;
+
+    try {
+      const toolResult = await executeTool(action);
+
+      spinner?.succeed(`${action.action} completed`);
+
+      options.onStep?.({
+        ...stepInfo,
+        status: "completed",
+      });
+
+      messages.push({
+        role: "user",
+        text: `Tool result for ${action.action}:\n${toolResult}`,
+      });
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+
+      spinner?.fail(`${action.action} failed`);
+
+      options.onStep?.({
+        ...stepInfo,
+        status: "failed",
+        error: errorMessage,
+      });
+
+      messages.push({
+        role: "user",
+        text: `Tool error for ${action.action}:\n${errorMessage}`,
+      });
+    }
+  }
+
+  return "Agent stopped: max steps reached.";
+}

package/src/lib/agentMemory.ts

@@ -0,0 +1,69 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { askLLM } from "./llm.js";
+
+const MEMORY_DIR = path.join(os.homedir(), ".tuistarter", "agent-memory");
+
+function ensureMemoryDir() {
+  if (!fs.existsSync(MEMORY_DIR)) {
+    fs.mkdirSync(MEMORY_DIR, { recursive: true });
+  }
+}
+
+export function getMemoryFile(sessionName = "default") {
+  ensureMemoryDir();
+
+  const safeName = sessionName.replace(/[^a-zA-Z0-9-_]/g, "_");
+
+  return path.join(MEMORY_DIR, `${safeName}.txt`);
+}
+
+export function loadAgentMemory(sessionName = "default") {
+  const file = getMemoryFile(sessionName);
+
+  if (!fs.existsSync(file)) return "";
+
+  return fs.readFileSync(file, "utf-8");
+}
+
+export function saveAgentMemory(sessionName: string, memory: string) {
+  const file = getMemoryFile(sessionName);
+  fs.writeFileSync(file, memory, "utf-8");
+}
+
+export function clearAgentMemory(sessionName = "default") {
+  const file = getMemoryFile(sessionName);
+
+  if (fs.existsSync(file)) {
+    fs.unlinkSync(file);
+  }
+}
+
+export async function updateAgentMemory(params: {
+  previousMemory: string;
+  userPrompt: string;
+  finalAnswer: string;
+}) {
+  const prompt = `
+Update this agent memory.
+Rules:
+- Keep it short.
+- Store useful facts only.
+- Do NOT include tool JSON.
+- Do NOT include raw tool results.
+- Do NOT include hidden reasoning.
+- Do NOT include repetitive chat.
+- Prefer bullet points.
+- Max 10 bullets.
+Previous memory:
+${params.previousMemory || "None"}
+Latest user request:
+${params.userPrompt}
+Latest assistant final answer:
+${params.finalAnswer}
+Return updated memory only.
+`;
+
+  return await askLLM(prompt);
+}

package/src/lib/config.ts

@@ -0,0 +1,55 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+export type ProviderConfig = {
+  apiKey?: string;
+  baseUrl?: string;
+};
+
+export type AppConfig = {
+  activeProvider?: string;
+  activeModel?: string;
+  providers: Record<string, ProviderConfig>;
+};
+
+const CONFIG_DIR = path.join(os.homedir(), ".tuistarter");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+
+const defaultConfig: AppConfig = {
+  activeProvider: undefined,
+  providers: {},
+};
+
+export function ensureConfigDir() {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+}
+
+export function loadConfig(): AppConfig {
+  ensureConfigDir();
+
+  if (!fs.existsSync(CONFIG_FILE)) {
+    saveConfig(defaultConfig);
+    return defaultConfig;
+  }
+
+  const raw = fs.readFileSync(CONFIG_FILE, "utf-8");
+
+  if (!raw.trim()) {
+    saveConfig(defaultConfig);
+    return defaultConfig;
+  }
+
+  return JSON.parse(raw) as AppConfig;
+}
+
+export function saveConfig(config: AppConfig) {
+  ensureConfigDir();
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+export function getConfigPath() {
+  return CONFIG_FILE;
+}

package/src/lib/history.ts

@@ -0,0 +1,50 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import type { ChatMessage } from "./llm.js";
+
+const HISTORY_DIR = path.join(os.homedir(), ".tuistarter", "history");
+
+function ensureHistoryDir() {
+  if (!fs.existsSync(HISTORY_DIR)) {
+    fs.mkdirSync(HISTORY_DIR, { recursive: true });
+  }
+}
+
+export function getHistoryFile(sessionName = "default") {
+  ensureHistoryDir();
+
+  const safeName = sessionName.replace(/[^a-zA-Z0-9-_]/g, "_");
+
+  return path.join(HISTORY_DIR, `${safeName}.json`);
+}
+
+export function loadHistory(sessionName = "default"): ChatMessage[] {
+  const file = getHistoryFile(sessionName);
+
+  if (!fs.existsSync(file)) {
+    return [];
+  }
+
+  const raw = fs.readFileSync(file, "utf-8");
+
+  if (!raw.trim()) {
+    return [];
+  }
+
+  return JSON.parse(raw) as ChatMessage[];
+}
+
+export function saveHistory(sessionName: string, messages: ChatMessage[]) {
+  const file = getHistoryFile(sessionName);
+
+  fs.writeFileSync(file, JSON.stringify(messages, null, 2));
+}
+
+export function clearHistory(sessionName = "default") {
+  const file = getHistoryFile(sessionName);
+
+  if (fs.existsSync(file)) {
+    fs.unlinkSync(file);
+  }
+}

package/src/lib/llm.ts

@@ -0,0 +1,86 @@
+import { loadConfig } from "./config.js";
+import { getProvider } from "../providers/index.js";
+
+export type ChatMessage = {
+  role: "user" | "model";
+  text: string;
+};
+
+function getActiveProviderConfig() {
+  const config = loadConfig();
+
+  if (!config.activeProvider) {
+    throw new Error(
+      "No active provider. Run: tuistarter providers login -p gemini -k YOUR_KEY",
+    );
+  }
+
+  if (!config.activeModel) {
+    throw new Error(
+      "No active model. Run: tuistarter models set gemini-2.5-flash",
+    );
+  }
+
+  const providerConfig = config.providers[config.activeProvider];
+
+  if (!providerConfig) {
+    throw new Error(`Provider config not found: ${config.activeProvider}`);
+  }
+
+  const provider = getProvider(config.activeProvider);
+
+  if (config.activeProvider !== "ollama" && !providerConfig.apiKey) {
+    throw new Error(`No API key found for provider: ${config.activeProvider}`);
+  }
+
+  return {
+    provider,
+    apiKey: providerConfig.apiKey ?? "",
+    model: config.activeModel,
+  };
+}
+
+export async function askLLM(prompt: string) {
+  return askLLMWithMessages([
+    {
+      role: "user",
+      text: prompt,
+    },
+  ]);
+}
+
+export async function askLLMWithMessages(messages: ChatMessage[]) {
+  const { provider, apiKey, model } = getActiveProviderConfig();
+
+  return provider.generate({
+    apiKey,
+    model,
+    messages,
+  });
+}
+
+export async function streamLLM(prompt: string) {
+  await streamLLMToCallback(prompt, (token) => {
+    process.stdout.write(token);
+  });
+
+  process.stdout.write("\n");
+}
+
+export async function streamLLMToCallback(
+  prompt: string,
+  onToken: (token: string) => void,
+) {
+  const { provider, apiKey, model } = getActiveProviderConfig();
+
+  if (!provider.stream) {
+    throw new Error(`Streaming not supported for provider: ${provider.name}`);
+  }
+
+  await provider.stream({
+    apiKey,
+    model,
+    prompt,
+    onToken,
+  });
+}

package/src/lib/providers.ts

@@ -0,0 +1,45 @@
+export const SUPPORTED_PROVIDERS = [
+  {
+    name: "gemini",
+    models: ["gemini-2.5-flash", "gemini-2.5-pro", "gemini-2.0-flash"],
+  },
+  {
+    name: "openrouter",
+    models: [
+      // Free router
+      "openrouter/free",
+      // Coding
+      "poolside/laguna-m1:free",
+      "poolside/laguna-xs.2:free",
+      // Qwen
+      "qwen/qwen3-235b-a22b:free",
+      // DeepSeek
+      "deepseek/deepseek-r1:free",
+      "deepseek/deepseek-chat-v3-0324:free",
+      // Llama
+      "meta-llama/llama-4-maverick:free",
+      // OpenAI OSS
+      "openai/gpt-oss-120b:free",
+      "openai/gpt-oss-20b:free",
+      // NVIDIA
+      "nvidia/nemotron-3-super:free",
+      "nvidia/nemotron-3-nano-30b-a3b:free",
+      // GLM
+      "z-ai/glm-4.5-air:free",
+    ],
+  },
+  {
+    name: "ollama",
+    models: [
+      "qwen3.5:2b",
+      "qwen3.5:4b",
+      "gemma3:4b",
+      "deepseek-r1:7b",
+      "qwen2.5-coder:1.5b-instruct-q4_K_M",
+      "qwen3.5:2b-q4_K_M",
+      "qwen2.5-coder:3b-instruct-q4_K_M",
+      "qwen3.5:4b-q4_K_M",
+      "qwen2.5-coder:7b-instruct-q4_K_M",
+    ],
+  },
+];

package/src/providers/gemini.ts

@@ -0,0 +1,91 @@
+import type { LLMProvider } from "./types.js";
+
+export const geminiProvider: LLMProvider = {
+  name: "gemini",
+
+  async generate({ apiKey, model, messages }) {
+    const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`;
+
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "x-goog-api-key": apiKey,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        contents: messages.map((message) => ({
+          role: message.role,
+          parts: [{ text: message.text }],
+        })),
+      }),
+    });
+
+    if (!res.ok) {
+      throw new Error(await res.text());
+    }
+
+    const data: any = await res.json();
+
+    return (
+      data?.candidates?.[0]?.content?.parts?.[0]?.text ??
+      "No response text found."
+    );
+  },
+
+  async stream({ apiKey, model, prompt, onToken }) {
+    const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:streamGenerateContent?alt=sse`;
+
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "x-goog-api-key": apiKey,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        contents: [
+          {
+            role: "user",
+            parts: [{ text: prompt }],
+          },
+        ],
+      }),
+    });
+
+    if (!res.ok || !res.body) {
+      throw new Error(await res.text());
+    }
+
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+
+    let buffer = "";
+
+    while (true) {
+      const { done, value } = await reader.read();
+
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+
+        if (!trimmed.startsWith("data: ")) continue;
+
+        const jsonText = trimmed.replace("data: ", "");
+
+        if (jsonText === "[DONE]") continue;
+
+        const data = JSON.parse(jsonText);
+        const text = data?.candidates?.[0]?.content?.parts?.[0]?.text;
+
+        if (text) {
+          onToken(text);
+        }
+      }
+    }
+  },
+};

package/src/providers/index.ts

@@ -0,0 +1,24 @@
+import { geminiProvider } from "./gemini.js";
+import { ollamaProvider } from "./ollama.js";
+import { openrouterProvider } from "./openrouter.js";
+import type { LLMProvider } from "./types.js";
+
+export const providers: Record<string, LLMProvider> = {
+  gemini: geminiProvider,
+  openrouter: openrouterProvider,
+  ollama: ollamaProvider,
+};
+
+export function getProvider(name: string) {
+  const provider = providers[name];
+
+  if (!provider) {
+    throw new Error(`Provider not implemented yet: ${name}`);
+  }
+
+  return provider;
+}
+
+export function getProviderNames() {
+  return Object.keys(providers);
+}

package/src/providers/ollama.ts

@@ -0,0 +1,84 @@
+import type { LLMProvider } from "./types.js";
+
+export const ollamaProvider: LLMProvider = {
+  name: "ollama",
+
+  async generate({ model, messages }) {
+    const res = await fetch(
+      "http://localhost:11434/api/chat",
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          model,
+          stream: false,
+          messages: messages.map((m) => ({
+            role: m.role === "model" ? "assistant" : "user",
+            content: m.text,
+          })),
+        }),
+      },
+    );
+
+    if (!res.ok) {
+      throw new Error(await res.text());
+    }
+
+    const data: any = await res.json();
+
+    return data.message?.content ?? "";
+  },
+
+  async stream({ model, prompt, onToken }) {
+    const res = await fetch(
+      "http://localhost:11434/api/generate",
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          model,
+          prompt,
+          stream: true,
+        }),
+      },
+    );
+
+    if (!res.ok || !res.body) {
+      throw new Error(await res.text());
+    }
+
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+
+    let buffer = "";
+
+    while (true) {
+      const { done, value } = await reader.read();
+
+      if (done) break;
+
+      buffer += decoder.decode(value, {
+        stream: true,
+      });
+
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        if (!line.trim()) continue;
+
+        try {
+          const data = JSON.parse(line);
+
+          if (data.response) {
+            onToken(data.response);
+          }
+        } catch {}
+      }
+    }
+  },
+};