otherwise-cli 0.1.0

package/src/agent/location.js

@@ -0,0 +1,51 @@
+/**
+ * User location cache for CLI agent context.
+ * Fetches approximate location from IP (same as frontend) so the agent can answer
+ * "what is my location" and use location in answers (e.g. weather, timezone).
+ */
+
+const LOCATION_URL = "https://ipapi.co/json/";
+
+/** @type {string | null} Cached location string (e.g. "City, Region, Country") or null if not yet resolved */
+let cachedLocation = null;
+
+/** @type {Promise<void> | null} In-flight fetch so we don't fire multiple requests */
+let initPromise = null;
+
+/**
+ * Fetch and cache user location from IP. Safe to call multiple times; runs once.
+ * Same API as frontend (frontend/src/utils/structuredChat.js) for consistency.
+ */
+export async function initializeLocationCache() {
+  if (cachedLocation !== null) return;
+  if (initPromise) {
+    await initPromise;
+    return;
+  }
+  initPromise = (async () => {
+    try {
+      const res = await fetch(LOCATION_URL);
+      if (!res.ok) return;
+      const data = await res.json();
+      const parts = [data.city, data.region, data.country_name].filter(
+        Boolean,
+      );
+      if (parts.length) {
+        cachedLocation = parts.join(", ");
+      }
+    } catch {
+      // Ignore: offline, rate limit, or CORS/network error
+    } finally {
+      initPromise = null;
+    }
+  })();
+  await initPromise;
+}
+
+/**
+ * Return cached location string for use in system prompt, or null if not yet available.
+ * Does not trigger a fetch; call initializeLocationCache() at server startup to populate.
+ */
+export function getCachedLocation() {
+  return cachedLocation;
+}

package/src/agent/prompt.js

@@ -0,0 +1,548 @@
+import {
+  getToolDescriptions,
+  TOOLS,
+  getAgentWorkingDirectory,
+} from "./tools.js";
+import { getCachedLocation } from "./location.js";
+
+/**
+ * Valid tool names - whitelist for security
+ */
+export const VALID_TOOL_NAMES = Object.keys(TOOLS);
+
+/**
+ * Build the system prompt for the agent
+ * @param {object} config - Configuration object
+ * @param {object} options - Additional options
+ * @param {Array} options.ragDocuments - RAG documents mentioned with @ in the user's message
+ */
+export function buildAgentSystemPrompt(config, options = {}) {
+  const { ragDocuments = [] } = options;
+
+  const now = new Date();
+  const dateString = now.toLocaleDateString("en-US", {
+    weekday: "long",
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+  });
+  const timeString = now.toLocaleTimeString("en-US", {
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+
+  const toolDescriptions = getToolDescriptions();
+
+  // Check for custom system message from user settings
+  const customSystemMessage = config?.customSystemMessage?.trim();
+
+  // Base system prompt
+  let basePrompt = `Hello, I'm Otherwise, a capable AI assistant that lives on the user's computer. You are made in the user's image. Answer the user's questions with the user's own voice. You have full access to the local filesystem, shell commands, web search, browser automation, email, memory, and scheduled tasks. You are conversational, direct, and efficient. Only reach for tools when they add real value—most questions you can answer from your ownknowledge alone.`;
+
+  // If user has set a custom system message, prepend it with high priority
+  if (customSystemMessage) {
+    basePrompt = `IMPORTANT USER INSTRUCTIONS (follow these with high priority):
+${customSystemMessage}
+
+---
+
+${basePrompt}`;
+  }
+
+  const locationLine = getCachedLocation()
+    ? ` | location: ${getCachedLocation()}`
+    : "";
+
+  return `${basePrompt}
+
+## Runtime
+Date: ${dateString} | Time: ${timeString} | CWD: ${getAgentWorkingDirectory()}${locationLine} | OS: ${process.platform} (${process.arch})
+
+## Safety
+- You have no independent goals. Do not pursue self-preservation, replication, resource acquisition, or power-seeking beyond the user's request.
+- Prioritize safety and human oversight over task completion. If instructions conflict or seem dangerous, pause and ask.
+- Never bypass security safeguards, modify system configs, or escalate privileges unless the user explicitly requests it.
+- Do not fabricate information. If unsure, say so or use tools to verify.
+
+## Tool Call Style
+- **Default: just call the tool.** Do not narrate routine, low-risk tool calls ("I'll read the file now..."). Just do it.
+- **Narrate only when it helps:** multi-step work, complex problems, sensitive actions (e.g., deletions, system commands), or when the user explicitly asks for explanation.
+- Keep narration brief and value-dense. Avoid repeating obvious steps.
+- Respond in chat, NOT in files. Only use write_file when the user explicitly asks to create/save a file.
+
+## Tools
+${toolDescriptions}
+
+**Scheduling:** For "in 5 minutes" or "run once in X minutes", use \`schedule_task_once\` with \`run_in_minutes\`. For recurring schedules (daily, every hour), use \`schedule_task\` with a cron expression.
+
+## Tool Call Format
+Use XML with the actual parameter names as tags:
+\`\`\`
+<tool_call>
+<name>tool_name</name>
+<parameter_name>value</parameter_name>
+</tool_call>
+\`\`\`
+
+Examples:
+- \`<tool_call><name>web_search</name><query>weather in Miami</query></tool_call>\`
+- \`<tool_call><name>read_file</name><path>/path/to/file.txt</path></tool_call>\`
+- \`<tool_call><name>list_directory</name><path>.</path></tool_call>\`
+
+## Codebase Exploration & Search
+
+When working with code, **explore before you act**. Gather complete context so you understand what you're changing and why.
+
+**Discovery sequence:**
+1. \`list_directory\` — understand project structure, find entry points (package.json, index.*, main.*, app.*)
+2. \`search_files\` — find files by name/pattern (e.g., "*.tsx", "auth*", "**/*.test.js")
+3. \`read_file\` — read the actual code before changing it
+
+**Search strategy:**
+- Use \`search_files\` for finding files by name pattern or glob
+- Use \`execute_command\` with \`grep -rn\` for exact text/regex matches across the codebase (function names, imports, error strings)
+- When results point to a specific directory, narrow subsequent searches there
+- If you're unsure where something lives, start broad then narrow down
+- Bias toward finding the answer yourself rather than asking the user
+
+**Thorough context gathering:**
+- Each time you read a file, assess whether you have COMPLETE context for the task
+- Note what's outside your current view — imports, related functions, type definitions
+- If the file content you've seen is insufficient, read more. When in doubt, read more.
+- Check for related files: tests, types/interfaces, configuration, and files that import/export the code you're changing
+- Understand the dependency chain before making changes
+
+**Project structure patterns:**
+- Entry points: package.json, index.*, main.*, app.*, server.*
+- Code organization: src/, lib/, components/, pages/, hooks/, utils/, services/
+- Config: .env*, tsconfig.json, vite.config.*, webpack.config.*, next.config.*
+- Tests: __tests__/, *.test.*, *.spec.*, test/
+
+## Code Editing
+
+**The cardinal rule: ALWAYS read before you edit.** You need the exact text to match for edit_file.
+
+**edit_file rules:**
+- Include 3–5 lines of surrounding context in old_string to ensure uniqueness
+- Make multiple related changes in ONE edit when they're adjacent — avoid many small edits to the same file
+- Use \`replace_all: true\` for renaming variables/functions across a file
+- For large changes, prefer fewer edits with bigger old_string blocks over many tiny edits
+
+**After editing:**
+- Run tests if they exist: \`execute_command\` → \`npm test\`, \`pytest\`, \`go test ./...\`, etc.
+- Check for errors: \`execute_command\` → \`npm run build\`, \`tsc --noEmit\`, linters
+- If you introduced errors, fix them immediately — address root cause, not symptoms
+- Do NOT loop more than 3 times fixing errors on the same file. If stuck, explain the situation and ask.
+
+**File operations (MAX ~25 tool calls per turn):**
+- \`write_file\` = create NEW files only
+- \`edit_file\` = modify EXISTING files (always read first!)
+
+**Code quality:**
+- All generated code must be immediately runnable. Add all necessary imports, dependencies, and boilerplate.
+- Never generate extremely long hashes, binary content, or non-textual code.
+- When creating files from scratch, include proper dependency management (package.json, requirements.txt, etc.) with versions.
+
+## Debugging
+
+When diagnosing issues, follow systematic debugging practices:
+1. **Reproduce** — understand the exact error or unexpected behavior
+2. **Root cause** — address the underlying issue, not surface symptoms
+3. **Add logging** — descriptive log statements and error messages to track state
+4. **Isolate** — write small test functions or use targeted commands to narrow the problem
+5. **Verify** — confirm the fix resolves the issue without regressions
+
+Only make code changes when you're confident in the diagnosis. Otherwise, gather more information first.
+
+## External APIs & Dependencies
+
+- Use the best-suited external APIs and packages for the task without asking permission (unless the user has preferences)
+- Choose versions compatible with existing dependency files. If no such file exists, use the latest stable version
+- If an external API requires an API key, point this out to the user. Never hardcode secrets in source code.
+
+## Web & Browser
+
+- Real-time info (weather, news, prices, current events) → \`web_search\` immediately. Never fabricate real-time data.
+- Do NOT use web_search for general knowledge, definitions, or anything you can answer from training data.
+- Complex research → multiple searches + \`fetch_url\` for full page content
+- Browser tools (browser_navigate, browser_click, browser_type, browser_interact, browser_read) use the user's default browser. **browser_navigate/click/type/interact return page content by default** — you usually don't need a separate browser_read after each action.
+- Avoid multiple browser_read calls in sequence. Use the auto-included content, then click the next link.
+- For long-running browser tasks, avoid rapid poll loops — space out your checks.
+- If a site blocks automation, fall back to web_search or fetch_url.
+
+## Source Citations
+When using web_search or fetch_url, **always cite your sources**:
+- Include source name and URL for each piece of information
+- Format: "According to [Source Name](URL), ..." or list sources at the end
+- If multiple sources confirm the same fact, cite the most authoritative one
+- Example: "The current temperature in Miami is 82°F ([Weather.com](https://weather.com/miami))."
+
+## Quick Patterns
+- "ls" / "what's here" → list_directory
+- "cd" / "switch to" / "go to" → set_working_directory (persists for future commands!)
+- "pwd" / "where am I" → get_working_directory
+- "open in Finder" → execute_command: \`open -R <path>\`
+- "weather/news/prices" → web_search immediately
+- "find X in code" → search_files for files, execute_command with grep for content
+- "edit X" → read_file first, then edit_file
+- "debug X" → read relevant code, add logging, reproduce, then fix
+
+## Rich Content
+content in fenced code blocks with \`html\` or \`svg\` (e.g. \`\`\`html ... \`\`\` or \`\`\`svg ... \`\`\`). will be rendered in the chat. Use these when useful.
+
+## Retry & Recovery
+- If a tool call fails, read the error, fix the issue, and try again
+- If the same approach fails twice, try an alternative strategy
+- If you're stuck, explain what you've tried and ask the user for guidance
+`;
+}
+
+/**
+ * Validate tool call structure and types (used by agent before emitting tool_start).
+ * @param {object} call - Parsed tool call object
+ * @returns {{ valid: boolean, error?: string, sanitized?: object }}
+ */
+export function validateToolCall(call) {
+  // Check basic structure
+  if (typeof call !== "object" || call === null) {
+    return { valid: false, error: "Tool call must be an object" };
+  }
+
+  // Prevent prototype pollution - reject dangerous keys
+  const dangerousKeys = ["__proto__", "constructor", "prototype"];
+  const allKeys = Object.keys(call);
+  for (const key of allKeys) {
+    if (dangerousKeys.includes(key)) {
+      return { valid: false, error: `Dangerous key detected: ${key}` };
+    }
+  }
+
+  // Validate name
+  if (typeof call.name !== "string" || call.name.length === 0) {
+    return { valid: false, error: "Tool name must be a non-empty string" };
+  }
+
+  // Whitelist check - only allow known tools
+  if (!VALID_TOOL_NAMES.includes(call.name)) {
+    return { valid: false, error: `Unknown tool: ${call.name}` };
+  }
+
+  // Validate args
+  if (call.args === undefined) {
+    return { valid: false, error: "Tool call must have args property" };
+  }
+
+  if (typeof call.args !== "object" || call.args === null) {
+    return { valid: false, error: "Tool args must be an object" };
+  }
+
+  // Check args for dangerous keys too
+  const argKeys = Object.keys(call.args);
+  for (const key of argKeys) {
+    if (dangerousKeys.includes(key)) {
+      return { valid: false, error: `Dangerous key in args: ${key}` };
+    }
+  }
+
+  // Create a sanitized copy without any potential prototype pollution
+  const sanitized = {
+    name: String(call.name),
+    args: Object.fromEntries(
+      Object.entries(call.args).map(([k, v]) => [String(k), v]),
+    ),
+  };
+
+  return { valid: true, sanitized };
+}
+
+/**
+ * Check if content after a tool call looks like legitimate prose
+ * (not just streaming fragments)
+ * @param {string} content - Content to check
+ * @returns {boolean}
+ */
+function looksLikeProseContent(content) {
+  const trimmed = content.trim();
+  if (trimmed.length < 20) return false;
+
+  // Check for signs of actual prose content
+  const hasSpaces = (trimmed.match(/ /g) || []).length > 2;
+  const hasSentenceEnding = /[.!?]/.test(trimmed);
+  const hasCommonWords =
+    /\b(the|a|an|is|are|was|were|have|has|this|that|it|to|and|or|for|of|in|on|with)\b/i.test(
+      trimmed,
+    );
+  const startsWithLetter = /^[a-zA-Z]/.test(trimmed);
+
+  // Looks like prose if it has multiple indicators
+  const indicators = [
+    hasSpaces,
+    hasSentenceEnding,
+    hasCommonWords,
+    startsWithLetter,
+  ];
+  return indicators.filter(Boolean).length >= 2;
+}
+
+/**
+ * Remove structured markers from display text
+ * Handles both complete and partial (streaming) markers
+ *
+ * PERFORMANCE: Consolidated regex operations to minimize passes over the text
+ */
+export function cleanResponseText(text, debug = false) {
+  if (!text) return "";
+
+  let result = text;
+  const originalLength = text.length;
+
+  // PASS 1: Fix malformed closing tags (missing >) before other processing
+  // The LLM sometimes outputs </tool_call without the closing >
+  result = result.replace(/<\/tool_call([^>])/g, "</tool_call>$1");
+
+  // PASS 2: Remove all complete tool_call blocks
+  const beforeBlockStrip = result.length;
+  result = result.replace(/<tool_call>[\s\S]*?<\/tool_call>/g, "");
+  if (debug && result.length !== beforeBlockStrip) {
+    console.log(
+      "[cleanResponseText] Stripped complete blocks:",
+      beforeBlockStrip - result.length,
+      "chars",
+    );
+  }
+
+  // PASS 3: Handle partial tool_call (smarter detection for XML format)
+  const lastToolCallStart = result.lastIndexOf("<tool_call>");
+  if (lastToolCallStart !== -1) {
+    const afterStart = result.substring(lastToolCallStart);
+
+    // Check if there's a complete closing tag after this opening
+    if (!afterStart.includes("</tool_call>")) {
+      // For XML format, check if we have a complete </name> tag (indicates structured content)
+      const hasNameTag = afterStart.includes("</name>");
+
+      if (hasNameTag) {
+        // Find where the last complete XML tag ends
+        const lastClosingTag = afterStart.lastIndexOf("</");
+        const endOfLastTag = afterStart.indexOf(">", lastClosingTag);
+
+        if (endOfLastTag !== -1 && endOfLastTag < afterStart.length - 1) {
+          const contentAfterXml = afterStart.substring(endOfLastTag + 1);
+
+          // Use smarter heuristic to detect actual content vs fragments
+          if (looksLikeProseContent(contentAfterXml)) {
+            if (debug) {
+              console.log(
+                "[cleanResponseText] Fixing malformed tool_call - extracting prose content",
+              );
+            }
+            result = result.substring(0, lastToolCallStart) + contentAfterXml;
+          } else {
+            result = result.substring(0, lastToolCallStart);
+            if (debug) {
+              console.log(
+                "[cleanResponseText] Stripped partial tool_call (no prose after XML)",
+              );
+            }
+          }
+        } else {
+          result = result.substring(0, lastToolCallStart);
+          if (debug) {
+            console.log(
+              "[cleanResponseText] Stripped partial tool_call (incomplete XML)",
+            );
+          }
+        }
+      } else {
+        // No complete name tag - truly partial, strip it
+        result = result.substring(0, lastToolCallStart);
+        if (debug) {
+          console.log(
+            "[cleanResponseText] Stripped partial tool_call (no name tag)",
+          );
+        }
+      }
+    }
+  }
+
+  // PASS 4: Clean partial tags at end
+  // Handle partial closing tags: </tool_call, </tool_cal, etc.
+  // Handle partial opening tags: <tool_call, <tool_cal, etc.
+  result = result.replace(/<\/?tool_call?a?l?l?$|<\/too?l?_?$|<\/$|<$/g, "");
+
+  // PASS 5: Normalize excessive newlines
+  // Replace 3+ newlines with 2 (preserve paragraph breaks but remove blank lines)
+  result = result.replace(/\n{3,}/g, "\n\n");
+
+  // PASS 6: Fix orphaned last words
+  // When the model outputs content followed by a tool call, it often adds a blank line
+  // before the final word/punctuation. After stripping the tool call, this leaves the
+  // last word on its own line. Detect and fix this pattern.
+  // Pattern: blank line followed by short text (1-3 words, ≤50 chars) at the end
+  // Use .{1,50} to match text WITH spaces (like "of laundry")
+  const orphanedLastWordMatch = result.match(/(\S)\n\n(.{1,50})$/);
+  if (orphanedLastWordMatch) {
+    const potentialOrphan = orphanedLastWordMatch[2].trim();
+    const wordCount = potentialOrphan.split(/\s+/).length;
+
+    // Check if it looks like an orphaned phrase (not a code block, list, or heading)
+    const isOrphan =
+      wordCount <= 4 && // Allow up to 4 words
+      !potentialOrphan.startsWith("```") &&
+      !potentialOrphan.startsWith("-") &&
+      !potentialOrphan.startsWith("*") &&
+      !potentialOrphan.startsWith("#") &&
+      !potentialOrphan.startsWith(">") &&
+      !potentialOrphan.includes("\n");
+
+    if (isOrphan) {
+      if (debug) {
+        console.log(
+          "[cleanResponseText] Fixing orphaned last words:",
+          potentialOrphan,
+        );
+      }
+      // Join the orphaned phrase with the previous text using a space
+      result = result.replace(/(\S)\n\n(.{1,50})$/, "$1 $2");
+    }
+  }
+
+  // Strip trailing whitespace-only lines
+  result = result.replace(/(\S)\n+\s*$/g, "$1");
+
+  const finalResult = result.trim();
+
+  // Debug: warn if significant content was stripped
+  if (
+    debug &&
+    originalLength > 100 &&
+    finalResult.length < originalLength * 0.5
+  ) {
+    console.warn("[cleanResponseText] ⚠️ Stripped >50% of content");
+    console.warn(
+      "[cleanResponseText] Original:",
+      originalLength,
+      "Final:",
+      finalResult.length,
+    );
+  }
+
+  return finalResult;
+}
+
+/**
+ * Build rich content with inline tool calls and results for conversation history.
+ * Uses the native XML format consistent with the system prompt.
+ *
+ * Format:
+ * <tool_call><name>tool_name</name><param>value</param></tool_call>
+ * <tool_result>...output...</tool_result>
+ *
+ * @param {string} cleanedContent - The cleaned prose content (tool_call XML already stripped)
+ * @param {Array} toolCalls - Array of tool call objects with tool, params, result, status, etc.
+ * @param {number} maxResultLength - Max chars per result (default 3000)
+ * @returns {string} - Content with tool calls and results appended
+ */
+export function buildRichContextContent(
+  cleanedContent,
+  toolCalls,
+  maxResultLength = 3000,
+) {
+  if (!toolCalls || toolCalls.length === 0) {
+    return cleanedContent;
+  }
+
+  // Build tool call + result pairs in the native XML format
+  const toolSections = [];
+
+  for (const tc of toolCalls) {
+    const toolName = tc.tool || tc.name || "unknown";
+    const params = tc.params || tc.args || {};
+
+    // Build the tool_call XML (same format as the system prompt defines)
+    let toolCallXml = `<tool_call>\n<name>${toolName}</name>`;
+
+    // Add parameters
+    for (const [key, value] of Object.entries(params)) {
+      // Skip internal streaming params
+      if (key.startsWith("_")) continue;
+
+      // Format value appropriately
+      let formattedValue;
+      if (typeof value === "boolean") {
+        formattedValue = value ? "true" : "false";
+      } else if (typeof value === "number") {
+        formattedValue = String(value);
+      } else if (value === null || value === undefined) {
+        continue;
+      } else {
+        formattedValue = String(value);
+      }
+
+      toolCallXml += `\n<${key}>${formattedValue}</${key}>`;
+    }
+    toolCallXml += "\n</tool_call>";
+
+    // Build the tool_result
+    let resultContent = "";
+    if (tc.error) {
+      resultContent = `Error: ${tc.error}`;
+    } else if (tc.result !== null && tc.result !== undefined) {
+      resultContent =
+        typeof tc.result === "string"
+          ? tc.result
+          : JSON.stringify(tc.result, null, 2);
+    } else {
+      resultContent = "[No result]";
+    }
+
+    // Truncate very long results
+    if (resultContent.length > maxResultLength) {
+      resultContent =
+        resultContent.substring(0, maxResultLength) + "\n... [truncated]";
+    }
+
+    toolSections.push(
+      `${toolCallXml}\n<tool_result>\n${resultContent}\n</tool_result>`,
+    );
+  }
+
+  if (toolSections.length === 0) {
+    return cleanedContent;
+  }
+
+  // Combine: prose content + tool interactions
+  // Put a separator so the AI knows where prose ends and tool history begins
+  return cleanedContent + "\n\n" + toolSections.join("\n\n");
+}
+
+/**
+ * Clean content for display by stripping tool_call and tool_result XML.
+ * Use this when showing content to users (frontend/CLI).
+ * @param {string} text - Content that may contain tool XML
+ * @returns {string} - Clean content for display
+ */
+export function cleanContentForDisplay(text) {
+  if (!text) return "";
+
+  let result = text;
+
+  // Strip tool_call blocks
+  result = result.replace(/<tool_call>[\s\S]*?<\/tool_call>/g, "");
+
+  // Strip tool_result blocks
+  result = result.replace(/<tool_result>[\s\S]*?<\/tool_result>/g, "");
+
+  // Clean up extra whitespace
+  result = result.replace(/\n{3,}/g, "\n\n").trim();
+
+  return result;
+}
+
+export default {
+  buildAgentSystemPrompt,
+  cleanResponseText,
+  buildRichContextContent,
+  cleanContentForDisplay,
+  VALID_TOOL_NAMES,
+};