portable-agent-layer 0.18.0 → 0.19.0

package/README.md

@@ -118,6 +118,7 @@ pal cli install               # all available (default)
 | Variable | Description |
 |----------|-------------|
 | `GEMINI_API_KEY` | For YouTube video analysis skill |
+| `XAI_API_KEY` | For Grok real-time research skill (X/web search) |
 | `PAL_HOME` | Override user state directory (default: `~/.pal` or repo root) |
 | `PAL_PKG` | Override package root |
 | `PAL_CLAUDE_DIR` | Override Claude config dir (default: `~/.claude`) |

package/assets/agents/grok-researcher.md

@@ -0,0 +1,86 @@
+---
+name: grok-researcher
+description: Real-time research via Grok/X API — fetches live data from X (Twitter), trending topics, and breaking news. Use for research requiring up-to-the-minute information about current events, public sentiment, or rapidly evolving situations.
+tools: WebSearch, WebFetch, Bash, Read, Grep, Glob
+model: sonnet
+---
+
+You are a research specialist focused on **real-time information and current events** using the Grok API and X (Twitter) data.
+
+## Primary Path — grok-search tool
+
+Use the `grok-search` tool to query the Grok API with real-time search grounding. The tool handles authentication, API formatting, and source extraction.
+
+### Current events / breaking news (web + X sources)
+
+```bash
+bun ~/.agents/skills/research/tools/grok-search.ts -- "<your research query>" --sources web,x
+```
+
+### Social sentiment / trending topics (X only)
+
+```bash
+bun ~/.agents/skills/research/tools/grok-search.ts -- "Search X for recent posts about: <topic>. Summarize key themes, notable accounts, and overall sentiment." --sources x
+```
+
+### Web-only search
+
+```bash
+bun ~/.agents/skills/research/tools/grok-search.ts -- "<query>" --sources web
+```
+
+The tool outputs findings as markdown with a `## Sources` section listing URLs and X posts.
+
+## Fallback Path — WebSearch
+
+If the grok-search tool fails (missing `XAI_API_KEY` or API error), fall back to WebSearch and WebFetch with a **recency focus**:
+
+1. **Search** using WebSearch with time-sensitive queries — prepend "2026" or "latest" or "today" to queries
+2. **Prioritize** news sources, social media aggregators, and live blogs
+3. **Fetch** the most recent results with WebFetch to extract detail
+4. **Note** in your output that you used the fallback path (no Grok API access)
+
+## Methodology
+
+1. **Assess** whether the query needs real-time data (breaking news, current events) vs X/social data (sentiment, trends, reactions)
+2. **Query** via grok-search — use `--sources web,x` for current events, `--sources x` for sentiment
+3. **Extract** key facts, dates, and source references from the output
+4. **Cross-reference** with a WebSearch if the grok-search output lacks detail or sources
+5. **Synthesize** findings with emphasis on timeliness and recency
+
+## Guidelines
+
+- Always note the recency of information — include dates and "as of" timestamps
+- Distinguish between confirmed reports and unverified social media claims
+- For trending topics, note scale (approximate engagement/post volume if available)
+- Flag rapidly evolving situations where facts may change
+- If a claim has no strong source, say so — do not fabricate citations
+- If using the fallback path, be transparent about reduced real-time capability
+
+## Output Format
+
+```markdown
+## Findings
+
+[Numbered list of discoveries, each with timestamp/recency indicator]
+- 🔴 Breaking (< 1 hour)
+- 🟠 Recent (< 24 hours)
+- 🟡 This week
+- ⚪ Older context
+
+## Sources
+
+[Verified URLs with one-line descriptions — only include URLs you actually visited or received from Grok]
+
+## Sentiment (if applicable)
+
+[Summary of public reaction/sentiment from X data, with notable voices]
+
+## Confidence
+
+[High/Medium/Low rating per finding — note if single-sourced or unverified social media]
+
+## Gaps
+
+[What couldn't be confirmed or needs monitoring as the situation develops]
+```

package/assets/skills/research/SKILL.md

@@ -9,14 +9,15 @@ argument-hint: <topic or question>
 | User says | Mode | Agents |
 |-----------|------|--------|
 | "quick research" / "minor research" | Quick | 1 agent |
-| "research" / "do research" (default) | Standard | 2 parallel agents |
-| "extensive research" / "deep research" | Extensive | 6 parallel agents |
+| "research" / "do research" (default) | Standard | 3 parallel agents |
+| "extensive research" / "deep research" | Extensive | 8 parallel agents |
 
 ## Available Researcher Agents
 
 - **claude-researcher** — academic depth, query decomposition, scholarly synthesis
 - **multi-perspective-researcher** — breadth, multiple angles, diverse viewpoints
 - **investigative-researcher** — verification rigor, triple-checks, source credibility
+- **grok-researcher** — real-time data via Grok/X API, breaking news, social sentiment (falls back to WebSearch with recency focus if no API key)
 
 ## Quick Mode
 
@@ -28,18 +29,20 @@ Wait for the result, then deliver it directly with light formatting.
 
 ## Standard Mode (Default)
 
-Craft **2 different queries** optimized for each researcher's strengths, then spawn both **in parallel (in a single message)**:
+Craft **3 different queries** optimized for each researcher's strengths, then spawn all **in parallel (in a single message)**:
 
 - Spawn `claude-researcher` with a query optimized for depth/analysis
 - Spawn `multi-perspective-researcher` with a query optimized for breadth/perspectives
+- Spawn `grok-researcher` with a query optimized for real-time data, recent developments, current state
 
 **Query design:**
 - claude-researcher: focus on authoritative sources, technical depth, how/why
 - multi-perspective-researcher: focus on different stakeholder views, trade-offs, alternatives
+- grok-researcher: focus on latest news, breaking developments, social sentiment, what's happening right now
 
 ## Extensive Mode
 
-Craft **6 queries** (2 per researcher type, each from a different angle), then spawn all **in parallel (in a single message)**:
+Craft **8 queries** (2 per researcher type, each from a different angle), then spawn all **in parallel (in a single message)**:
 
 - Spawn `claude-researcher` — angle 1: core technical depth
 - Spawn `claude-researcher` — angle 2: historical context / evolution
@@ -47,6 +50,8 @@ Craft **6 queries** (2 per researcher type, each from a different angle), then s
 - Spawn `multi-perspective-researcher` — angle 4: cross-domain connections
 - Spawn `investigative-researcher` — angle 5: verify key claims
 - Spawn `investigative-researcher` — angle 6: find contradictions / counter-evidence
+- Spawn `grok-researcher` — angle 7: real-time developments and breaking news
+- Spawn `grok-researcher` — angle 8: social sentiment, public reaction, trending discourse
 
 ## Synthesis (All Modes)
 

package/assets/skills/research/tools/grok-search.ts

@@ -0,0 +1,192 @@
+#!/usr/bin/env bun
+/**
+ * Grok Search — CLI tool for real-time search via the Grok/X API.
+ *
+ * Uses the Grok Responses API with web_search and x_search tools
+ * to fetch real-time information from the web and X (Twitter).
+ *
+ * Requires XAI_API_KEY environment variable.
+ *
+ * Usage:
+ *   bun grok-search.ts -- <query> [--sources web,x] [--max-tokens 2048]
+ *   bun grok-search.ts -- "latest AI news" --sources x
+ *   bun grok-search.ts -- "bitcoin price today" --sources web
+ */
+
+import { parseArgs } from "node:util";
+
+const API_BASE = "https://api.x.ai/v1";
+const MODEL = "grok-4-1-fast-non-reasoning";
+
+type SourceType = "web" | "x";
+type ToolType = "web_search" | "x_search";
+
+interface UrlCitation {
+  type: "url_citation";
+  url: string;
+  title?: string;
+}
+
+interface ContentPart {
+  type: string;
+  text?: string;
+  annotations?: UrlCitation[];
+}
+
+interface OutputItem {
+  type: string;
+  content?: ContentPart[];
+  status?: string;
+}
+
+interface GrokResponse {
+  output?: OutputItem[];
+  error?: { message: string };
+}
+
+function loadApiKey(): string {
+  const key = process.env.XAI_API_KEY;
+  if (!key) {
+    console.error("Error: XAI_API_KEY environment variable is not set.");
+    console.error("Get an API key at https://console.x.ai/");
+    process.exit(1);
+  }
+  return key;
+}
+
+function parseSources(raw: string): SourceType[] {
+  const valid: SourceType[] = ["web", "x"];
+  const parts = raw.split(",").map((s) => s.trim().toLowerCase());
+  const sources = parts.filter((s): s is SourceType => valid.includes(s as SourceType));
+  if (sources.length === 0) {
+    console.error(`Error: Invalid sources "${raw}". Valid: web, x`);
+    process.exit(1);
+  }
+  return sources;
+}
+
+function sourcesToTools(sources: SourceType[]): ToolType[] {
+  const map: Record<SourceType, ToolType> = { web: "web_search", x: "x_search" };
+  return sources.map((s) => map[s]);
+}
+
+export async function grokSearch(
+  query: string,
+  sources: SourceType[],
+  maxTokens: number
+): Promise<void> {
+  const apiKey = loadApiKey();
+  const tools = sourcesToTools(sources);
+
+  const body = {
+    model: MODEL,
+    input: [
+      {
+        role: "system" as const,
+        content:
+          "You are a research assistant. Provide factual, sourced answers about current events and real-time information. Always include dates and source context. Be thorough but concise.",
+      },
+      { role: "user" as const, content: query },
+    ],
+    tools: tools.map((type) => ({ type })),
+    max_output_tokens: maxTokens,
+  };
+
+  const response = await fetch(`${API_BASE}/responses`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const err = await response.text().catch(() => "");
+    console.error(`Error: HTTP ${response.status} — ${err.slice(0, 500)}`);
+    process.exit(1);
+  }
+
+  const data = (await response.json()) as GrokResponse;
+
+  if (data.error) {
+    console.error(`Error: ${data.error.message}`);
+    process.exit(1);
+  }
+
+  if (!data.output || data.output.length === 0) {
+    console.error("Error: No response output from Grok.");
+    process.exit(1);
+  }
+
+  // Extract text and citations from message output items
+  const textParts: string[] = [];
+  const citations = new Map<string, string>(); // url → title
+
+  for (const item of data.output) {
+    if (item.type !== "message" || !item.content) continue;
+    for (const part of item.content) {
+      if (part.type === "output_text" && part.text) {
+        textParts.push(part.text);
+      }
+      if (part.annotations) {
+        for (const ann of part.annotations) {
+          if (ann.type === "url_citation" && ann.url) {
+            citations.set(ann.url, ann.title ?? ann.url);
+          }
+        }
+      }
+    }
+  }
+
+  if (textParts.length === 0) {
+    console.error("Error: No text content in Grok response.");
+    process.exit(1);
+  }
+
+  console.log(textParts.join("\n\n"));
+
+  if (citations.size > 0) {
+    console.log("\n---\n## Sources\n");
+    for (const [url, title] of citations) {
+      console.log(`- [${title}](${url})`);
+    }
+  }
+}
+
+async function run() {
+  const { positionals, values } = parseArgs({
+    allowPositionals: true,
+    options: {
+      sources: { type: "string", short: "s", default: "web,x" },
+      "max-tokens": { type: "string", short: "m", default: "2048" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+
+  if (values.help || positionals.length === 0) {
+    console.log(`Grok Search — real-time search via Grok/X API
+
+Usage:
+  bun grok-search.ts -- <query> [options]
+
+Options:
+  --sources, -s <web,x>      Comma-separated source types (default: web,x)
+  --max-tokens, -m <n>       Max response tokens (default: 2048)
+  --help, -h                 Show this help
+
+Examples:
+  bun grok-search.ts -- "latest AI news"
+  bun grok-search.ts -- "bitcoin price" --sources web
+  bun grok-search.ts -- "reactions to new iPhone" --sources x`);
+    process.exit(0);
+  }
+
+  const query = positionals.join(" ");
+  const sources = parseSources(values.sources ?? "web,x");
+  const maxTokens = Number.parseInt(values["max-tokens"] ?? "2048", 10);
+
+  await grokSearch(query, sources, maxTokens);
+}
+
+if (import.meta.main) run();

package/assets/templates/settings.claude.json

@@ -20,7 +20,7 @@
       "Bash(stat //*)",
       "Bash(readlink //*)",
       "Bash(bun ~/.agents/skills/*/tools/*.ts *)",
-      "Bash(bun run tool:wisdom-frame *)"
+      "Bash(bun ~/.agents/PAL/tools/*.ts *)"
     ]
   },
   "hooks": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {