@foldrun/core 0.4.0 → 0.5.0

package/dist/src/providers.d.ts

@@ -24,7 +24,197 @@ export interface ProviderPreset {
     note?: string;
     /** A tool loop was driven through this endpoint from this runtime. */
     verified?: boolean;
+    /** Whether the endpoint runs a server-side web search, and in whose shape.
+     *  Absent means it does not — `web.search: <that name>` is then an error a
+     *  person should see from `check`, not an empty result at 3am. */
+    search?: SearchShape;
 }
+/** Whether this endpoint will execute a server-side web search, and in whose
+ *  shape. Separate from `format` on purpose: speaking a wire is not the same
+ *  as running a tool on it. DeepSeek's endpoint is Anthropic-shaped and still
+ *  has no search at all, which is exactly the mistake this field exists to
+ *  stop `check` from letting through.
+ *
+ *   "anthropic"  executes the `web_search_20250305` server tool as Anthropic
+ *                defines it, so the runtime grants it and the endpoint answers
+ *   "plugin"     has its own switch rather than a tool (OpenRouter's web
+ *                plugin / `:online`), fulfilled natively where the underlying
+ *                model supports it and by Exa everywhere else
+ *   "openai"     the Responses-shaped `web_search` tool
+ *   "builtin_fn" Moonshot's `$web_search`, a Chat-Completions builtin_function
+ *                the client has to echo back — billed per successful call
+ *   undefined    no server-side search. Ours is the only way to the web. */
+export type SearchShape = "anthropic" | "plugin" | "openai" | "builtin_fn" | "direct";
+/** A search API the runtime calls itself, with the customer's own key.
+ *
+ *  These are not model providers — none of them serves a model — so they
+ *  live apart from PROVIDERS. `web.search:` accepts either kind of name, and
+ *  the difference decides where the search runs: a provider's server-side
+ *  tool runs on the provider's machines and is off the run record, while a
+ *  direct API is called from the run's own sandbox through the egress proxy
+ *  — the key never enters the pod, the call is on the record with its
+ *  arguments, and it works whichever model is driving. Same switch, better
+ *  audit trail. Shapes were read from each vendor's own API reference on
+ *  2026-09-16; the gallery's web tool carries the
+ *  matching request and response mapping. */
+export interface SearchApi {
+    /** The vendor's API reference the adapter was built from, the day it was
+     *  last matched to it, and what that page could not confirm. Read by
+     *  web-actions.ts; a check older than 90 days fails its test. */
+    docs?: string;
+    checked?: string;
+    gaps?: string;
+    name: string;
+    aliases?: string[];
+    title: string;
+    /** The one host the key may be sent to — the egress grant is for this. */
+    host: string;
+    endpoint: string;
+    method: "GET" | "POST";
+    /** The header the key travels in, and any prefix on the value. */
+    auth: {
+        header: string;
+        prefix?: string;
+    };
+    /** The vault name a customer stores their key under. */
+    secret: string;
+    index: string;
+    note?: string;
+    /** The API answers without a key (at a lower rate). The runner declares
+     *  the secret only when the vault has it, so a missing key is not an
+     *  error the way a declared-and-absent secret is. */
+    secretOptional?: boolean;
+    /** What the value in the vault must be, when it is not the bare key. */
+    secretFormat?: string;
+}
+export declare const SEARCH_APIS: readonly SearchApi[];
+/** Names people will try that cannot work, and why — said at `check`
+ *  rather than discovered at 3am. */
+export declare const REFUSED_WEB: Record<string, string>;
+/** Fetch APIs the runtime calls itself: a URL in, the page out, with the
+ *  customer's own key. Same seam as the search APIs — `web.fetch: jina` —
+ *  and the same trade: our own fetch is free and on the record; these are
+ *  for the failure modes ours cannot cover, chiefly a page that refuses a
+ *  plain request. Three tiers, priced accordingly: a reader (Jina,
+ *  Firecrawl) turns a page into clean markdown; a search vendor's extract
+ *  (Exa, Tavily, Parallel) reads many at once; an unblocker (Zyte, ScrapingBee) renders
+ *  behind the anti-bot walls a reader cannot pass. */
+export interface FetchApi extends Omit<SearchApi, "index"> {
+    tier: "reader" | "extract" | "unblocker";
+    /** How many URLs one call may carry. 1 means one call per page. */
+    batch: number;
+    what: string;
+}
+export declare const FETCH_APIS: readonly FetchApi[];
+/** Remote browsers: a CDP endpoint our web browse connects to instead of
+ *  the account's pod — the same tool, the same modes and actions, rendered
+ *  on the vendor's machines. `web.browse: browserbase`. The one capability
+ *  where the key cannot ride the egress proxy: CDP is a websocket, so the
+ *  wrapper holds the real value the way it already holds a cookie secret,
+ *  and creates the session itself where the vendor wants one. */
+/** What a vendor's own session can be asked for, per its docs — the keys of
+ *  `web.browse.vendor_session:` it accepts. Absent means it has no such option;
+ *  naming one is an error in `check` that says which vendors do. */
+export interface SessionSupport {
+    /** on: a proxy can be switched on; always: it is always on (true is a
+     *  no-op, false an error); the rest say which parts of a location, and
+     *  whether a proxy of your own is taken. */
+    proxy?: {
+        on?: boolean;
+        always?: boolean;
+        country?: boolean;
+        state?: boolean;
+        city?: boolean;
+        own?: boolean;
+        needsCountry?: boolean;
+        stateOrCity?: boolean;
+    };
+    captcha?: boolean;
+    stealth?: boolean;
+    region?: readonly string[];
+    /** The session's life, in seconds: [least, most]. */
+    timeout?: readonly [number, number];
+    /** Saved logins across runs: the vendor's contexts or profiles. */
+    keep?: boolean;
+    record?: boolean;
+    block?: readonly ("ads" | "trackers" | "cookies")[];
+    /** Where `options:` goes, as written: the session request's body, or the
+     *  connection URL's query. Absent: the vendor takes none. */
+    options?: "body" | "query";
+    /** web.browse settings this vendor's browser will not take. */
+    refuses?: readonly string[];
+}
+/** `web.browse.vendor_session:` — what the vendor's session is asked for.
+ *  Called `session:` until 2026-10-01, which a call's `session=` (a named
+ *  saved login) also is; the old key is still read, and check warns. */
+export interface BrowseSession {
+    proxy?: boolean | {
+        country?: string;
+        state?: string;
+        city?: string;
+        own?: string;
+    };
+    captcha?: boolean;
+    stealth?: boolean;
+    region?: string;
+    /** seconds */
+    timeout?: number;
+    keep?: string;
+    record?: boolean;
+    block?: ("ads" | "trackers" | "cookies")[];
+    options?: Record<string, unknown>;
+}
+export interface BrowserApi {
+    session?: SessionSupport;
+    /** Steps of web browse this browser cannot do, per the vendor's own docs.
+     *  Kept equal to the tool's VENDORS table by the platform's gallery test. */
+    lacks?: string[];
+    /** The vendor's API reference the adapter was built from, the day it was
+     *  last matched to it, and what that page could not confirm. Read by
+     *  web-actions.ts; a check older than 90 days fails its test. */
+    docs?: string;
+    checked?: string;
+    gaps?: string;
+    name: string;
+    aliases?: string[];
+    title: string;
+    /** How a session is reached: a REST call that returns the endpoint, or a
+     *  websocket URL the key goes straight into. */
+    how: "session" | "direct";
+    host: string;
+    secret: string;
+    secretFormat?: string;
+    what: string;
+    note?: string;
+}
+export declare const BROWSER_APIS: readonly BrowserApi[];
+/** The web's actions, in the order the docs list them. */
+export declare const WEB_ACTIONS: readonly ["search", "fetch", "browse", "crawl", "map", "extract", "answer", "monitor"];
+export type WebAction = (typeof WEB_ACTIONS)[number];
+/** A provider for one of the actions that came after search, fetch and
+ *  browse. Only what the runtime needs — the vault name of the key and the
+ *  one host it may go to — plus the docs the adapter in the `web` tool was
+ *  built from. None has been called live from here: no account holds these
+ *  keys yet, so each is as good as its docs page. */
+export interface ActionApi {
+    name: string;
+    title: string;
+    host: string;
+    secret: string;
+    docs: string;
+    checked: string;
+    gaps?: string;
+}
+export declare const ACTION_APIS: Record<"crawl" | "map" | "extract" | "answer" | "monitor", readonly ActionApi[]>;
+export declare function findActionApi(action: keyof typeof ACTION_APIS, name: string): ActionApi | undefined;
+export declare function findBrowserApi(name: string): BrowserApi | undefined;
+export declare function findFetchApi(name: string): FetchApi | undefined;
+export declare function findSearchApi(name: string): SearchApi | undefined;
+/** Whose index answers, for the ones that will answer at all. Checked against
+ *  each vendor's own documentation on 2026-09-16. Worth stating out loud
+ *  because it is the whole reason to prefer a provider's search over ours:
+ *  you are buying an index we cannot crawl, not a faster endpoint. */
+export declare const SEARCH_INDEX: Record<string, string>;
 export declare const PROVIDERS: readonly ProviderPreset[];
 /**
  * Request fields `params:` may not set.
@@ -45,3 +235,294 @@ export declare function providerPreset(name: unknown): ProviderPreset | null;
  *  without saying `format: openai`? The heuristic the checker uses to say
  *  so before a run fails with a 404 from the wrong path. */
 export declare function looksOpenAiShaped(baseUrl: string): boolean;
+/** What `web.search: <name>` in an agent's frontmatter resolves to.
+ *
+ *  Unset means ours: the account's own search engine, free, on the run
+ *  record. Naming a provider buys that provider's index instead — which is
+ *  the only reason to do it, and the reason the failure modes below are
+ *  errors rather than a quiet fallback. A desk that silently searched
+ *  nothing for a month is worse than one that refused to deploy.
+ */
+export interface SearchChoice {
+    /** null when ours answers. */
+    provider: string | null;
+    shape?: SearchShape;
+    /** Whose index answers, for the run trace and the help page. */
+    index?: string;
+    /** For a direct API: the vault name of the customer's key, and the one
+     *  host the egress proxy may fill it in for. */
+    secret?: string;
+    secretOptional?: boolean;
+    host?: string;
+    /** Set when the name cannot work; `check` prints it and refuses. */
+    error?: string;
+}
+/** `web.search: exa`, or the long form with the customer's own vault name:
+ *
+ *    web:
+ *      search:
+ *        name: exa
+ *        key: ${MY_EXA_KEY}
+ *
+ *  The same two spellings `provider:` takes. `key` is a reference, never a
+ *  value — a credential written into a markdown file is refused here, the
+ *  way it is refused everywhere else in foldrun. */
+/**
+ * `web.browse:` settings — how the browser presents itself, not what one call
+ * does.
+ *
+ *    web:
+ *      browse:
+ *        engine: firefox
+ *        user_agent: "Mozilla/5.0 …"
+ *
+ * The engine and the user agent belong in the file, not in every call. They
+ * travel together: a Cloudflare clearance cookie is bound to the user agent
+ * that earned it, so a skill repeating the UA in each call is one edit away
+ * from a session that silently stops working (Medium, 2026-09-17).
+ *
+ * `via:` (or `name:`) names a remote browser vendor, which is what this key
+ * meant when it only took a string; that spelling still works. Anything a
+ * single call decides — mode, actions, wait_for, block — stays in the call.
+ */
+export interface BrowseSettings {
+    engine?: "chrome" | "chromium" | "firefox" | "webkit" | "lightpanda" | "obscura";
+    user_agent?: string;
+    device?: string;
+    locale?: string;
+    timezone?: string;
+    /** The NAME of a vault secret holding this site's sign-in cookies, never
+     *  the cookies themselves. It sits here beside `user_agent` because the two
+     *  are one thing: a Cloudflare clearance cookie is bound to the user agent
+     *  that earned it, and a file that carries one without the other is a
+     *  session waiting to stop working. */
+    cookies?: string;
+    cookie_domain?: string;
+    /** The NAME of a vault secret holding this site's signed-in Web Storage and
+     *  IndexedDB, as JSON: `{ localStorage, sessionStorage, indexedDB }`. The
+     *  sibling of `cookies:` for the sites that keep their login in storage
+     *  rather than a cookie — Firebase writes a record to IndexedDB, MSAL can
+     *  keep tokens in sessionStorage, and a cookie jar alone opens those pages
+     *  signed out. Seeded before the page's own scripts run, never read back. */
+    storage?: string;
+    storage_origin?: string;
+    /** Named bundles of the same settings plus the per-call ones that travel
+     *  with an identity — proxy, headers, geolocation, permissions,
+     *  color_scheme, block — chosen on a call as `identity=<name>`. "As an
+     *  Australian phone" is six settings; a name says it once. Each value is a
+     *  map of text (or JSON for headers), validated here the way the block is. */
+    identities?: Record<string, Record<string, string>>;
+    /** false runs the full browser with a window, on a virtual screen where
+     *  the machine has none. Unset or true is the usual no-window browser. */
+    headless?: boolean;
+    /** Which build of the engine to run: a Chrome release channel
+     *  (`stable`/`beta`/`dev`) or a label naming a binary installed in the
+     *  image (`/opt/browser/<engine>/<version>/`). Unset is the pinned
+     *  default. Resolved in the tool, which falls back to the default and
+     *  says so when the named build is not installed. */
+    version?: string;
+    /** true keeps the browser and its open page alive between this agent's
+     *  calls in a step, so a multi-step form can be driven one step per call.
+     *  Chromium-only (chrome/chromium). Unset: each call is a fresh page, with
+     *  only cookies carried by a session. */
+    live?: boolean;
+    /** The domains this agent's browser may reach at all — pages, scripts,
+     *  fetches, sockets. A lock, not a default: a call may narrow it and never
+     *  widen it, so no page's text can talk the model past it. */
+    allowed_domains?: string[];
+    /** Actions this agent may never take (eval, download, upload, …), checked
+     *  before a browser opens. Names from WEB_BROWSE_ACTIONS, plus js. */
+    deny?: string[];
+    /** true marks the page's words in every reply with a nonce the page cannot
+     *  know, so text written to look like instructions stays the page's. */
+    boundaries?: boolean;
+    /** Workspace paths of scripts run in every page before its own. */
+    init?: string[];
+    /** Workspace paths of unpacked Chrome extensions to load (Chromium, in the step). */
+    extensions?: string[];
+    /** true gives pages WebGPU, on a software GPU where there is none. */
+    webgpu?: boolean;
+    /** true opens pages whose certificate does not check out (staging, self-signed). */
+    ignore_https_errors?: boolean;
+    /** The NAME of a vault secret whose value encrypts state= logins at rest. */
+    state_key?: string;
+    /** true records every call, so the run page always has the recording to play. */
+    video?: boolean;
+    /** false stops the tool streaming its page to the run page while the step
+     *  runs. Unset is on wherever the platform can take the frames. */
+    live_view?: boolean;
+    /** What the vendor's own session is asked for (only with a vendor).
+     *  Written `vendor_session:`; `session:` is the deprecated spelling. */
+    vendor_session?: BrowseSession;
+}
+/** Every action web browse takes, which is what `deny:` may name. The
+ *  gallery test holds this equal to the tool's own list, so a new action
+ *  cannot be undeniable, and a misspelt denial — which would deny nothing —
+ *  is refused at check time instead. */
+export declare const WEB_BROWSE_ACTIONS: readonly ["click", "dblclick", "rightclick", "hover", "check", "uncheck", "drag", "fill", "type", "press", "select", "wait", "goto", "screenshot", "pdf", "scroll", "paste", "upload", "download", "extract", "frame", "tab", "back", "forward", "reload", "focus", "clear", "highlight", "keyboard", "keydown", "keyup", "mouse", "wheel", "tap", "swipe", "clipboard", "eval", "get", "expect", "if", "mock", "unmock", "offline", "cookie", "localstorage", "sessionstorage", "viewport", "dialog", "solve", "pushstate", "insert", "webmcp", "login"];
+export declare const BROWSE_ENGINES: readonly ["chromium", "chrome", "firefox", "safari", "lightpanda", "obscura"];
+/**
+ * What each engine cannot do, and the words a refusal uses. ONE table: the
+ * tool (web/browse.mjs in the platform gallery) carries a copy that refuses a
+ * call, and `foldrun check` reads this one to refuse a `web.browse:` block
+ * that pairs an engine with something it cannot do — so the mistake is found
+ * at check time, not at 3am. The gallery test holds the tool's copy equal to
+ * this one, so neither can learn an option the other does not.
+ *
+ * An entry is what the tool prints for the option: a call argument (video,
+ * trace, block…), `mode=<mode>`, or `headless: false`. A refusal reads
+ * `<entry> <why>`. chromium and chrome can do all of it, so they have no row.
+ */
+export declare const BROWSE_ENGINE_LIMITS: Record<string, {
+    why: string;
+    cannot: readonly string[];
+}>;
+/** The refusal for one option on one engine, or null when the engine can. */
+export declare function browseEngineRefusal(engine: string, what: string): string | null;
+/** The shape of `web.browse.vendor_session:`, before anyone knows the vendor. What
+ *  the vendor can do is browseSessionProblems' question. */
+export declare function readBrowseSession(raw: unknown, key?: "vendor_session" | "session"): {
+    session?: BrowseSession;
+    error?: string;
+};
+/**
+ * Everything wrong with a session block for this vendor: a setting the
+ * vendor has no option for (naming the vendors that do), a value outside its
+ * range, and the browse settings its browser will not take. The rule the
+ * actions follow — the file is fixed, nothing is quietly dropped.
+ */
+export declare function browseSessionProblems(settings: BrowseSettings, vendor: string | null): string[];
+export declare function readBrowseSettings(raw: unknown): {
+    settings: BrowseSettings;
+    rest: unknown;
+    error?: string;
+};
+/**
+ * `web.search:` settings — what the account's own engine (SearXNG) is asked,
+ * not who answers.
+ *
+ *    web:
+ *      search:
+ *        engines: [bing, google cse, duckduckgo]
+ *        categories: [general, news]
+ *        safesearch: moderate
+ *
+ * Every SearXNG request option that changes what comes back has a key here;
+ * the ones that only change its HTML page (theme, results_on_new_tab,
+ * image_proxy, url_formatting) do not, because in JSON they do nothing and a
+ * key that does nothing is a question someone asks later. Engine and
+ * category names are checked for shape here and against the running
+ * instance by the tool (its /config), because the instance decides which of
+ * SearXNG's engines are loaded. Plugin ids are a short list that changes
+ * rarely, so a misspelt one — which would enable nothing — is refused here.
+ *
+ * The settings speak SearXNG, so they are refused beside `name:` — with
+ * `web.search: exa` they would be silently ignored.
+ */
+export interface SearchSettings {
+    /** Ask only these engines. A default: a call's `engines=` or
+     *  `categories=` replaces it, and it beats `categories` beside it — the
+     *  tool never sends SearXNG both, which would add the categories' engines
+     *  to the list. */
+    engines?: string[];
+    /** Never ask these, whatever the call says. A lock, like
+     *  web.browse.allowed_domains: a call may not widen it. */
+    exclude_engines?: string[];
+    /** The SearXNG categories to search (general, news, science, it, …),
+     *  when no engine list is in force. A default a call replaces. */
+    categories?: string[];
+    /** 0 off, 1 moderate, 2 strict. */
+    safesearch?: 0 | 1 | 2;
+    /** The default recency when a call does not say. */
+    time_range?: "day" | "week" | "month" | "year";
+    /** Seconds SearXNG waits for its engines before answering with what it has. */
+    timeout?: number;
+    /** SearXNG plugins to switch on, and off, for this agent's searches. */
+    plugins?: string[];
+    exclude_plugins?: string[];
+    /** Where the open-access DOI rewrite plugin points a paper's link. */
+    doi_resolver?: string;
+}
+/** SearXNG's plugin ids (searx/plugins/*.py, 2026-09-29). The gallery test
+ *  keeps this equal to the list the tool documents. */
+export declare const WEB_SEARCH_PLUGINS: readonly ["ahmia_filter", "calculator", "hash_plugin", "hostnames", "infinite_scroll", "oa_doi_rewrite", "self_info", "time_zone", "tor_check", "tracker_url_remover", "unit_converter"];
+/** The settings in a `web.search:` block, and the provider part with them
+ *  removed — the shape readBrowseSettings has, for the same reason. */
+export declare function readSearchSettings(raw: unknown): {
+    settings: SearchSettings;
+    rest: unknown;
+    error?: string;
+};
+/** The `web.search:` block's settings as the env the tool reads. Only what
+ *  was said travels — an unset key is SearXNG's own default. */
+export declare function searchSettingsEnv(s: SearchSettings): Record<string, string>;
+export declare function resolveSearch(name: unknown, kind?: "search" | "fetch" | "browse"): SearchChoice;
+/** A `web.browse:` block that pairs an engine with something it cannot do,
+ *  in the tool's own words (BROWSE_ENGINE_LIMITS). The block's engine is
+ *  checked against the block's settings; each identity is checked with its
+ *  own engine (or the block's) against the block's settings and its own,
+ *  because a call that picks the identity gets both. What only a call can
+ *  ask for (a mode, a trace, mocks) is the tool's to refuse. */
+export declare function browseEngineProblems(settings: BrowseSettings): string[];
+/** Every `web:` value in a frontmatter that cannot work, each as the
+ *  sentence resolveSearch gives. Computed once in core so `check`, the
+ *  deploy gate and the run all refuse the same thing in the same words —
+ *  the timezone rule's shape. Empty when all are unset or answerable. */
+export declare function webProblems(front: Record<string, unknown>): string[];
+/**
+ * The engines the runner image was built with, as the deploy wrote them into
+ * FOLDRUN_RUNNER_ENGINES (foldrun-infra dev/ci/runner-engines.sh): a comma
+ * list of names, each with `=<version>` where the image's manifest
+ * (/opt/browser/engines.json) has a dotted version —
+ * `chromium=153.0.8010.12,chrome=154.0.8037.58,firefox,lightpanda=0.4.1`.
+ * Null when unset.
+ */
+export declare function runnerEngines(raw?: string | undefined): Record<string, string | null> | null;
+/** The Chrome major a user-agent string claims — `Chrome/153.0.0.0` → 153 —
+ *  or null for one that names no Chrome (Firefox, Safari, an iPhone). */
+export declare function chromeMajorOf(ua: string): number | null;
+/**
+ * A pinned `user_agent:` that claims another Chrome than the one that will
+ * send it. The tool's own default follows the installed Chrome (its
+ * chromiumVersion()), so only a pinned string can drift — and it drifts
+ * every time the image's Chrome moves (stable is unpinned, a new major every
+ * four weeks). A site then sees `Chrome/153` in the User-Agent header beside
+ * `"Google Chrome";v="154"` in the client hints the browser still sends, and
+ * a JavaScript engine that is 154's: the mismatch bot checks look for.
+ * `chrome` is the image's version of that browser (runnerEngines().chrome,
+ * or .chromium for engine chromium); null — an image that did not say —
+ * warns about nothing.
+ */
+export declare function userAgentDrift(ua: string | undefined, chrome: string | null | undefined, where: string, browser?: string): string | null;
+/**
+ * What in a `web:` block works today but should change — never a refusal.
+ * `check` prints these as warnings and the deploy reports them beside its
+ * outward-gate warnings. `opts.chrome` / `opts.chromium`: the runner image's
+ * Google Chrome and Playwright Chromium versions, when known
+ * (FOLDRUN_RUNNER_ENGINES on the platform, /api/version from the CLI); an
+ * engine whose version is unknown is not compared.
+ */
+export declare function webWarnings(front: Record<string, unknown>, opts?: {
+    chrome?: string | null;
+    chromium?: string | null;
+}): string[];
+/**
+ * The agent's `web:` block, read once for everyone — the runner, `check`
+ * and the deploy gate:
+ *
+ *    tools: [web]
+ *    web:
+ *      actions: [search, fetch, crawl]   # what it may do; all when absent
+ *      search: brave                     # who does each; absent is foldrun
+ *      browse: { engine: firefox }       # search and browse also take their settings
+ *
+ * `raw` is each action's value as written. Browse alone cascades: the
+ * workspace's (or account's) `web: {browse: …}` applies when the agent's
+ * says nothing. A per-action key outside the block (`web_search:`) is not
+ * read; it is a problem naming the block.
+ */
+export declare function webConfig(front: Record<string, unknown>, workspaceFront?: Record<string, unknown>): {
+    actions: WebAction[] | null;
+    raw: Record<WebAction, unknown>;
+    problems: string[];
+};