pi-tinyfish

TinyFish Web Agent tools for pi — search, fetch, and goal-driven browser automation.

Tools

| Tool | API | Description | |------|-----|-------------| | tinyfish_search | Search API | Web search with ranked results, snippets, and URLs | | tinyfish_fetch | Fetch API | Render URLs and extract clean content (markdown/html/json) | | tinyfish_agent_run | Agent API (SSE) | Goal-driven browser automation with real-time progress | | tinyfish_run_get | Runs API | Query a specific automation run's status and result | | tinyfish_run_list | Runs API | List/search historical automation runs | | tinyfish_run_cancel | Runs API | Cancel an in-progress run |

Setup

1. Install:

pi install npm:pi-tinyfish
# or local:
pi install ./pi-tinyfish

2. Configure your TinyFish API key (get one from agent.tinyfish.ai/api-keys):

/tinyfish-login

3. Check status:

/tinyfish-status

Configuration

API key and defaults are stored in ~/.pi/agent/pi-tinyfish.json (permissions 0600). No global environment variable required.

{
  "apiKey": "tf_xxx",
  "defaultLocation": "US",
  "defaultLanguage": "en",
  "defaultFetchFormat": "markdown",
  "defaultBrowserProfile": "lite"
}

Fallback: TINYFISH_API_KEY env var for CI / debugging.

Commands

| Command | Description | |---------|-------------| | /tinyfish-login | Enter your TinyFish API key interactively | | /tinyfish-status | Show configuration status (key never exposed) | | /tinyfish-logout | Remove stored API key |

Development

npm install          # peer deps
npm test             # vitest
pi -e .             # load extension for testing

Tool Result UI

Tool results follow a three-layer information model so the LLM gets the full picture while the user only sees what they need on screen:

| Layer | Field | Audience | Purpose | |-------|-------|----------|---------| | Full data | content | LLM | Complete output enters the next conversation turn — never truncated for the LLM | | Structured | details | Renderer & state | Compact summary (status, count, urls) used by renderResult and persisted in session state | | Visual | renderResult | Human | Default view is a one-line summary; press Ctrl+O (app.tools.expand) to expand the full markdown |

This applies to all six tools. See src/tools/README.md for the per-tool contract.

Directory layout

index.ts               # Standard package entry — re-exports src/index.ts
src/
  index.ts          # Extension implementation — registers tools and /commands
  api.ts            # TinyFish REST/SSE client
  config.ts         # ~/.pi/agent/pi-tinyfish.json read/write
  format.ts         # Output text formatters
  render.ts         # Shared renderResult helpers (collapsible markdown)
  tools/
    search.ts       # tinyfish_search
    fetch.ts        # tinyfish_fetch
    agent-run.ts    # tinyfish_agent_run
    run-get.ts      # tinyfish_run_get
    run-list.ts     # tinyfish_run_list
    run-cancel.ts   # tinyfish_run_cancel
skills/
  tinyfish/
    SKILL.md        # Agent-facing usage guide

Design notes

• All six tools are synchronous — execute() awaits the full response. No background runs, no pi.sendMessage injection. The LLM sees results in the natural tool-call return.
• details is the source of truth for collapsible summaries; content is the source of truth for LLM context. They are intentionally not derived from each other.
• truncateOutput (format.ts) only trims content when the caller passes maxBytes; it never silently strips data the LLM needs.