@strayl/agent 0.1.2 → 0.1.4

package/src/tools/external/database.ts

@@ -1,285 +0,0 @@
-import { z } from "zod";
-import type { ToolDefinition, ToolContext } from "../../types.js";
-
-/**
- * All database tools proxy through api.strayl.dev/v1/tools/database/*
- * The proxy adds auth, resolves project context, and forwards to db.strayl.dev.
- *
- * In direct mode (STRAYL_LLM_DIRECT=1), calls db.strayl.dev directly.
- */
-
-async function dbFetch(
-  path: string,
-  init: RequestInit,
-  ctx: ToolContext,
-): Promise<Response> {
-  const env = ctx.env;
-
-  if (env.STRAYL_LLM_DIRECT === "1") {
-    // Direct mode — call db.strayl.dev with auth token
-    const dbApiUrl = env.DB_API_URL ?? "https://db.strayl.dev";
-    const authToken = env.STRAYL_AUTH_TOKEN ?? "";
-    const username = env.STRAYL_USERNAME ?? "";
-    const projectSlug = env.STRAYL_PROJECT_SLUG ?? "";
-
-    const url = `${dbApiUrl}/databases/${username}/${projectSlug}${path}`;
-    const headers = new Headers(init.headers);
-    headers.set("Authorization", `Bearer ${authToken}`);
-    headers.set("Content-Type", "application/json");
-    return fetch(url, { ...init, headers });
-  }
-
-  // Proxy mode — route through api.strayl.dev
-  const apiUrl = env.STRAYL_API_URL ?? "https://api.strayl.dev";
-  const token = env.STRAYL_SESSION_TOKEN ?? "";
-  const username = env.STRAYL_USERNAME ?? "";
-  const projectSlug = env.STRAYL_PROJECT_SLUG ?? "";
-
-  const url = `${apiUrl}/v1/tools/database${path}`;
-  const headers = new Headers(init.headers);
-  headers.set("Authorization", `Bearer ${token}`);
-  headers.set("Content-Type", "application/json");
-  headers.set("X-Strayl-Project", `${username}/${projectSlug}`);
-  return fetch(url, { ...init, headers });
-}
-
-// ─── create_database ─────────────────────────────────────────────────
-
-export const createDatabaseTool: ToolDefinition = {
-  name: "create_database",
-  description:
-    "Create a Neon PostgreSQL database for the project. " +
-    "Provisions production and development branches. Sets DATABASE_URL in the sandbox.",
-  parameters: z.object({
-    name: z.string().describe("Database name"),
-    region: z
-      .string()
-      .optional()
-      .default("aws-us-east-1")
-      .describe("Neon region, defaults to aws-us-east-1"),
-  }),
-  execute: async (rawArgs: unknown, ctx: ToolContext): Promise<string> => {
-    const args = rawArgs as { name: string; region?: string };
-
-    if (!args.name.trim()) {
-      return JSON.stringify({ error: "Missing required parameter: name" });
-    }
-
-    const res = await dbFetch("", {
-      method: "POST",
-      body: JSON.stringify({ name: args.name.trim(), region: args.region ?? "aws-us-east-1" }),
-    }, ctx);
-
-    if (!res.ok) {
-      const err = await res.json().catch(() => ({})) as { error?: string };
-      return JSON.stringify({
-        error: err.error || `Database API error: ${res.status} ${res.statusText}`,
-      });
-    }
-
-    const data = await res.json() as Record<string, unknown>;
-    return JSON.stringify({
-      success: true,
-      ...(data.databases ? { databases: data.databases } : { database: data.database }),
-      ...(Array.isArray((data as any).warnings) && (data as any).warnings.length ? { warnings: (data as any).warnings } : {}),
-    });
-  },
-};
-
-// ─── list_databases ──────────────────────────────────────────────────
-
-export const listDatabasesTool: ToolDefinition = {
-  name: "list_databases",
-  description:
-    "List all databases in the project with their IDs, environments, and status.",
-  parameters: z.object({}),
-  execute: async (_rawArgs: unknown, ctx: ToolContext): Promise<string> => {
-    const res = await dbFetch("", { method: "GET" }, ctx);
-
-    if (!res.ok) {
-      const err = await res.json().catch(() => ({})) as { error?: string };
-      return JSON.stringify({
-        error: err.error || `Database API error: ${res.status} ${res.statusText}`,
-      });
-    }
-
-    const data = await res.json() as { databases?: Array<Record<string, unknown>> };
-    const databases = (data.databases || []).map((db) => ({
-      id: db.id,
-      name: db.name,
-      environment: db.environment,
-      region: db.region,
-      status: db.status,
-      createdAt: db.createdAt,
-    }));
-
-    return JSON.stringify({ databases });
-  },
-};
-
-// ─── run_database_query ──────────────────────────────────────────────
-
-export const runDatabaseQueryTool: ToolDefinition = {
-  name: "run_database_query",
-  description:
-    "Execute a SQL query against the development database. Use for SELECT, INSERT, schema introspection.",
-  parameters: z.object({
-    sql: z.string().describe("SQL query to execute"),
-    databaseId: z
-      .string()
-      .optional()
-      .describe("Database ID to query. If omitted, the development database is used automatically."),
-  }),
-  execute: async (rawArgs: unknown, ctx: ToolContext): Promise<string> => {
-    const args = rawArgs as { sql: string; databaseId?: string };
-
-    if (!args.sql.trim()) {
-      return JSON.stringify({ error: "Missing required parameter: sql" });
-    }
-
-    let databaseId = args.databaseId || "";
-
-    // Auto-find dev database if no ID given
-    if (!databaseId) {
-      const listRes = await dbFetch("", { method: "GET" }, ctx);
-      if (!listRes.ok) {
-        return JSON.stringify({ error: "Failed to list databases" });
-      }
-      const listData = await listRes.json() as { databases: Array<{ id: string; environment: string }> };
-      const devDb = listData.databases.find((db) => db.environment === "development");
-      if (!devDb) {
-        return JSON.stringify({ error: "No development database found. Create a database first." });
-      }
-      databaseId = devDb.id;
-    }
-
-    const res = await dbFetch(`/${databaseId}/query`, {
-      method: "POST",
-      body: JSON.stringify({ sql: args.sql }),
-    }, ctx);
-
-    if (!res.ok) {
-      const err = await res.json().catch(() => ({})) as { error?: string };
-      return JSON.stringify({
-        error: err.error || `Query failed: ${res.status} ${res.statusText}`,
-      });
-    }
-
-    const data = await res.json() as { rows: unknown[]; rowCount: number };
-    return JSON.stringify(data);
-  },
-};
-
-// ─── prepare_database_migration ──────────────────────────────────────
-
-export const prepareDatabaseMigrationTool: ToolDefinition = {
-  name: "prepare_database_migration",
-  description:
-    "Prepare a schema migration for review. Returns migration ID and current schema. " +
-    "One SQL statement per call. Use complete_database_migration to apply.",
-  parameters: z.object({
-    migrationSql: z.string().describe("SQL DDL statement for the migration"),
-    databaseId: z
-      .string()
-      .optional()
-      .describe("Database ID. If omitted, the development database is used automatically."),
-  }),
-  execute: async (rawArgs: unknown, ctx: ToolContext): Promise<string> => {
-    const args = rawArgs as { migrationSql: string; databaseId?: string };
-
-    if (!args.migrationSql.trim()) {
-      return JSON.stringify({ error: "Missing required parameter: migrationSql" });
-    }
-
-    let databaseId = args.databaseId || "";
-
-    // Auto-find dev database
-    if (!databaseId) {
-      const listRes = await dbFetch("", { method: "GET" }, ctx);
-      if (!listRes.ok) {
-        return JSON.stringify({ error: "Failed to list databases" });
-      }
-      const listData = await listRes.json() as { databases: Array<{ id: string; environment: string }> };
-      const devDb = listData.databases.find((db) => db.environment === "development");
-      if (!devDb) {
-        return JSON.stringify({ error: "No development database found. Create a database first." });
-      }
-      databaseId = devDb.id;
-    }
-
-    // Fetch current schema for context
-    let currentSchema: unknown[] = [];
-    try {
-      const schemaRes = await dbFetch(`/${databaseId}/query`, {
-        method: "POST",
-        body: JSON.stringify({
-          sql: `SELECT table_name, column_name, data_type, is_nullable, column_default
-                FROM information_schema.columns
-                WHERE table_schema = 'public'
-                ORDER BY table_name, ordinal_position`,
-        }),
-      }, ctx);
-      if (schemaRes.ok) {
-        const schemaData = await schemaRes.json() as { rows: unknown[] };
-        currentSchema = schemaData.rows;
-      }
-    } catch {
-      // Non-fatal
-    }
-
-    const migrationId = `mig_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
-
-    return JSON.stringify({
-      migrationId,
-      migrationSql: args.migrationSql,
-      databaseId,
-      currentSchema,
-      message: "Migration prepared. Review the SQL and current schema, then use complete_database_migration to apply.",
-    });
-  },
-};
-
-// ─── complete_database_migration ─────────────────────────────────────
-
-export const completeDatabaseMigrationTool: ToolDefinition = {
-  name: "complete_database_migration",
-  description:
-    "Apply a prepared migration. Pass migrationId, migrationSql, and databaseId from prepare step.",
-  parameters: z.object({
-    migrationId: z.string().describe("Migration ID from prepare_database_migration"),
-    migrationSql: z.string().describe("SQL statement to execute"),
-    databaseId: z.string().describe("Database ID from prepare_database_migration"),
-  }),
-  execute: async (rawArgs: unknown, ctx: ToolContext): Promise<string> => {
-    const args = rawArgs as { migrationId: string; migrationSql: string; databaseId: string };
-
-    if (!args.migrationId || !args.migrationSql.trim() || !args.databaseId) {
-      return JSON.stringify({
-        error: "Missing required parameters: migrationId, migrationSql, databaseId.",
-      });
-    }
-
-    const res = await dbFetch(`/${args.databaseId}/query`, {
-      method: "POST",
-      body: JSON.stringify({ sql: args.migrationSql }),
-    }, ctx);
-
-    if (!res.ok) {
-      const err = await res.json().catch(() => ({})) as { error?: string };
-      return JSON.stringify({
-        success: false,
-        migrationId: args.migrationId,
-        error: err.error || `Query failed: ${res.status} ${res.statusText}`,
-      });
-    }
-
-    const result = await res.json() as { rows: unknown[]; rowCount: number };
-
-    return JSON.stringify({
-      success: true,
-      migrationId: args.migrationId,
-      databaseId: args.databaseId,
-      result: { rows: result.rows, rowCount: result.rowCount },
-    });
-  },
-};

package/src/tools/external/enter-plan-mode.ts

@@ -1,34 +0,0 @@
-import { z } from "zod";
-import type { ToolDefinition } from "../../types.js";
-
-export const enterPlanModeTool: ToolDefinition = {
-  name: "enterPlanMode",
-  description: `Enter plan mode to create a detailed implementation plan before writing code. Activates immediately.
-
-USE ONLY when ALL of these are true:
-- You have NOT just exited plan mode (never re-enter after a plan was confirmed or rejected)
-- The user has NOT provided a clear plan, detailed instructions, or step-by-step requirements
-- The task genuinely requires architectural decisions with multiple valid approaches
-
-Examples where you SHOULD use this:
-- User says "add authentication" with no specifics
-- User says "refactor the API layer" — multiple approaches, need to explore first
-
-Examples where you MUST NOT use this:
-- A plan was just confirmed — implement it immediately
-- User provided specific instructions — just execute them
-- Simple or single-file tasks (typos, bug fixes, small features)
-- You already know what to do — just do it`,
-  parameters: z.object({
-    reason: z.string().describe("Why this task needs a plan (brief explanation)"),
-  }),
-  execute: async (rawArgs: unknown, ctx): Promise<string> => {
-    const args = rawArgs as { reason: string };
-    ctx.emitter.emit({ type: "plan-mode-entered", reason: args.reason });
-    return JSON.stringify({
-      success: true,
-      reason: args.reason,
-      message: "Plan mode activated. Use read-only tools and interviewUser to gather requirements, then writePlan to create the plan.",
-    });
-  },
-};

package/src/tools/external/generate-image.ts

@@ -1,110 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { z } from "zod";
-import type { ToolDefinition, ToolContext } from "../../types.js";
-import { proxyFetch } from "./proxy-fetch.js";
-
-export const generateImageTool: ToolDefinition = {
-  name: "generate_image",
-  description:
-    "Generate images using AI. Provide output paths and prompts. " +
-    "Saves generated images to the filesystem.",
-  parameters: z.object({
-    items: z
-      .array(
-        z.object({
-          path: z.string().describe("Relative output path for the image"),
-          prompt: z.string().describe("Image generation prompt"),
-          aspectRatio: z
-            .enum(["1:1", "3:2", "2:3", "4:3", "3:4", "16:9", "9:16"])
-            .optional()
-            .describe("Aspect ratio (default: 1:1)"),
-        }),
-      )
-      .min(1)
-      .max(10)
-      .describe("Array of images to generate"),
-  }),
-  execute: async (rawArgs: unknown, ctx: ToolContext): Promise<string> => {
-    const args = rawArgs as {
-      items: Array<{ path: string; prompt: string; aspectRatio?: string }>;
-    };
-
-    const results: Array<{ path: string; success: boolean }> = [];
-    const failed: Array<{ path: string; error: string }> = [];
-
-    for (const item of args.items) {
-      if (item.path.includes("..") || path.isAbsolute(item.path)) {
-        failed.push({ path: item.path, error: "Invalid path: must be relative, no .." });
-        continue;
-      }
-
-      try {
-        const response = await proxyFetch(
-          "openrouter",
-          "https://openrouter.ai/api/v1/chat/completions",
-          "OPENROUTER_API_KEY",
-          {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({
-              model: "google/gemini-2.5-flash-image",
-              messages: [{ role: "user", content: item.prompt }],
-              modalities: ["image", "text"],
-              image_config: { aspect_ratio: item.aspectRatio ?? "1:1" },
-            }),
-          },
-          ctx.env,
-        );
-
-        if (!response.ok) {
-          failed.push({ path: item.path, error: `API error: ${response.status}` });
-          continue;
-        }
-
-        const data = (await response.json()) as {
-          choices: Array<{
-            message: {
-              content: Array<{
-                type: string;
-                image_url?: { url: string };
-              }>;
-            };
-          }>;
-        };
-
-        const imageContent = data.choices?.[0]?.message?.content?.find(
-          (c) => c.type === "image_url" && c.image_url?.url,
-        );
-
-        if (!imageContent?.image_url?.url) {
-          failed.push({ path: item.path, error: "No image in response" });
-          continue;
-        }
-
-        const dataUrl = imageContent.image_url.url;
-        const base64Match = dataUrl.match(/^data:[^;]+;base64,(.+)$/);
-        if (!base64Match) {
-          failed.push({ path: item.path, error: "Invalid data URL format" });
-          continue;
-        }
-
-        const buffer = Buffer.from(base64Match[1], "base64");
-        const filePath = path.resolve(ctx.workDir, item.path);
-        await fs.mkdir(path.dirname(filePath), { recursive: true });
-        await fs.writeFile(filePath, buffer);
-
-        results.push({ path: item.path, success: true });
-      } catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        failed.push({ path: item.path, error: msg });
-      }
-    }
-
-    return JSON.stringify({
-      success: failed.length === 0,
-      items: results,
-      failed: failed.length > 0 ? failed : undefined,
-    });
-  },
-};

package/src/tools/external/hitl-tools.ts

@@ -1,118 +0,0 @@
-import { z } from "zod";
-import type { ToolDefinition } from "../../types.js";
-
-export const askUserTool: ToolDefinition = {
-  name: "askUser",
-  description:
-    "Ask the user a clarifying question with selectable options. " +
-    "Use this when you need the user to make a decision or provide clarification before proceeding. " +
-    "The user will see an interactive prompt with the options you provide.",
-  parameters: z.object({
-    question: z.string().describe("The question to ask the user"),
-    context: z.string().optional().describe("Why this question matters (shown as subtitle)"),
-    options: z
-      .array(
-        z.object({
-          label: z.string().describe("Short option label"),
-          description: z.string().optional().describe("Brief explanation of this option"),
-        })
-      )
-      .min(1)
-      .max(6)
-      .describe("1-6 options for the user to choose from"),
-    allowCustom: z
-      .boolean()
-      .optional()
-      .default(true)
-      .describe("Whether the user can type a custom answer instead of picking an option"),
-    answer: z
-      .string()
-      .optional()
-      .describe("The user's answer (provided via HITL — do not set this)"),
-  }),
-  hitl: true,
-  execute: async (rawArgs: unknown): Promise<string> => {
-    const args = rawArgs as { question: string; answer?: string };
-    if (!args.answer) {
-      return JSON.stringify({
-        success: false,
-        error: "No answer provided. The user may have rejected the question.",
-      });
-    }
-    return JSON.stringify({
-      success: true,
-      question: args.question,
-      answer: args.answer,
-    });
-  },
-};
-
-export const writePlanTool: ToolDefinition = {
-  name: "writePlan",
-  description:
-    "Write an implementation plan as a markdown file to .strayl/plans/ in the project. " +
-    "Use this after gathering requirements via askUser to present the final plan for user confirmation. " +
-    "The agent will be paused until the user confirms or provides feedback.",
-  parameters: z.object({
-    title: z.string().describe("Plan title (used as heading and filename)"),
-    content: z.string().describe("Full plan content in markdown format"),
-    filename: z
-      .string()
-      .optional()
-      .describe("Custom filename (without extension). If omitted, derived from title."),
-    feedback: z
-      .string()
-      .optional()
-      .describe("Internal: user feedback on the plan (set by HITL resume)"),
-  }),
-  hitl: true,
-  execute: async (rawArgs: unknown): Promise<string> => {
-    const args = rawArgs as { title: string; content: string; filename?: string; feedback?: string };
-
-    if (args.feedback) {
-      return JSON.stringify({
-        success: false,
-        feedback: args.feedback,
-        message: `User wants changes to the plan: ${args.feedback}`,
-      });
-    }
-
-    const safeName =
-      args.filename ||
-      args.title
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-|-$/g, "")
-        .slice(0, 60);
-    const filePath = `.strayl/plans/${safeName}.md`;
-
-    return JSON.stringify({
-      success: true,
-      filePath,
-      message: `Plan confirmed by user. Written to ${filePath}. You are now in IMPLEMENTATION MODE. Start executing the plan immediately — do NOT call enterPlanMode again.`,
-    });
-  },
-};
-
-export const requestEnvVarTool: ToolDefinition = {
-  name: "requestEnvVar",
-  description:
-    "Request an environment variable or API key from the user. " +
-    "Use when a tool needs an API key that isn't configured.",
-  parameters: z.object({
-    name: z.string().describe("Environment variable name (e.g. STRIPE_API_KEY)"),
-    reason: z.string().describe("Why this variable is needed"),
-    value: z
-      .string()
-      .optional()
-      .describe("The value (provided via HITL — do not set this)"),
-  }),
-  hitl: true,
-  execute: async (rawArgs: unknown): Promise<string> => {
-    const args = rawArgs as { name: string; reason: string; value?: string };
-    if (args.value) {
-      return JSON.stringify({ name: args.name, value: args.value, set: true });
-    }
-    return JSON.stringify({ name: args.name, error: "User did not provide value" });
-  },
-};

package/src/tools/external/preview.ts

@@ -1,28 +0,0 @@
-import { z } from "zod";
-import type { ToolDefinition, ToolContext } from "../../types.js";
-
-export const previewTool: ToolDefinition = {
-  name: "show_preview",
-  description:
-    "Signal that a web preview is available on a given port. " +
-    "The proxy will resolve this to a publicly accessible URL.",
-  parameters: z.object({
-    port: z.number().describe("Port number the preview is running on"),
-    title: z.string().optional().describe("Title for the preview (default: 'Preview')"),
-  }),
-  execute: async (rawArgs: unknown, ctx: ToolContext): Promise<string> => {
-    const args = rawArgs as { port: number; title?: string };
-
-    ctx.emitter.emit({
-      type: "preview",
-      port: args.port,
-      title: args.title ?? "Preview",
-    });
-
-    return JSON.stringify({
-      success: true,
-      port: args.port,
-      message: "Preview event emitted. The proxy will provide the URL.",
-    });
-  },
-};

package/src/tools/external/proxy-fetch.ts

@@ -1,51 +0,0 @@
-/**
- * Helper for external tools that need to call third-party APIs.
- * In proxy mode: routes through api.strayl.dev/v1/tools/{service}
- * In direct mode: calls the API directly with env var keys.
- *
- * This ensures API keys never live inside the sandbox.
- */
-
-export interface ProxyFetchConfig {
-  env: Record<string, string>;
-}
-
-/**
- * Make an API call, routing through the Strayl proxy in production.
- * @param service - Service name for proxy routing (e.g. "tavily", "jina", "openrouter")
- * @param directUrl - Direct API URL (used in STRAYL_LLM_DIRECT=1 mode)
- * @param directApiKey - Direct API key env var name (e.g. "TAVILY_API_KEY")
- * @param init - Fetch init (method, headers, body)
- * @param env - Environment variables
- */
-export async function proxyFetch(
-  service: string,
-  directUrl: string,
-  directApiKey: string,
-  init: RequestInit,
-  env: Record<string, string>,
-): Promise<Response> {
-  if (env.STRAYL_LLM_DIRECT === "1") {
-    // Direct mode — use raw API key
-    const key = env[directApiKey];
-    if (!key) {
-      throw new Error(`${directApiKey} not configured (direct mode)`);
-    }
-    const headers = new Headers(init.headers);
-    if (!headers.has("Authorization")) {
-      headers.set("Authorization", `Bearer ${key}`);
-    }
-    return fetch(directUrl, { ...init, headers });
-  }
-
-  // Proxy mode — route through api.strayl.dev
-  const apiUrl = env.STRAYL_API_URL ?? "https://api.strayl.dev";
-  const token = env.STRAYL_SESSION_TOKEN ?? "";
-  const proxyUrl = `${apiUrl}/v1/tools/${service}`;
-
-  const headers = new Headers(init.headers);
-  headers.set("Authorization", `Bearer ${token}`);
-  headers.set("X-Strayl-Direct-URL", directUrl);
-
-  return fetch(proxyUrl, { ...init, headers });
-}

package/src/tools/external/task.ts

@@ -1,38 +0,0 @@
-import { z } from "zod";
-import type { ToolDefinition, ToolContext } from "../../types.js";
-import type { SubAgentManager } from "../../subagents/manager.js";
-
-export function createTaskTool(subAgentManager: SubAgentManager): ToolDefinition {
-  return {
-    name: "task",
-    description:
-      "Delegate work to a specialized sub-agent. " +
-      "Use code-explorer for codebase search, web-researcher for docs/APIs, " +
-      "general-purpose for combined tasks. Sub-agents run in the same process " +
-      "and return their result when complete.",
-    parameters: z.object({
-      agent: z
-        .enum(["code-explorer", "web-researcher", "general-purpose"])
-        .describe("Which sub-agent to use"),
-      description: z.string().describe("Short task title (3-6 words)"),
-      prompt: z.string().describe("Detailed task instructions"),
-    }),
-    execute: async (rawArgs: unknown, ctx: ToolContext): Promise<string> => {
-      const args = rawArgs as {
-        agent: string;
-        description: string;
-        prompt: string;
-      };
-
-      const id = subAgentManager.spawn({
-        agentName: args.agent,
-        label: args.description,
-        prompt: args.prompt,
-        workDir: ctx.workDir,
-        env: ctx.env,
-      });
-
-      return await subAgentManager.waitFor(id);
-    },
-  };
-}

package/src/tools/external/wait.ts

@@ -1,20 +0,0 @@
-import { z } from "zod";
-import type { ToolDefinition } from "../../types.js";
-
-export const waitTool: ToolDefinition = {
-  name: "wait",
-  description:
-    "Wait for a specified number of seconds. Useful for waiting for background processes to start. " +
-    "Clamped between 1 and 120 seconds.",
-  parameters: z.object({
-    seconds: z.number().describe("Number of seconds to wait (1-120)"),
-  }),
-  execute: async (rawArgs: unknown): Promise<string> => {
-    const args = rawArgs as { seconds: number };
-    const seconds = Math.max(1, Math.min(120, args.seconds));
-
-    await new Promise(resolve => setTimeout(resolve, seconds * 1000));
-
-    return JSON.stringify({ waited: seconds });
-  },
-};