@outcrawl/sdk 0.1.0

package/dist/types/_deps/core/registry.d.ts

@@ -0,0 +1,466 @@
+/**
+ * The capability registry.
+ *
+ * One list, four surfaces. The API is the truth; the SDK, MCP server and CLI
+ * are generated or checked against this array. The failure mode it exists to
+ * prevent is a feature landing in the SDK and reaching MCP six months later —
+ * which has already happened once, at a smaller scale, with session replay.
+ *
+ * Adding a capability means adding one row here and letting every surface fail
+ * until it carries it. Removing a column from a row is not allowed — but two
+ * of the columns are legitimately empty, and that is a different fact.
+ *
+ * `mcpTool` and `cliCommand` are nullable, because a capability appears in a
+ * surface only where its user can act on it: an assistant must never manage a
+ * credit card or connect an integration, and the CLI serves a human and CI and
+ * does not need a replay viewer. The matrix is in `docs/AGENTS.md` and it is
+ * the design, not a backlog. What is still forbidden is the OMISSION: both
+ * fields are required-and-nullable, so a row that has no MCP tool has to write
+ * `mcpTool: null` and a row that forgot does not compile. See the field docs.
+ *
+ * **A deliberate `null` and a forgotten field must not be spellable the same
+ * way.** This is the third time this codebase has arrived at that rule — after
+ * `streamsWhen` below, and after `AgentBindingOptions`, where `model`,
+ * `solveChallenge`, `tabs` and `pointerSink` were each optional, each omitted
+ * at a composition root, and each absent in production for the life of a
+ * feature with nothing failing. Somebody being tidy will propose `?:` here
+ * again; the answer is no, and this paragraph is why.
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface Capability {
+    /** Dotted, stable. The key every surface addresses this capability by. */
+    name: string;
+    method: HttpMethod;
+    /** REST path. `{id}` marks a path parameter. */
+    path: string;
+    /**
+     * One line. This is product copy for an audience of one model — MCP tool
+     * descriptions are prompts, and a model picks between tools on this text
+     * alone, so each says what the tool is *not* for.
+     */
+    summary: string;
+    /**
+     * MCP tool name, or `null` when no MCP tool should exist.
+     *
+     * Required rather than optional, for the same reason as `streamsWhen` below:
+     * `mcpTool?: string` compiles on a row that omits it, so "we decided this
+     * capability has no tool" and "nobody said" would be the same bytes. They are
+     * not the same fact — the first is the `docs/AGENTS.md` matrix and the second
+     * is the defect this file exists to prevent. Never the empty string, which
+     * would be a third spelling of the same idea; `core/test/registry.test.ts`
+     * refuses it.
+     *
+     * The nulls do not cost the exhaustiveness that makes this registry worth
+     * having. They split it: {@link McpCapabilityName} and
+     * {@link CliCapabilityName} are derived from these two columns, and MCP and
+     * the CLI key their per-capability tables by those instead of by
+     * `CapabilityName`. So a row that declares a tool still fails the MCP build
+     * until it has a shape and copy, and a row that declares `null` cannot
+     * acquire one — the key is not in the union, and an object literal that
+     * offers it is an excess property.
+     */
+    mcpTool: string | null;
+    /**
+     * CLI invocation without the `outcrawl` prefix, or `null` when no command
+     * should exist. Required-and-nullable on the same terms as `mcpTool`.
+     */
+    cliCommand: string | null;
+    /**
+     * Every capability is authenticated: the router checks an API key and an IP
+     * allowlist before it picks a worker. Health and version endpoints are not
+     * capabilities and are not listed here.
+     */
+    requiresAuth: boolean;
+    /**
+     * How the response body is framed.
+     *
+     * `'json'` is one object. `'ndjson'` is a header frame followed by zero or
+     * more item frames, one JSON object per line, delivered as they are produced.
+     *
+     * This field exists because the registry could not express it, and two
+     * surfaces immediately disagreed about the same capability: the SDK read
+     * crawl as a stream because §7 specifies `for await`, while the CLI declined
+     * to offer `--stream` because no row said it was one. Both reasoned correctly
+     * from an incomplete registry. A capability whose framing is undeclared is
+     * one every surface has to guess about, which is the failure this registry
+     * exists to prevent.
+     */
+    framing: 'json' | 'ndjson';
+    /**
+     * The request field that switches this row to `'ndjson'`, when it has one.
+     *
+     * Three rows stream and they do not stream the same way. `crawl` is always
+     * ndjson. `agent` is json unless the request sets `stream`. `sessions.get` is
+     * json unless it sets `live`. Declaring only a single default framing was a
+     * half-fix: it said something false about the two rows that switch, and left
+     * a surface to invent the field name — which is exactly what happened, since
+     * `live` reached the SDK before it reached this registry.
+     *
+     * `null` means the framing above is the only one this row produces.
+     * Required rather than optional on purpose: an optional field that every
+     * surface is supposed to consult is the field that gets forgotten, and on a
+     * const-asserted array it is not even reachable on the rows that omit it —
+     * MCP hit exactly that. A new row must now state whether it streams.
+     */
+    streamsWhen: string | null;
+}
+/**
+ * Not listed, deliberately: the live Playwright `page` — `page.act`,
+ * `page.observe`, `page.hands`. It only exists in the SDK because it needs a
+ * live CDP connection in the caller's own process. API, MCP and CLI reach the
+ * same capabilities through `agent` and `scrape`, which run the loop on our
+ * side. That is a difference in kind, not an omission.
+ */
+export declare const CAPABILITIES: readonly [{
+    readonly name: "scrape";
+    readonly method: "POST";
+    readonly path: "/v1/scrape";
+    readonly summary: "Fetch one URL and return clean content in the requested formats. Use for a single known page; not for following links, and not for tasks that need decisions.";
+    readonly mcpTool: "outcrawl_scrape";
+    readonly cliCommand: "scrape";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "crawl";
+    readonly method: "POST";
+    readonly path: "/v1/crawl";
+    readonly summary: "Walk a site from a seed URL and stream every page as it is scraped. Use when the set of URLs is unknown; not for one page, and not for content behind a login flow.";
+    readonly mcpTool: "outcrawl_crawl";
+    readonly cliCommand: "crawl";
+    readonly requiresAuth: true;
+    readonly framing: "ndjson";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "search";
+    readonly method: "POST";
+    readonly path: "/v1/search";
+    readonly summary: "Web search, optionally with every hit rendered through our scrape pipeline. Use to find pages; not to read one you already have a URL for.";
+    readonly mcpTool: "outcrawl_search";
+    readonly cliCommand: "search";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "monitors.create";
+    readonly method: "POST";
+    readonly path: "/v1/monitors";
+    readonly summary: "Watch a URL on a schedule and notify on real change via Discord, Slack or webhook. Use for recurring checks; not for a one-off comparison.";
+    readonly mcpTool: "outcrawl_monitor_create";
+    readonly cliCommand: "monitors create";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "monitors.list";
+    readonly method: "GET";
+    readonly path: "/v1/monitors";
+    readonly summary: "List monitors with their last check status.";
+    readonly mcpTool: "outcrawl_monitor_list";
+    readonly cliCommand: "monitors ls";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "monitors.delete";
+    readonly method: "DELETE";
+    readonly path: "/v1/monitors/{id}";
+    readonly summary: "Delete a monitor and stop its schedule. Snapshots are discarded.";
+    readonly mcpTool: "outcrawl_monitor_delete";
+    readonly cliCommand: "monitors rm";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "agent";
+    readonly method: "POST";
+    readonly path: "/v1/agent";
+    readonly summary: "Submit a natural-language browser task as a JOB and get an id back in milliseconds. The run is not held open on this call and hours are normal: read outcrawl_agent_status for the answer, outcrawl_agent_results for the records it appended, and outcrawl_agent_cancel to stop it. Use when the page needs decisions or interaction; not for plain reading, where scrape is far cheaper.";
+    readonly mcpTool: "outcrawl_agent";
+    readonly cliCommand: "agent";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "agent.get";
+    readonly method: "GET";
+    readonly path: "/v1/agent/{id}";
+    readonly summary: "Where one run has got to: status, the plan it stated, what it has spent, and its answer once it has one. Safe to call as often as you like — it is a row read, not a browser. Use it to find out whether a submitted run has finished; not to fetch the records it produced, which is outcrawl_agent_results.";
+    readonly mcpTool: "outcrawl_agent_status";
+    readonly cliCommand: "agent status";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "agent.events";
+    readonly method: "GET";
+    readonly path: "/v1/agent/{id}/events";
+    readonly summary: "Everything a run has done, in order, from a cursor: steps, findings, dead ends, plan changes. Ask for the verbosity you want with `level`, and resume with the `after` sequence you last saw rather than re-reading from the start. Use it to watch or audit a run; not to get its answer, which is outcrawl_agent_status.";
+    readonly mcpTool: "outcrawl_agent_events";
+    readonly cliCommand: "agent events";
+    readonly requiresAuth: true;
+    readonly framing: "ndjson";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "agent.results";
+    readonly method: "GET";
+    readonly path: "/v1/agent/{id}/results";
+    readonly summary: "The records a run appended, a page at a time, oldest first. Records land DURING the run, so this answers before the run has finished and a killed run still delivers what it bought. Use it for the data; not for whether the run is done, which is outcrawl_agent_status.";
+    readonly mcpTool: "outcrawl_agent_results";
+    readonly cliCommand: "agent results";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "agent.cancel";
+    readonly method: "POST";
+    readonly path: "/v1/agent/{id}/cancel";
+    readonly summary: "Stop a run. It settles with whatever it had reached and everything it already appended stays yours; work already performed is still billed, because caps are the protection and not a refund argued afterwards. Use it to stop spending; not to delete the output.";
+    readonly mcpTool: "outcrawl_agent_cancel";
+    readonly cliCommand: "agent cancel";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "agent.control";
+    readonly method: "POST";
+    readonly path: "/v1/agent/{id}/control";
+    readonly summary: "Take the wheel of a live run, or hand it back. Taking it PAUSES the agent where it stands with the browser still open, and answers the URL a person drives it at; handing it back resumes the same run on whatever page you left it on. Use it when a run needs a human for one step — a login you will not automate, a form only you can fill; not to stop a run, which is outcrawl_agent_cancel, and not to answer a question the agent asked, which is outcrawl_agent_answer.";
+    readonly mcpTool: "outcrawl_agent_control";
+    readonly cliCommand: "agent control";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "agent.answer";
+    readonly method: "POST";
+    readonly path: "/v1/agent/{id}/answer";
+    readonly summary: "Answer the question a paused run is waiting on, and it carries on from where it stopped. A run parks when it needs something only you know — which of two options, a detail you did not give it — and reports the question on its status and its event stream. Use it to unblock a run whose status is paused; not to send a run new instructions, which no route does, and not to take over the browser yourself, which is outcrawl_agent_control.";
+    readonly mcpTool: "outcrawl_agent_answer";
+    readonly cliCommand: "agent answer";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "agent.files";
+    readonly method: "POST";
+    readonly path: "/v1/agent/{id}/files";
+    readonly summary: "Hand a file to a run so it can attach it to a page — at submit time, mid-run, or before its first step. Answers a HANDLE the agent uses with attachFile; you never send the bytes twice and the model never sees them. The file is destroyed when the run ends, on every ending. Use it for something the task needs to upload; not to fetch a file the run produced, because downloads do not exist.";
+    readonly mcpTool: "outcrawl_agent_file_add";
+    readonly cliCommand: "agent files add";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "profiles.create";
+    readonly method: "POST";
+    readonly path: "/v1/profiles";
+    readonly summary: "Mint a durable identity with pinned exit and persistent storage. Use to keep a login across sessions; the identity itself is minted, never chosen.";
+    readonly mcpTool: "outcrawl_profile_create";
+    readonly cliCommand: "profiles create";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "profiles.list";
+    readonly method: "GET";
+    readonly path: "/v1/profiles";
+    readonly summary: "List profiles, optionally filtered by a label glob.";
+    readonly mcpTool: "outcrawl_profile_list";
+    readonly cliCommand: "profiles ls";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "profiles.get";
+    readonly method: "GET";
+    readonly path: "/v1/profiles/{id}";
+    readonly summary: "Fetch one profile: its label, pinned exit and creation time.";
+    readonly mcpTool: "outcrawl_profile_get";
+    readonly cliCommand: "profiles get";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "profiles.delete";
+    readonly method: "DELETE";
+    readonly path: "/v1/profiles/{id}";
+    readonly summary: "Delete a profile and its stored cookies and site data. Irreversible.";
+    readonly mcpTool: "outcrawl_profile_delete";
+    readonly cliCommand: "profiles rm";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "sessions.list";
+    readonly method: "GET";
+    readonly path: "/v1/sessions";
+    readonly summary: "Query past sessions by status, outcome, task or age — twenty replays to watch rather than twenty log lines to guess from.";
+    readonly mcpTool: null;
+    readonly cliCommand: null;
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "sessions.get";
+    readonly method: "GET";
+    readonly path: "/v1/sessions/{id}";
+    readonly summary: "Fetch one session with its replay URL, duration, page count and usage. This is how a charge is disputed: watch what it bought.";
+    readonly mcpTool: null;
+    readonly cliCommand: null;
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: "live";
+}, {
+    readonly name: "sessions.export";
+    readonly method: "POST";
+    readonly path: "/v1/sessions/{id}/export";
+    readonly summary: "Export a session as a portable bundle that plays offline.";
+    readonly mcpTool: null;
+    readonly cliCommand: null;
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "usage";
+    readonly method: "GET";
+    readonly path: "/v1/usage";
+    readonly summary: "Aggregate the same usage numbers already attached to each call. Nothing appears here that was not visible on the call that caused it.";
+    readonly mcpTool: "outcrawl_usage";
+    readonly cliCommand: "usage";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "credits";
+    readonly method: "GET";
+    readonly path: "/v1/credits";
+    readonly summary: "What this account has been granted, what it has spent against the grant, and what is left. Use to see a promotional or student balance and when it lapses; not for the monthly plan allowance, and not for per-call cost, which every response already carries.";
+    readonly mcpTool: "outcrawl_credits";
+    readonly cliCommand: "credits";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "secrets.create";
+    readonly method: "POST";
+    readonly path: "/v1/secrets";
+    readonly summary: "Store a credential under a handle an agent can reference but never read. Use to save a card or an environment variable for a run to use; not to read one back, which nothing can do.";
+    readonly mcpTool: null;
+    readonly cliCommand: "secrets create";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "secrets.list";
+    readonly method: "GET";
+    readonly path: "/v1/secrets";
+    readonly summary: "List stored credentials by handle, with the last four digits of a card and nothing else. No route returns a value, and that absence is the point.";
+    readonly mcpTool: null;
+    readonly cliCommand: "secrets ls";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "secrets.delete";
+    readonly method: "DELETE";
+    readonly path: "/v1/secrets/{id}";
+    readonly summary: "Delete a credential and the record of which runs used it. Takes effect on the next fill: a run holding a grant finds nothing to resolve.";
+    readonly mcpTool: null;
+    readonly cliCommand: "secrets rm";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "rules.get";
+    readonly method: "GET";
+    readonly path: "/v1/rules";
+    readonly summary: "The workspace rules and, for each one, whether it is ENFORCED as a gate that blocks a dispatch or is only GUIDANCE in the prompt. Use it to check that a rule you wrote is actually enforced; the class is the answer, not the text.";
+    readonly mcpTool: "outcrawl_rules_get";
+    readonly cliCommand: "rules get";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "rules.set";
+    readonly method: "PUT";
+    readonly path: "/v1/rules";
+    readonly summary: "Replace the workspace rules with these plain-language sentences and get the classification back on the same call. Use to forbid something in your own words; a rule that could not be compiled into a gate comes back as guidance with the reason.";
+    readonly mcpTool: "outcrawl_rules_set";
+    readonly cliCommand: "rules set";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "integrations.connect";
+    readonly method: "POST";
+    readonly path: "/v1/integrations";
+    readonly summary: "Connect an MCP server — Gmail, Slack, Twilio — so a run can call its tools mid-task. HTTPS endpoints only, authenticated by a secret handle, and no run reaches it unless the run names it. Use to give an agent a way past a wall the browser cannot climb; not to store the credential itself, which is a secret and has no tool.";
+    readonly mcpTool: null;
+    readonly cliCommand: "integrations connect";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "integrations.list";
+    readonly method: "GET";
+    readonly path: "/v1/integrations";
+    readonly summary: "Everything an agent can reach outside the browser: each connected server, the tools it exposes, and the secret handle it authenticates with. This is the blast radius, and a customer who cannot see it cannot consent to it.";
+    readonly mcpTool: null;
+    readonly cliCommand: "integrations ls";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}, {
+    readonly name: "integrations.delete";
+    readonly method: "DELETE";
+    readonly path: "/v1/integrations/{id}";
+    readonly summary: "Disconnect an MCP server. Takes effect on the next call: a run already holding a grant finds the connector gone and is told so. The credential is untouched — it lives in the secrets store and is deleted there.";
+    readonly mcpTool: null;
+    readonly cliCommand: "integrations rm";
+    readonly requiresAuth: true;
+    readonly framing: "json";
+    readonly streamsWhen: null;
+}];
+export type CapabilityName = (typeof CAPABILITIES)[number]['name'];
+/**
+ * One row of the array above, with its literal `name` intact.
+ *
+ * Not `Capability`: the interface declares `name: string`, and reading a row
+ * through it turns every `Record<CapabilityName, …>` downstream into
+ * `Record<string, …>`, which checks nothing.
+ */
+type RegistryRow = (typeof CAPABILITIES)[number];
+/**
+ * The rows that declare an MCP tool, and the rows that declare a CLI command.
+ *
+ * This is where the nullable columns pay for themselves. `Extract` keeps only
+ * the rows whose column is a string, so `McpCapabilityName` is the exact set of
+ * capabilities MCP is supposed to carry — no wider, and derived rather than
+ * listed a second time. MCP keys its shapes and copy by it and the CLI keys its
+ * arguments by its own, which makes both tables exhaustive over their own
+ * surface: a row that declares a tool does not compile until it has one, and a
+ * row that declares `null` cannot be given one.
+ */
+export type McpCapability = Extract<RegistryRow, {
+    mcpTool: string;
+}>;
+export type CliCapability = Extract<RegistryRow, {
+    cliCommand: string;
+}>;
+export type McpCapabilityName = McpCapability['name'];
+export type CliCapabilityName = CliCapability['name'];
+/**
+ * The same rows, in registry order, for the surfaces to map over. The
+ * predicates are type guards, so the narrowed element type carries a `string`
+ * column and a surface never has to check a null the registry ruled out.
+ */
+export declare const MCP_CAPABILITIES: readonly McpCapability[];
+export declare const CLI_CAPABILITIES: readonly CliCapability[];
+/**
+ * Look up a capability by name. Throws rather than returning undefined: every
+ * caller here is a surface being built against the registry, and a missing
+ * capability is a build-time bug, not a runtime condition to handle.
+ */
+export declare function getCapability(name: CapabilityName): Capability;
+export {};