portable-agent-layer 0.18.1 → 0.20.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/create-pdf/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: create-pdf
+description: Generate a structured PDF report from a topic or content using parallel research/writing agents and md-to-pdf. Use when creating a report, generating a PDF, writing a document, or producing a structured multi-section PDF.
+argument-hint: <topic, outline, or content description>
+---
+
+## Overview
+
+Create professional PDF reports by orchestrating parallel subagents for content generation, writing results as structured markdown files, then converting to PDF via `bunx md-to-pdf`.
+
+## Workflow
+
+### Phase 1: Plan the Report Structure
+
+Based on the user's request, determine:
+
+1. **Report topic and scope**
+2. **Section breakdown** — identify 5-15 discrete sections/chapters
+3. **Output directory** — ask the user or default to `~/Documents/<kebab-case-topic>/`
+4. **Language** — detect from the user's request or ask
+5. **File naming** — each section: `YYYYMMDD_snake_case_title.md` (use today's date if no specific date applies)
+
+Present the outline to the user for approval before proceeding.
+
+### Phase 2: Parallel Content Generation
+
+Spawn **parallel subagents** to write sections simultaneously. Batch sections across agents — each agent handles 2-4 sections depending on total count.
+
+**Agent spawning rules:**
+- All agent spawns for a batch MUST be in a **single message** for true parallel execution
+- Each agent gets a clear, self-contained prompt with: section title, scope, key points to cover, tone/style, and the output file path
+- Agents write their sections directly as markdown files
+- For research-heavy reports: use `investigative-researcher`, `multi-perspective-researcher`, and `claude-researcher` agent types to get different perspectives
+- For content-heavy reports: use `general-purpose` agents with detailed writing instructions
+
+**Prompt template for each agent:**
+```
+Read [any reference files if applicable].
+Write a detailed markdown file at [output path] covering:
+- Section title: [title]
+- Scope: [what to cover]
+- Key points: [specific items to include]
+- Tone: [objective/persuasive/technical/casual]
+- Structure: Use ## for main headings, ### for sub-sections
+- Include sources with full URLs where applicable
+```
+
+**Batch sizing guide:**
+
+| Total sections | Agents | Sections per agent |
+|----------------|--------|--------------------|
+| 3-6 | 2-3 | 2 each |
+| 7-12 | 3-4 | 2-3 each |
+| 13+ | 5 | 3-4 each |
+
+### Phase 3: Overview File
+
+After all agents complete, write a `00_overview.md` file containing:
+- Report title and date
+- Methodology description
+- Table of contents linking to each section
+- Executive summary synthesizing key findings from all sections
+
+### Phase 4: Combine and Convert to PDF
+
+**Step 1: Combine all markdown files into one.**
+
+Concatenate files in order with page break dividers between sections:
+
+```bash
+cat \
+  00_overview.md \
+  <(echo -e '\n\n<div style="page-break-before: always"></div>\n\n---\n\n') \
+  YYYYMMDD_section_one.md \
+  <(echo -e '\n\n<div style="page-break-before: always"></div>\n\n---\n\n') \
+  YYYYMMDD_section_two.md \
+  ... \
+  > /tmp/combined_raw.md
+```
+
+**Step 2: Add PDF frontmatter.**
+
+Prepend YAML frontmatter with styling, then append the combined content:
+
+```bash
+cat > <report_name>.md << 'FRONTMATTER'
+---
+pdf_options:
+  format: A4
+  margin: 25mm
+  printBackground: true
+stylesheet: https://cdn.jsdelivr.net/npm/github-markdown-css/github-markdown.css
+body_class: markdown-body
+css: |-
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif; font-size: 11px; line-height: 1.6; color: #1a1a1a; }
+  h1 { font-size: 22px; border-bottom: 2px solid #333; padding-bottom: 8px; }
+  h2 { font-size: 17px; }
+  h3 { font-size: 14px; }
+  table { border-collapse: collapse; width: 100%; margin: 12px 0; }
+  th, td { border: 1px solid #ccc; padding: 6px 10px; text-align: left; font-size: 10px; }
+  th { background: #f0f0f0; }
+  blockquote { border-left: 3px solid #666; padding-left: 12px; color: #444; }
+  hr { border: none; border-top: 1px solid #ccc; margin: 20px 0; }
+  a { color: #0366d6; text-decoration: none; }
+---
+
+FRONTMATTER
+cat /tmp/combined_raw.md >> <report_name>.md
+```
+
+**Step 3: Generate the PDF.**
+
+```bash
+bunx --bun md-to-pdf <report_name>.md
+```
+
+**Step 4: Verify.**
+
+```bash
+ls -lh <report_name>.pdf
+```
+
+Report the file path and size to the user.
+
+### Phase 5: Translation (Optional)
+
+If the user requests translation to another language:
+
+1. Spawn parallel agents (same batching as Phase 2) to translate each markdown file
+2. Translated files get the same name with a `_<lang>` suffix (e.g., `_hu`, `_de`, `_es`)
+3. Keep all markdown formatting, links, and structure identical — only translate text content
+4. Keep source link titles in their original language; translate surrounding descriptive text
+5. Combine and convert the translated files to PDF using the same Phase 4 process with a `_<lang>` suffix on the final filename
+
+## Important
+
+- All subagent spawns for a batch MUST be in a **single message** for true parallel execution
+- Do NOT run agents sequentially — that defeats the purpose of parallel generation
+- Each agent writes its own files directly — the orchestrating agent only combines and converts
+- Always verify the final PDF exists and report its size
+- Use `bunx --bun md-to-pdf` (NOT npx) for PDF conversion
+- Individual markdown files are kept alongside the PDF so the user can edit and regenerate

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/package.json

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