@m8i-51/shoal 0.1.13 → 0.1.15

package/.env.example

@@ -99,3 +99,9 @@ GITHUB_REPO=owner/repo
 
 MAX_EXPLORERS=4
 MAX_BROWSERS=2
+
+# Persona templates (optional)
+# Path to a local YAML/JSON file, or an npm package name.
+# If omitted, shoal auto-discovers personas.yaml / personas.yml / personas.json in the project root.
+# SHOAL_PERSONAS=./personas.yaml
+# SHOAL_PERSONAS=shoal-personas-ecommerce

package/framework/__tests__/coverage.test.ts

@@ -22,6 +22,7 @@ function makeEntry(overrides: Partial<RunCoverage> = {}): RunCoverage {
     byCategory: {},
     byLens: {},
     byScenario: {},
+    visitedPaths: [],
     ...overrides,
   };
 }

package/framework/__tests__/report.test.ts

@@ -52,6 +52,7 @@ function makeAgentLog(overrides: Partial<AgentLog> = {}): AgentLog {
     status: "completed",
     iterations: 3,
     actions: [],
+    visitedPaths: [],
     issuesPosted: [],
     regressionChecks: [],
     error: null,

package/framework/account-manager.ts

@@ -287,7 +287,8 @@ If user management is not accessible from this account, or the app has no role s
           }
 
           case "navigate": {
-            const { path: navPath } = toolUse.input as { path: string };
+            const { path: navPath } = toolUse.input as { path?: string };
+            if (!navPath) { resultText = "navigate: missing path"; break; }
             await saveSnapshotBeforeAction(page, observation);
             await page.goto(`${baseUrl}${navPath}`, { waitUntil: "networkidle" });
             await page.waitForTimeout(500);
@@ -297,7 +298,8 @@ If user management is not accessible from this account, or the app has no role s
           }
 
           case "click": {
-            const { description } = toolUse.input as { description: string };
+            const { description } = toolUse.input as { description?: string };
+            if (!description) { resultText = "click: missing description"; break; }
             await saveSnapshotBeforeAction(page, observation);
             const escaped = description.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
             let clicked = false;
@@ -316,7 +318,8 @@ If user management is not accessible from this account, or the app has no role s
           }
 
           case "fill": {
-            const { label, value } = toolUse.input as { label: string; value: string };
+            const { label, value } = toolUse.input as { label?: string; value?: string };
+            if (!label || value === undefined) { resultText = "fill: missing label or value"; break; }
             await saveSnapshotBeforeAction(page, observation);
             const byLabel = page.getByLabel(new RegExp(label, "i"));
             const byPlaceholder = page.getByPlaceholder(new RegExp(label, "i"));
@@ -340,7 +343,8 @@ If user management is not accessible from this account, or the app has no role s
           }
 
           case "save_account": {
-            const { email, password, role } = toolUse.input as { email: string; password: string; role: string };
+            const { email, password, role } = toolUse.input as { email?: string; password?: string; role?: string };
+            if (!email || !password || !role) { resultText = "save_account: missing required fields"; break; }
             savedAccounts.push({ email, password, role });
             console.log(`  [account-manager] saved account: ${email} (role: ${role})`);
             resultText = `Account saved: ${email} (${role})`;
@@ -348,7 +352,8 @@ If user management is not accessible from this account, or the app has no role s
           }
 
           case "post_finding": {
-            const { title, body } = toolUse.input as { title: string; body: string };
+            const { title, body } = toolUse.input as { title?: string; body?: string };
+            if (!title || !body) { resultText = "post_finding: missing title or body"; break; }
             saveFinding({
               id: `acct_${Date.now()}`,
               runId,

package/framework/coverage.ts

@@ -10,6 +10,7 @@ export interface RunCoverage {
   byCategory: Record<string, number>;
   byLens: Record<string, number>;
   byScenario: Record<string, number>;
+  visitedPaths: string[];
 }
 
 export interface Coverage {
@@ -45,10 +46,18 @@ function saveCoverage(coverage: Coverage): void {
   fs.writeFileSync(COVERAGE_PATH, JSON.stringify(coverage, null, 2), "utf-8");
 }
 
+export function getLastRunPaths(): { visitedPaths: string[]; runId: string } | null {
+  const coverage = loadCoverage();
+  if (coverage.entries.length === 0) return null;
+  const last = coverage.entries[coverage.entries.length - 1];
+  return { visitedPaths: last.visitedPaths ?? [], runId: last.runId };
+}
+
 export function updateCoverage(
   runId: string,
   findings: Finding[],
   agentAssignments: Map<string, { scenario?: Scenario; lens?: string }>,
+  visitedPaths: string[] = [],
 ): void {
   const coverage = loadCoverage();
 
@@ -69,6 +78,7 @@ export function updateCoverage(
     }
   }
 
+  const uniquePaths = [...new Set(visitedPaths)].sort();
   coverage.entries.push({
     runId,
     timestamp: new Date().toISOString(),
@@ -76,6 +86,7 @@ export function updateCoverage(
     byCategory,
     byLens,
     byScenario,
+    visitedPaths: uniquePaths,
   });
 
   if (coverage.entries.length > MAX_ENTRIES) {

package/framework/persona-pack.ts

@@ -0,0 +1,137 @@
+import * as fs from "fs";
+import * as path from "path";
+import { parse as parseYaml } from "yaml";
+
+export interface PersonaTemplate {
+  name: string;
+  role: string;
+  persona: string;
+  lenses?: string[];
+}
+
+export interface PersonaPack {
+  name: string;
+  version?: string;
+  personas: PersonaTemplate[];
+}
+
+function isPersonaTemplate(v: unknown): v is PersonaTemplate {
+  if (typeof v !== "object" || v === null) return false;
+  const o = v as Record<string, unknown>;
+  return typeof o.name === "string" && typeof o.role === "string" && typeof o.persona === "string";
+}
+
+function parseRaw(raw: unknown, source: string): PersonaPack | null {
+  if (typeof raw !== "object" || raw === null) {
+    console.warn(`[persona-pack] ${source}: expected an object, got ${typeof raw}`);
+    return null;
+  }
+  const obj = raw as Record<string, unknown>;
+
+  // Support { personas: [...] } or bare array
+  const list = Array.isArray(obj) ? obj : Array.isArray(obj.personas) ? obj.personas : null;
+  if (!list) {
+    console.warn(`[persona-pack] ${source}: no "personas" array found`);
+    return null;
+  }
+
+  const personas = list.filter((v) => {
+    if (!isPersonaTemplate(v)) {
+      console.warn(`[persona-pack] ${source}: skipping invalid entry (missing name/role/persona)`);
+      return false;
+    }
+    return true;
+  }) as PersonaTemplate[];
+
+  if (personas.length === 0) {
+    console.warn(`[persona-pack] ${source}: 0 valid personas found`);
+    return null;
+  }
+
+  const packName = typeof obj.name === "string" ? obj.name : source;
+  const version = typeof obj.version === "string" ? obj.version : undefined;
+  return { name: packName, version, personas };
+}
+
+function loadFromFile(filePath: string): PersonaPack | null {
+  const resolved = path.isAbsolute(filePath)
+    ? filePath
+    : path.join(process.cwd(), filePath);
+
+  if (!fs.existsSync(resolved)) {
+    console.warn(`[persona-pack] file not found: ${resolved}`);
+    return null;
+  }
+
+  const content = fs.readFileSync(resolved, "utf-8");
+  const ext = path.extname(resolved).toLowerCase();
+  let raw: unknown;
+  try {
+    raw = ext === ".json" ? JSON.parse(content) : parseYaml(content);
+  } catch (e) {
+    console.warn(`[persona-pack] failed to parse ${resolved}: ${e}`);
+    return null;
+  }
+  return parseRaw(raw, resolved);
+}
+
+async function loadFromPackage(packageName: string): Promise<PersonaPack | null> {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const mod = await import(packageName);
+    // Support both default export and named export
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    const raw = mod?.default ?? mod?.personas ? { personas: mod.personas } : mod;
+    return parseRaw(raw, packageName);
+  } catch (e) {
+    console.warn(`[persona-pack] failed to load package "${packageName}": ${e}`);
+    return null;
+  }
+}
+
+function lookupLocalDefault(): PersonaPack | null {
+  for (const name of ["personas.yaml", "personas.yml", "personas.json"]) {
+    const p = path.join(process.cwd(), name);
+    if (fs.existsSync(p)) return loadFromFile(p);
+  }
+  return null;
+}
+
+export async function loadPersonaPack(): Promise<PersonaPack | null> {
+  const source = process.env.SHOAL_PERSONAS?.trim();
+
+  if (!source) {
+    // Auto-discover personas.yaml / personas.yml / personas.json in cwd
+    const pack = lookupLocalDefault();
+    if (pack) console.log(`[persona-pack] loaded "${pack.name}" (${pack.personas.length} templates)`);
+    return pack;
+  }
+
+  // Looks like a file path
+  if (source.startsWith(".") || source.startsWith("/")) {
+    const pack = loadFromFile(source);
+    if (pack) console.log(`[persona-pack] loaded "${pack.name}" (${pack.personas.length} templates) from ${source}`);
+    return pack;
+  }
+
+  // Treat as npm package name
+  const pack = await loadFromPackage(source);
+  if (pack) console.log(`[persona-pack] loaded "${pack.name}" (${pack.personas.length} templates) from package ${source}`);
+  return pack;
+}
+
+export function formatPackForPrompt(pack: PersonaPack): string {
+  const lines = [
+    `[Persona Templates from "${pack.name}"${pack.version ? ` v${pack.version}` : ""}]`,
+    "Prefer using these as a starting point. You may adapt names/personas to fit the app, but keep the role archetype intact.",
+    "",
+    ...pack.personas.map((p, i) =>
+      [
+        `${i + 1}. ${p.name} (${p.role})`,
+        `   ${p.persona}`,
+        ...(p.lenses?.length ? [`   Suggested lenses: ${p.lenses.join(", ")}`] : []),
+      ].join("\n")
+    ),
+  ];
+  return lines.join("\n");
+}

package/framework/product-discovery.ts

@@ -253,7 +253,8 @@ Guidelines for output_spec:
       let result: string;
 
       if (toolUse.name === "navigate_and_read") {
-        const { path } = toolUse.input as { path: string };
+        const { path } = toolUse.input as { path?: string };
+        if (!path) { result = "navigate_and_read: missing path"; toolResults.push({ type: "tool_result", tool_use_id: toolUse.id, content: result }); continue; }
         try {
           await page.goto(`${baseUrl}${path}`, { waitUntil: "networkidle", timeout: 10000 });
           await page.waitForTimeout(500);
@@ -268,7 +269,8 @@ Guidelines for output_spec:
         }
 
       } else if (toolUse.name === "fetch_url") {
-        const { url } = toolUse.input as { url: string };
+        const { url } = toolUse.input as { url?: string };
+        if (!url) { result = "fetch_url: missing url"; toolResults.push({ type: "tool_result", tool_use_id: toolUse.id, content: result }); continue; }
         try {
           const res = await fetch(url, { signal: AbortSignal.timeout(8000) });
           const text = await res.text();

package/framework/trackers/asana.ts

@@ -48,6 +48,19 @@ export class AsanaTracker implements IssueTracker {
     return url;
   }
 
+  async commentOnIssue(issueNumber: number | string, body: string): Promise<boolean> {
+    const res = await fetch(`https://app.asana.com/api/1.0/tasks/${issueNumber}/stories`, {
+      method: "POST",
+      headers: this.headers,
+      body: JSON.stringify({ data: { text: body } }),
+    });
+    if (!res.ok) {
+      const msg = await res.text().catch(() => "");
+      console.error(`[asana] failed to comment on task ${issueNumber} (${res.status}): ${msg.slice(0, 200)}`);
+    }
+    return res.ok;
+  }
+
   async fetchOpenIssues(): Promise<OpenIssue[]> {
     const res = await fetch(
       `https://app.asana.com/api/1.0/tasks?project=${this.projectId}&completed_since=now&opt_fields=gid,name&limit=50`,

package/framework/trackers/backlog.ts

@@ -46,6 +46,20 @@ export class BacklogTracker implements IssueTracker {
     return url;
   }
 
+  async commentOnIssue(issueNumber: number | string, body: string): Promise<boolean> {
+    const form = new URLSearchParams({ content: body });
+    const res = await fetch(this.endpoint(`/issues/${issueNumber}/comments`), {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: form,
+    });
+    if (!res.ok) {
+      const msg = await res.text().catch(() => "");
+      console.error(`[backlog] failed to comment on issue ${issueNumber} (${res.status}): ${msg.slice(0, 200)}`);
+    }
+    return res.ok;
+  }
+
   async fetchOpenIssues(): Promise<OpenIssue[]> {
     const res = await fetch(this.endpoint("/issues", {
       "projectId[]": String(this.projectId),

package/framework/trackers/github.ts

@@ -21,4 +21,22 @@ export class GitHubTracker implements IssueTracker {
   async fetchClosedIssues(): Promise<ClosedIssue[]> {
     return ghFetchClosed(this.opts);
   }
+
+  async commentOnIssue(issueNumber: number | string, body: string): Promise<boolean> {
+    const [owner, repo] = this.opts.repo.split("/");
+    const res = await fetch(`https://api.github.com/repos/${owner}/${repo}/issues/${issueNumber}/comments`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.opts.token}`,
+        "Content-Type": "application/json",
+        Accept: "application/vnd.github+json",
+      },
+      body: JSON.stringify({ body }),
+    });
+    if (!res.ok) {
+      const msg = await res.text().catch(() => "");
+      console.error(`[github] failed to comment on issue #${issueNumber} (${res.status}): ${msg.slice(0, 200)}`);
+    }
+    return res.ok;
+  }
 }

package/framework/trackers/index.ts

@@ -44,6 +44,15 @@ export class AggregatedTracker implements IssueTracker {
       return r.value;
     });
   }
+
+  async commentOnIssue(issueNumber: number | string, body: string): Promise<boolean> {
+    if (this.trackers.length === 0) return false;
+    const results = await Promise.allSettled(this.trackers.map((t) => t.commentOnIssue(issueNumber, body)));
+    for (const r of results) {
+      if (r.status === "rejected") console.error("[trackers] commentOnIssue error:", r.reason);
+    }
+    return results.some((r) => r.status === "fulfilled" && r.value === true);
+  }
 }
 
 export function buildTrackers(): AggregatedTracker {

package/framework/trackers/jira.ts

@@ -73,6 +73,25 @@ export class JiraTracker implements IssueTracker {
     }));
   }
 
+  async commentOnIssue(issueNumber: number | string, body: string): Promise<boolean> {
+    const res = await fetch(`${this.baseUrl}/rest/api/3/issue/${issueNumber}/comment`, {
+      method: "POST",
+      headers: this.headers,
+      body: JSON.stringify({
+        body: {
+          type: "doc",
+          version: 1,
+          content: [{ type: "paragraph", content: [{ type: "text", text: body }] }],
+        },
+      }),
+    });
+    if (!res.ok) {
+      const msg = await res.text().catch(() => "");
+      console.error(`[jira] failed to comment on issue ${issueNumber} (${res.status}): ${msg.slice(0, 200)}`);
+    }
+    return res.ok;
+  }
+
   async fetchClosedIssues(): Promise<ClosedIssue[]> {
     const jql = encodeURIComponent(
       `project = ${this.projectKey} AND statusCategory = Done AND labels = "feedback-agent" ORDER BY updated DESC`

package/framework/trackers/notion.ts

@@ -50,6 +50,22 @@ export class NotionTracker implements IssueTracker {
     return url;
   }
 
+  async commentOnIssue(issueNumber: number | string, body: string): Promise<boolean> {
+    const res = await fetch("https://api.notion.com/v1/comments", {
+      method: "POST",
+      headers: this.headers,
+      body: JSON.stringify({
+        parent: { page_id: String(issueNumber) },
+        rich_text: [{ type: "text", text: { content: body } }],
+      }),
+    });
+    if (!res.ok) {
+      const msg = await res.text().catch(() => "");
+      console.error(`[notion] failed to comment on page ${issueNumber} (${res.status}): ${msg.slice(0, 200)}`);
+    }
+    return res.ok;
+  }
+
   async fetchOpenIssues(): Promise<OpenIssue[]> {
     return this._queryPages("Open");
   }

package/framework/trackers/types.ts

@@ -17,4 +17,5 @@ export interface IssueTracker {
   createIssue(title: string, body: string, labels: string[]): Promise<string | null>;
   fetchOpenIssues(): Promise<OpenIssue[]>;
   fetchClosedIssues(): Promise<ClosedIssue[]>;
+  commentOnIssue(issueNumber: number | string, body: string): Promise<boolean>;
 }

package/framework/triage.ts

@@ -143,11 +143,16 @@ Organize feedback collected by multiple agents and post it as issue tickets.
 
       } else if (toolUse.name === "create_issue") {
         const { title, body, category, merged_finding_ids } = toolUse.input as {
-          title: string;
-          body: string;
-          category: string;
-          merged_finding_ids: string[] | undefined;
+          title?: string;
+          body?: string;
+          category?: string;
+          merged_finding_ids?: string[];
         };
+        if (!title || !body || !category) {
+          result = { error: "create_issue: missing required fields" };
+          toolResults.push({ type: "tool_result", tool_use_id: toolUse.id, content: JSON.stringify(result) });
+          continue;
+        }
         const mergedIds = merged_finding_ids ?? [];
         if (mergedIds.length === 0) {
           result = { error: "merged_finding_ids must contain at least one ID" };
@@ -175,7 +180,12 @@ Organize feedback collected by multiple agents and post it as issue tickets.
         }
 
       } else if (toolUse.name === "skip_finding") {
-        const { finding_id, reason } = toolUse.input as { finding_id: string; reason: string };
+        const { finding_id, reason } = toolUse.input as { finding_id?: string; reason?: string };
+        if (!finding_id) {
+          result = { error: "skip_finding: missing finding_id" };
+          toolResults.push({ type: "tool_result", tool_use_id: toolUse.id, content: JSON.stringify(result) });
+          continue;
+        }
         pendingIds.delete(finding_id);
         skippedIds.push(finding_id);
         skipped++;

package/framework/types.ts

@@ -43,6 +43,7 @@ export interface AgentLog {
   status: "completed" | "error" | "iteration_limit";
   iterations: number;
   actions: ToolAction[];
+  visitedPaths: string[];
   issuesPosted: IssuePosted[];
   regressionChecks: RegressionCheck[];
   error: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m8i-51/shoal",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "type": "module",
   "description": "Multi-agent web exploration framework — finds bugs, UX issues, and missing features by running AI agents against your app",
   "repository": {
@@ -42,7 +42,8 @@
     "express-rate-limit": "^8.5.0",
     "openai": "^6.33.0",
     "playwright": "^1.59.1",
-    "tsx": "^4.21.0"
+    "tsx": "^4.21.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",