tabstack

Name: tabstack
Author: Mozilla

v0.2.0

Browsing infrastructure for AI agents on the iii bus — tabstack::* functions turn any URL into clean markdown or structured JSON, and run cited web research through the hosted Tabstack API.

license: Apache-2.0Published 19d agoweb scraping extraction markdown research browser agents url

Install

bash

iii trigger compose::add worker=tabstack@next

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Agent-ready brief for v0.2.0

Install, config, dependencies, readme, skills and API reference, all in one place. Fetch as agent-context.md for an LLM to consume.

Full markdown

Open as agent-context.md

The same content rendered as discrete blocks below is exposed as a single markdown document at /workers/tabstack.md?version=next. Paste it into an LLM prompt or pipe it through curl from a worker.

Install

iii trigger compose::add worker=tabstack@0.2.0

Dependencies

Dependency · 1Version

configurationlatest

Readme

README.md

Tabstack

Tabstack reads the sources, checks what is missing, reconciles conflicting information, and returns a cited answer in one call. The same API also returns clean text, matching JSON, or a completed public web task.

Backed by the hosted Tabstack API, built by Mozilla. You bring a Tabstack API key; usage is billed to your own account. Full endpoint semantics live in the Tabstack API reference.

Install

iii trigger compose::add worker=tabstack

iii trigger compose::add resolves the worker and its dependencies, writes exact declarations to worker-compose.yaml, and reconciles the Compose project.

Configuration

The worker needs a Tabstack API key. Sign up free — the trial needs no card.

It registers a schema and seed in the configuration worker on boot, so the key can be set from the Console or with configuration::set:

tabstack:
  api_key: your-api-key                 # required; no default
  base_url: https://api.tabstack.ai/v1  # override only for testing

If no key is stored, the worker falls back to the TABSTACK_API_KEY environment variable. With neither set, every call fails with tabstack_not_configured.

Note the configuration entry is namespaced: in the default namespace the id is default-tabstack, not tabstack.

Quickstart

Read a page as markdown:

iii trigger tabstack::extract-markdown url=https://example.com

{
  "ok": true,
  "url": "https://example.com",
  "content": "---\ntitle: Example Domain\n---\n\nThis domain is for use in documentation examples..."
}

Pull structured data out of a page by describing the shape you want:

iii trigger tabstack::extract-json url=https://news.ycombinator.com \
  json_schema='{"type":"object","properties":{"stories":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer"},"title":{"type":"string"},"points":{"type":"integer"}}},"maxItems":5}}}'

{
  "ok": true,
  "data": {
    "stories": [
      { "rank": 1, "title": "Web Search API", "points": 318 },
      { "rank": 2, "title": "The future of independence is interdependence", "points": 41 }
    ]
  }
}

From another worker:

import { registerWorker } from 'iii-sdk';

const iii = registerWorker('ws://localhost:49134', { workerName: 'my-worker' });

const result = await iii.trigger({
  function_id: 'tabstack::extract-markdown',
  payload: { url: 'https://example.com' },
  timeoutMs: 60_000,
});

Raise the call timeout. iii's default is 30 seconds. extract-markdown and extract-json usually return well inside that, but effort: "max" renders the page in a full browser and is documented at up to 60 seconds, and automate runs for minutes. A caller on the default gives up before the work finishes.

From the CLI it is a flag, not a key/value pair — --timeout-ms goes before the function name. timeout_ms=… as a pair is passed through as payload and silently has no effect:

iii trigger --timeout-ms 300000 tabstack::automate task='...' url='...'

From another worker it is timeoutMs on the trigger call.

The functions

Function	Takes	Returns
`tabstack::extract-markdown`	`url`	the page as markdown in `content`
`tabstack::extract-json`	`url`, `json_schema`	matching object in `data`
`tabstack::generate-json`	`url`, `json_schema`, `instructions`	matching object in `data`
`tabstack::research`	`query`	a cited markdown answer in `report`
`tabstack::automate`	`task`	the agent's final answer in `result`

See the Tabstack API reference for more details about each function.

Researching rather than reading

research is the one function that does not take a url. Give it a question and it searches, reads and synthesises an answer with inline citations:

iii trigger --timeout-ms 180000 tabstack::research query='What is the iii.dev worker registry?'

{
  "ok": true,
  "report": "The iii.dev worker registry is a central online repository located at `workers.iii.dev` ... [1][2]",
  "metadata": {
    "citedPages": [{ "id": "5YI5Rc", "title": "iii worker - iii.dev", "url": "https://workers.iii.dev/" }],
    "mode": "fast",
    "totalPagesAnalyzed": 3
  }
}

Completing a task in a browser

automate drives a real browser from a plain-language task: navigate, read, fill forms, work through multi-step flows.

iii trigger --timeout-ms 300000 tabstack::automate \
  task='Fill in the contact form with the supplied details' \
  url=https://example.com/contact \
  data='{"name":"Alex Johnson","email":"alex@example.com"}' \
  guardrails='fill the fields only, do not submit' \
  trusted_hostnames='["example.com"]'

{ "ok": true, "result": "The name and email fields have been populated. The form was not submitted." }

Put every value the task needs in data. A value that is missing may be filled with something the agent invented rather than reported back, so do not rely on it to ask you.

guardrails is worth using. It constrains what the agent may do — "browse and extract only, do not submit any form" is a sensible default for anything read-only.

trusted_hostnames lifts the action firewall for fills and submissions on the hosts you list. Page content on those hosts can steer the agent, so list only sites you would trust with whatever is in data.

Runs take minutes. The timeout is a CLI flag, not a payload key — see above.

Choosing between extract-json and generate-json

extract-json takes a schema alone and is the cheaper of the two. Reach for it whenever the schema says enough about what you want.

generate-json additionally takes natural-language instructions, for when the schema alone cannot express how values should be derived — ranking, classifying, or comparing across a whole page. "Pick the dominant theme across these stories" needs an instruction; a bare schema cannot say it.

Reading the result

Every function returns an envelope. On success, ok is true and the result sits alongside it. When Tabstack returns an error, ok is false and the call still succeeds at the iii level:

{ "ok": false, "error": "tabstack_invalid_request", "message": "invalid URL" }

`error`	Meaning
`tabstack_auth_failed`	key missing, wrong or revoked
`tabstack_out_of_credits`	account balance exhausted
`tabstack_rate_limited`	too many requests; back off and retry
`tabstack_not_found`	endpoint not found
`tabstack_invalid_request`	bad URL, malformed schema, or similar
`tabstack_upstream_error`	Tabstack-side failure; safe to retry
`tabstack_automation_failed`	the browser task could not be completed; `message` says why
`tabstack_incomplete_stream`	the response ended before finishing (`research`, `automate`)

Failures are returned rather than thrown so callers can branch on error. The Node SDK collapses every thrown handler error to invocation_failed, which would make these indistinguishable.

Two cases are thrown, because no useful result exists: tabstack_not_configured when no API key is available, and tabstack_unreachable / tabstack_timeout when the request never reached Tabstack at all.

These codes map onto the HTTP statuses in the Tabstack API reference, which is the authority on what each endpoint can return.

API reference (JSON)

agent-api-reference.json

{
  "functions": [
    {
      "description": "Drive a browser with a plain-language task: navigate, read, fill forms, complete multi-step flows. Returns the agent's final answer. Supply every value the task needs in `data` — a value that is missing may be filled with something the agent invented rather than reported, so do not rely on it to ask. Runs for minutes, so raise your call timeout well above the 30s default.",
      "metadata": {},
      "name": "tabstack::automate",
      "request_schema": {
        "properties": {
          "data": {
            "description": "Values the task may need, e.g. form fields. Supply these up front: if the agent needs something that is missing, the call returns tabstack_input_required naming the fields rather than guessing.",
            "type": "object"
          },
          "guardrails": {
            "description": "Safety constraints, e.g. \"browse and extract only, do not submit any form\".",
            "type": "string"
          },
          "max_iterations": {
            "description": "Cap on task iterations. Default 50.",
            "type": "integer"
          },
          "task": {
            "description": "What to do, in plain language. e.g. \"Find the top 3 trending repositories and extract their names and star counts\".",
            "type": "string"
          },
          "trusted_hostnames": {
            "description": "Hostnames where filling and submitting is permitted. Page content on these hosts can steer the agent, so list only sites you trust with the data in `data`.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "url": {
            "description": "Page to start from.",
            "type": "string"
          }
        },
        "required": [
          "task"
        ],
        "type": "object"
      },
      "response_schema": {
        "properties": {
          "error": {
            "description": "Failure code, present only when ok is false. One of: tabstack_auth_failed, tabstack_out_of_credits, tabstack_rate_limited, tabstack_not_found, tabstack_invalid_request, tabstack_upstream_error.",
            "type": "string"
          },
          "message": {
            "description": "Human-readable failure detail, present only when ok is false.",
            "type": "string"
          },
          "ok": {
            "description": "True on success. When false, read `error` and `message` instead of the result fields.",
            "type": "boolean"
          },
          "result": {
            "description": "The agent's final answer once the task completed.",
            "type": "string"
          }
        },
        "required": [
          "ok"
        ],
        "type": "object"
      }
    },
    {
      "description": "Pull structured data off a page into a shape you define. Supply a JSON Schema and get back matching data. This is the cheaper of the two JSON functions — reach for it whenever the schema alone says enough about what you want.",
      "metadata": {},
      "name": "tabstack::extract-json",
      "request_schema": {
        "properties": {
          "effort": {
            "default": "standard",
            "description": "Speed against capability. \"min\" is fastest with no fallback (1-5s); \"standard\" is balanced (3-15s); \"max\" renders in a full browser for JS-heavy sites (15-60s).",
            "enum": [
              "min",
              "standard",
              "max"
            ],
            "type": "string"
          },
          "json_schema": {
            "description": "JSON Schema describing the shape you want back. Drives the structure of `data`.",
            "type": "object"
          },
          "nocache": {
            "default": false,
            "description": "Bypass cache and refetch.",
            "type": "boolean"
          },
          "url": {
            "description": "URL to extract structured data from.",
            "type": "string"
          }
        },
        "required": [
          "url",
          "json_schema"
        ],
        "type": "object"
      },
      "response_schema": {
        "properties": {
          "data": {
            "description": "The extracted or generated object, matching the `json_schema` you supplied.",
            "type": "object"
          },
          "error": {
            "description": "Failure code, present only when ok is false. One of: tabstack_auth_failed, tabstack_out_of_credits, tabstack_rate_limited, tabstack_not_found, tabstack_invalid_request, tabstack_upstream_error.",
            "type": "string"
          },
          "message": {
            "description": "Human-readable failure detail, present only when ok is false.",
            "type": "string"
          },
          "ok": {
            "description": "True on success. When false, read `error` and `message` instead of the result fields.",
            "type": "boolean"
          }
        },
        "required": [
          "ok"
        ],
        "type": "object"
      }
    },
    {
      "description": "Fetch a URL and return it as clean markdown. Use this to read a web page. Prefer it over extract-json when you want the prose rather than specific fields.",
      "metadata": {},
      "name": "tabstack::extract-markdown",
      "request_schema": {
        "properties": {
          "content": {
            "default": "main",
            "description": "Content scope. \"main\" returns the main article content; \"full\" returns the whole page including navigation, footer and links.",
            "enum": [
              "main",
              "full"
            ],
            "type": "string"
          },
          "effort": {
            "default": "standard",
            "description": "Speed against capability. \"min\" is fastest with no fallback (1-5s); \"standard\" is balanced (3-15s); \"max\" renders in a full browser for JS-heavy sites (15-60s).",
            "enum": [
              "min",
              "standard",
              "max"
            ],
            "type": "string"
          },
          "metadata": {
            "default": false,
            "description": "Include Open Graph and HTML metadata as a separate response field.",
            "type": "boolean"
          },
          "nocache": {
            "default": false,
            "description": "Bypass cache and refetch.",
            "type": "boolean"
          },
          "url": {
            "description": "URL to fetch and convert to markdown.",
            "type": "string"
          }
        },
        "required": [
          "url"
        ],
        "type": "object"
      },
      "response_schema": {
        "properties": {
          "content": {
            "description": "The markdown content, with metadata as YAML frontmatter by default.",
            "type": "string"
          },
          "error": {
            "description": "Failure code, present only when ok is false. One of: tabstack_auth_failed, tabstack_out_of_credits, tabstack_rate_limited, tabstack_not_found, tabstack_invalid_request, tabstack_upstream_error.",
            "type": "string"
          },
          "message": {
            "description": "Human-readable failure detail, present only when ok is false.",
            "type": "string"
          },
          "metadata": {
            "description": "Page metadata. Present only when `metadata` was true.",
            "type": "object"
          },
          "ok": {
            "description": "True on success. When false, read `error` and `message` instead of the result fields.",
            "type": "boolean"
          },
          "url": {
            "description": "The URL that was converted.",
            "type": "string"
          }
        },
        "required": [
          "ok"
        ],
        "type": "object"
      }
    },
    {
      "description": "Produce structured output from a page using natural-language instructions alongside a JSON Schema. Use it when the schema alone cannot say how the values should be derived — ranking, classifying, comparing across a whole page, or any case where you need to steer the interpretation. Costs more than extract-json, so prefer that one when a bare schema is sufficient.",
      "metadata": {},
      "name": "tabstack::generate-json",
      "request_schema": {
        "properties": {
          "effort": {
            "default": "standard",
            "description": "Speed against capability. \"min\" is fastest with no fallback (1-5s); \"standard\" is balanced (3-15s); \"max\" renders in a full browser for JS-heavy sites (15-60s).",
            "enum": [
              "min",
              "standard",
              "max"
            ],
            "type": "string"
          },
          "instructions": {
            "description": "What to produce from the page. This is the reasoning task, not a selector.",
            "type": "string"
          },
          "json_schema": {
            "description": "JSON Schema describing the shape you want back. Drives the structure of `data`.",
            "type": "object"
          },
          "nocache": {
            "default": false,
            "description": "Bypass cache and refetch.",
            "type": "boolean"
          },
          "url": {
            "description": "URL to reason over.",
            "type": "string"
          }
        },
        "required": [
          "url",
          "json_schema",
          "instructions"
        ],
        "type": "object"
      },
      "response_schema": {
        "properties": {
          "data": {
            "description": "The extracted or generated object, matching the `json_schema` you supplied.",
            "type": "object"
          },
          "error": {
            "description": "Failure code, present only when ok is false. One of: tabstack_auth_failed, tabstack_out_of_credits, tabstack_rate_limited, tabstack_not_found, tabstack_invalid_request, tabstack_upstream_error.",
            "type": "string"
          },
          "message": {
            "description": "Human-readable failure detail, present only when ok is false.",
            "type": "string"
          },
          "ok": {
            "description": "True on success. When false, read `error` and `message` instead of the result fields.",
            "type": "boolean"
          }
        },
        "required": [
          "ok"
        ],
        "type": "object"
      }
    },
    {
      "description": "Answer a question by researching the live web, returning a markdown report with inline citations. Use this when the answer is spread across sources you have not identified yet; use extract-markdown when you already know the page to read. Runs for tens of seconds or more, so raise your call timeout.",
      "metadata": {},
      "name": "tabstack::research",
      "request_schema": {
        "properties": {
          "fetch_timeout": {
            "description": "Seconds to allow for fetching each web page.",
            "type": "integer"
          },
          "mode": {
            "default": "fast",
            "description": "How much work to do. \"fast\" answers quickly; \"balanced\" researches more thoroughly and costs more.",
            "enum": [
              "fast",
              "balanced"
            ],
            "type": "string"
          },
          "nocache": {
            "description": "Bypass cache and research afresh.",
            "type": "boolean"
          },
          "query": {
            "description": "The question to answer. Maximum 10,000 characters.",
            "type": "string"
          }
        },
        "required": [
          "query"
        ],
        "type": "object"
      },
      "response_schema": {
        "properties": {
          "error": {
            "description": "Failure code, present only when ok is false. One of: tabstack_auth_failed, tabstack_out_of_credits, tabstack_rate_limited, tabstack_not_found, tabstack_invalid_request, tabstack_upstream_error.",
            "type": "string"
          },
          "message": {
            "description": "Human-readable failure detail, present only when ok is false.",
            "type": "string"
          },
          "metadata": {
            "description": "Cited pages, executed queries and metrics for the run. Page `fullText` is stripped; fetch a cited url with extract-markdown if you need the source text.",
            "type": "object"
          },
          "ok": {
            "description": "True on success. When false, read `error` and `message` instead of the result fields.",
            "type": "boolean"
          },
          "report": {
            "description": "The answer as markdown, with inline citations to the sources used.",
            "type": "string"
          }
        },
        "required": [
          "ok"
        ],
        "type": "object"
      }
    }
  ],
  "triggers": []
}

Install

Full markdown

Install

Dependencies

Readme

Tabstack

Install

Configuration

Quickstart

The functions

Researching rather than reading

Completing a task in a browser

Choosing between extract-json and generate-json

Reading the result

API reference (JSON)

Search the registry