@outcrawl/sdk 0.1.0

package/dist/types/hands.d.ts

@@ -0,0 +1,259 @@
+/**
+ * Human input — the default path, not a flag.
+ *
+ * `page.click()` lands here; `page.raw.click()` is Playwright's. That ordering
+ * is deliberate: the failure mode we care about is someone forgetting to opt
+ * in, not someone forgetting to opt out. An agent that reasons perfectly and
+ * clicks like a robot is still a robot.
+ *
+ * The constants below are the measured ones from the product surface (§6.4),
+ * taken from real human sessions rather than guessed, alongside what Playwright
+ * does by default:
+ *
+ * | | human | Playwright default |
+ * |---|---|---|
+ * | click landing offset | mean 8.1px, sd 15.0 | 0.0, sd 0.0 — exact bbox centre |
+ * | key flight | mean 127ms, sd 89.4 | sd 34.3 |
+ * | sub-movements per stroke | median 3 | 30, with per-sample tremor |
+ * | peak-velocity position | 0.40 | 0.50 for any eased curve |
+ * | fractional coordinates | ~100% | 0% in some stacks |
+ *
+ * Two things this cannot fix from the client — `getCoalescedEvents()` returning
+ * 1 and `PointerEvent.pressure` always 0 — are properties of where the event
+ * enters the stack, and are fixed in the browser's C++.
+ *
+ * `agenthands` (aeonmindai/agenthands v1.1.1) is the reference implementation of
+ * this interface. It is not vendored here: {@link Hands} is the seam, and a
+ * caller passes `new Outcrawl({ hands })` to swap the driver. The built-in
+ * {@link createPlaywrightHands} drives the same measured model through
+ * Playwright's mouse and keyboard so the SDK is not inert without it.
+ *
+ * `scroll` is the one method that does NOT re-derive its model here, and the
+ * asymmetry is deliberate. Pointer and keyboard timing reduce to the five
+ * constants above; a scroll is a sequence of GESTURES with a phase per event, a
+ * per-device granularity and three measured distributions behind it, and a
+ * second copy of that would be a second thing to recalibrate. So `scroll`
+ * delegates to `agenthands`, which owns the model, and supplies the
+ * `Outcrawl.dispatchWheelPath` dispatcher the session hands it. Without a
+ * dispatcher the library falls back to `mouse.wheel()` on its own, which is what
+ * a caller driving a stock browser gets.
+ */
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface RawLocator {
+    boundingBox(options?: {
+        timeout?: number;
+    }): Promise<BoundingBox | null>;
+    scrollIntoViewIfNeeded(options?: {
+        timeout?: number;
+    }): Promise<void>;
+    focus(options?: {
+        timeout?: number;
+    }): Promise<void>;
+    fill(value: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    selectOption(values: string[], options?: {
+        timeout?: number;
+    }): Promise<string[]>;
+}
+export interface RawMouse {
+    move(x: number, y: number, options?: {
+        steps?: number;
+    }): Promise<void>;
+    down(options?: {
+        button?: 'left' | 'right' | 'middle';
+        clickCount?: number;
+    }): Promise<void>;
+    up(options?: {
+        button?: 'left' | 'right' | 'middle';
+        clickCount?: number;
+    }): Promise<void>;
+    /**
+     * `Input.dispatchMouseWheel`, one event per call. Here because it is the
+     * fallback route for {@link Hands.scroll} — the one a caller gets when the
+     * browser has no batched wheel entry point, which is every browser but ours.
+     */
+    wheel(deltaX: number, deltaY: number): Promise<void>;
+}
+export interface RawKeyboard {
+    press(key: string, options?: {
+        delay?: number;
+    }): Promise<void>;
+    insertText(text: string): Promise<void>;
+}
+/**
+ * The slice of Playwright's `Page` this package types against.
+ *
+ * Two jobs. It is what the human-input driver calls — `mouse`, `keyboard`,
+ * `locator` — and it is the floor under `page.raw`, so the escape hatch is
+ * usable without a caller having to parameterise the page type. A caller who
+ * does supply their real `Page` gets all of it: `OutcrawlPage` is generic in
+ * the page type and never narrows it.
+ *
+ * Options are typed loosely on purpose. This is a floor, not a re-declaration
+ * of Playwright's API, and pinning every option object here would mean
+ * tracking Playwright's releases to keep an assignability check passing.
+ */
+export interface RawPage {
+    readonly mouse: RawMouse;
+    readonly keyboard: RawKeyboard;
+    locator(selector: string): RawLocator;
+    url(): string;
+    close(options?: {
+        runBeforeUnload?: boolean;
+    }): Promise<void>;
+    click(selector: string, options?: Record<string, unknown>): Promise<void>;
+    dblclick(selector: string, options?: Record<string, unknown>): Promise<void>;
+    fill(selector: string, value: string, options?: Record<string, unknown>): Promise<void>;
+    hover(selector: string, options?: Record<string, unknown>): Promise<void>;
+    press(selector: string, key: string, options?: Record<string, unknown>): Promise<void>;
+    type(selector: string, text: string, options?: Record<string, unknown>): Promise<void>;
+    check(selector: string, options?: Record<string, unknown>): Promise<void>;
+    uncheck(selector: string, options?: Record<string, unknown>): Promise<void>;
+    focus(selector: string, options?: Record<string, unknown>): Promise<void>;
+    selectOption(selector: string, values: unknown, options?: Record<string, unknown>): Promise<string[]>;
+    goto(url: string, options?: Record<string, unknown>): Promise<unknown>;
+    content(): Promise<string>;
+    title(): Promise<string>;
+    waitForSelector(selector: string, options?: Record<string, unknown>): Promise<unknown>;
+}
+export type WheelPhase = 'began' | 'changed' | 'stationary' | 'ended' | 'cancelled';
+export interface WheelSample {
+    /** Milliseconds from the start of the path. Non-decreasing; the first is 0. */
+    offsetMs: number;
+    /** CSS pixels. Positive `deltaY` scrolls the content down. */
+    deltaX: number;
+    deltaY: number;
+    phase: WheelPhase;
+    /** macOS momentum, for a caller replaying a recorded gesture that had one. */
+    momentumPhase?: 'began' | 'changed' | 'ended' | 'cancelled';
+}
+export interface WheelPath {
+    /** Viewport-relative CSS pixels. One point for the whole path: the browser's
+     * own wheel-latching slop region is 10 CSS pixels, and a cursor that moves
+     * during a scroll is a pointer path, not a wheel one. */
+    x: number;
+    y: number;
+    path: WheelSample[];
+    granularity: 'precisePixel' | 'pixel';
+}
+/** Dispatches a whole gesture through a browser entry point that takes phases. */
+export type WheelPathDispatcher = (path: WheelPath) => Promise<unknown>;
+/**
+ * Input the browser refused to deliver, rather than input that failed.
+ *
+ * `Outcrawl.dispatchWheelPath` refuses while `Outcrawl.lock` is held, by design:
+ * the lock's `ScopedIgnoreInputEvents` drops every event before the renderer
+ * sees it, so a command that reported success would be lying. That refusal is a
+ * statement about the caller's own lock discipline and not about the page, so it
+ * arrives as itself instead of as a failed step.
+ */
+export declare class InputRefusedError extends Error {
+    /** The refusal as the browser worded it. */
+    readonly refusal: string;
+    constructor(what: string, refusal: string);
+}
+/**
+ * One bound set of hands. Bound, not static: personas bind to the profile, so
+ * the same identity keeps the same typing pace and click character across
+ * sessions. Real typing pace varies 3.6x between people, and an identity that
+ * returns at a different speed every visit is describing someone who is not the
+ * same person.
+ */
+export interface Hands {
+    click(page: RawPage, selector: string): Promise<void>;
+    fill(page: RawPage, selector: string, value: string): Promise<void>;
+    type(page: RawPage, selector: string, text: string): Promise<void>;
+    hover(page: RawPage, selector: string): Promise<void>;
+    press(page: RawPage, selector: string, key: string): Promise<void>;
+    selectOption(page: RawPage, selector: string, values: readonly string[]): Promise<void>;
+    /**
+     * Scroll `deltaY` CSS pixels; positive scrolls down.
+     *
+     * `selector` decides only WHERE the gesture happens — the browser latches the
+     * scroll to whatever is under the cursor — so it is optional and its absence
+     * means "where the cursor already is", which is what a page scroll is.
+     *
+     * Throws {@link InputRefusedError} when the browser refused the gesture rather
+     * than failing to deliver it, which today means the session is holding
+     * `Outcrawl.lock`.
+     */
+    scroll(page: RawPage, deltaY: number, selector?: string): Promise<void>;
+}
+/**
+ * What a set of hands is bound to when the session mints it.
+ *
+ * An object rather than a bare persona string because the persona is not the
+ * only thing a driver needs from the session: the batched wheel entry point is
+ * a property of the browser on the other end of the connection, and passing it
+ * per call would make a session-wide capability look like a per-call option.
+ */
+export interface HandsBinding {
+    /**
+     * Persona token minted with the session. Opaque, and never chosen by the
+     * caller — identity is not customer-visible.
+     */
+    readonly persona: string;
+    /**
+     * The browser's batched wheel entry point, when the connection has one. Absent
+     * for any browser but ours, and a driver must still scroll without it.
+     */
+    readonly wheelPath?: WheelPathDispatcher;
+}
+/** Binds hands to one session. */
+export type HandsFactory = (binding: HandsBinding) => Hands;
+export type Sleep = (ms: number) => Promise<void>;
+/** What `createHands` hands back, narrowed to the one method used here. */
+export interface AgentHandsScroller {
+    scroll(deltaY: number): Promise<void>;
+}
+export interface AgentHandsOptions {
+    /** Binds the gesture model to one identity, as the persona binds typing pace. */
+    persona?: string | number;
+    seed?: number;
+    /** Where the gesture happens. One point for the whole path. */
+    start?: {
+        x: number;
+        y: number;
+    };
+    wheelPath?: WheelPathDispatcher;
+}
+/**
+ * The slice of `agenthands` the built-in driver calls.
+ *
+ * `scroll()` reaches for `mouse.wheel` and an optional `evaluate` probe and
+ * nothing else, so the page is typed as that much. A real Playwright `Page`
+ * satisfies the library's own `PageLike` in full; {@link RawPage} is the
+ * narrower floor this package types against and does not declare the keyboard
+ * methods `PageLike` asks for, none of which a scroll touches.
+ */
+export interface AgentHandsModule {
+    createHands(page: {
+        readonly mouse: Pick<RawMouse, 'wheel'>;
+    }, options?: AgentHandsOptions): AgentHandsScroller;
+}
+export type AgentHandsLoader = () => Promise<AgentHandsModule>;
+export interface PlaywrightHandsOptions {
+    /**
+     * Injected so timing can be collapsed in tests. Nothing else about the model
+     * changes: the same samples are drawn, they are just not waited out.
+     */
+    sleep?: Sleep;
+    /**
+     * Loads the scroll model. Injected so the seam is testable without resolving
+     * the package, and overridable by a caller who vendors it.
+     */
+    loadAgentHands?: AgentHandsLoader;
+}
+/**
+ * The built-in driver. Same measured model as `agenthands`, expressed through
+ * Playwright's mouse and keyboard, so the SDK produces human input out of the
+ * box rather than only when a caller remembers to install a second package.
+ * `scroll` is the exception and delegates — see the note at the top of this file.
+ */
+export declare function createPlaywrightHands(options?: PlaywrightHandsOptions): HandsFactory;

package/dist/types/index.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `@outcrawl/sdk` — the typed client, and the Playwright integration.
+ *
+ * ```ts
+ * import { Outcrawl } from '@outcrawl/sdk';
+ * const oc = new Outcrawl({ apiKey: process.env.OUTCRAWL_KEY });
+ *
+ * const browser = await oc.browser({ profile: 'acme-user-42' });
+ * const page = await browser.newPage();
+ * await page.click('#login');       // human input, by default
+ * await page.raw.click('#login');   // Playwright's, and recorded
+ * ```
+ *
+ * The API is the truth; this is a transport over it. Every capability in
+ * `@outcrawl/core`'s registry is reachable from this client under its own
+ * dotted name, and a test in this package fails if one is not.
+ *
+ * The one thing here that is not in the API, MCP or the CLI is the live page —
+ * `page.act`, `page.observe`, `page.extract` — because it needs a CDP
+ * connection in the caller's own process. That is a difference in kind, not an
+ * omission: the other surfaces reach the same capabilities through `agent` and
+ * `scrape`, which run the loop on our side.
+ */
+/**
+ * `API_KEY_ENV` and `API_URL_ENV` are exported because a caller who wants to
+ * say "set OUTCRAWL_API_KEY" in their own error message should read the name
+ * off the client rather than retyping it — a retyped variable name is a
+ * customer told to set a variable nothing reads.
+ */
+export { API_KEY_ENV, API_URL_ENV, Outcrawl, type OutcrawlOptions } from './client.js';
+export { Browser, IdentityOverrideError, assertNoIdentityOverride, openBrowser, resolveExit, type BrowserDeps, type BrowserOptions, } from './browser.js';
+export { OutcrawlPage, type ActResult, type ExtractResult, type ObservedActions } from './page.js';
+export { Session, SessionControl, Sessions, UnsupportedSessionFilterError, assertSupportedFilter, } from './sessions.js';
+export { Integrations } from './integrations.js';
+export { Profiles } from './profiles.js';
+export { Rules } from './rules.js';
+export { Secrets } from './secrets.js';
+/**
+ * Which declared capabilities this SDK actually serves. Exported because a
+ * caller integrating against `monitors.*` deserves to discover it from the
+ * types rather than from a 503 at runtime.
+ */
+export { CAPABILITY_AVAILABILITY, assertAvailable, type Unavailable, } from './availability.js';
+export { Monitors } from './monitors.js';
+export { AgentEvents, AgentHandle, AgentJob, InvalidAgentRequestError, agent, createAgentApi, type AgentApi, type AgentEventOptions, type AgentResultsOptions, } from './agent.js';
+export { CrawlHandle, crawl, scrape, search, type CrawlOptions, type ScrapeOptions, type SearchHits, type SearchOptions, } from './scrape.js';
+export { deletedFrom, inlineUsage, pagedFrom, queryOf, unwrapItem, withUsage, type ClientContext, type Deleted, type Paged, type Result, } from './result.js';
+export { HttpTransport, OutcrawlApiError, alwaysStreams, errorFromWire, resolveRequest, streamSwitch, type CdpBrowser, type CdpBrowserContext, type CdpSession, type Connection, type ConnectSpec, type ExtractResponse, type HttpTransportOptions, type ObserveResponse, type RawInputMark, type RequestSpec, type Transport, } from './transport.js';
+export { createPlaywrightHands, InputRefusedError, type AgentHandsLoader, type AgentHandsModule, type AgentHandsOptions, type AgentHandsScroller, type BoundingBox, type Hands, type HandsBinding, type HandsFactory, type PlaywrightHandsOptions, type RawKeyboard, type RawLocator, type RawMouse, type RawPage, type Sleep, type WheelPath, type WheelPathDispatcher, type WheelPhase, type WheelSample, } from './hands.js';
+/**
+ * Re-exported so a caller catching a leased profile does not need a second
+ * import to name the error, and so `instanceof` is against the same class the
+ * SDK threw.
+ *
+ * EVERY CLASS `errorFromWire` CAN RETURN IS HERE, and the list was audited
+ * rather than extended by taste: eight of the fifteen were missing while the
+ * transport was already handing them to customers, so the errors a caller is
+ * most likely to meet in production — over their plan's rate limit, at their
+ * concurrency ceiling, on a key with no plan — were errors they could not name
+ * or `instanceof`. `OUTCRAWL_ERROR_CODES` and `isKnownErrorCode` come with
+ * them, because branching on `code` is the documented way to handle these and
+ * a caller cannot write an exhaustive switch against a union they cannot see.
+ */
+export { BadRequestError, CapExceededError, CapabilityUnavailableError, ConcurrencyLimitError, ExitUnavailableError, InternalError, MethodNotAllowedError, NoCapacityError, NotFoundError, OutcrawlError, PlanRequiredError, ProfileInUseError, ProfileNotFoundError, QuotaExceededError, TenantScopeError, UnauthorizedError, isOutcrawlError, isKnownErrorCode, OUTCRAWL_ERROR_CODES, CAPABILITIES, getCapability, PROFILE_KEYS, type Capability, type CapabilityName, type OutcrawlErrorCode, type QuotaCeiling, } from './_deps/core/index.js';
+/**
+ * The wire contract.
+ *
+ * Re-exported because this package is a customer's only door: `@outcrawl/core`
+ * is not on npm and is not going to be, so a type that is only nameable from
+ * there is a type nobody outside this repository can name.
+ *
+ * It was not a theoretical gap. `oc.scrape()` is declared to return
+ * `Result<ScrapeResult>` and `ScrapeResult` was not exported, so the first
+ * thing a customer does with a typed client — annotate the value they just
+ * got, or write a helper that takes it — did not compile. Same for
+ * `AgentRequest`, which `oc.agent()` takes as its only argument. A typed
+ * client whose types cannot be referenced is a client with no types.
+ *
+ * `scripts/build.ts` asserts this list stays complete: it reads the core types
+ * the published declarations actually reference and fails the build if one of
+ * them is not exported here, so a new method that returns a new wire type
+ * cannot ship unnameable.
+ *
+ * `PageMetadata`, `PageChallenge`, `PageChallengeOutcome` and `ChallengeWatch`
+ * arrived on 2026-09-06 because the assertion is over DIRECT references and
+ * these are one hop further: `ScrapeResult.metadata` is a `PageMetadata`, so a
+ * customer could always READ `result.metadata.challengeWatch` and could never
+ * name its type to switch exhaustively over it. A three-value union a caller
+ * is expected to branch on, whose union type is unnameable, is the same defect
+ * this block exists to close, one level down.
+ *
+ * `Secret`, `RulesView` and their one-hop companions arrived with the secrets
+ * and rules clients: `oc.secrets.create()` answers a `Result<Secret>` and
+ * `oc.rules.get()` a `Result<RulesView>`, and `RulesViewRule.class` and
+ * `.gate` are exactly the fields a caller is told to branch on — so the union
+ * types behind them have to be nameable or the branch cannot be written.
+ */
+export type { AgentEventLevel, AgentRecord, AgentRecordKind, AgentRequest, AgentResult, AgentRun, AgentRunStatus, AgentStep, AgentStopReason, AgentSubmission, BilledResources, ChallengeWatch, CrawlJob, CrawlPage, CrawlRequest, CreditBalance, ExitSpec, ExitTarget, HttpMethod, JsonSchema, Monitor, MonitorQuery, MonitorSpec, ObservedAction, PageChallenge, PageChallengeOutcome, PageMetadata, Profile, ProfileCreateRequest, ProfileQuery, ResolvedExit, RuleClass, RuleGate, RulesView, RulesViewRule, ScrapeRequest, ScrapeResult, SearchHit, SearchRequest, Secret, SecretCreateRequest, SecretKind, SecretQuery, SessionExport, SessionOutcome, SessionQuery, SessionStatus, SessionSummary, Timestamp, Usage, UsageQuery, UsageReport, } from './_deps/core/index.js';
+/**
+ * The connector wire types, on the block above's argument and from the package
+ * that owns them rather than from a copy kept here.
+ *
+ * `oc.integrations.connect()` takes a `ConnectorInput` and every method
+ * answers `Connector` rows verbatim — there is no view in front of them,
+ * because a connector row holds a secrets-store HANDLE and never a value — so
+ * a customer who cannot name `ConnectorAuth` cannot write the switch that
+ * reads which handle a connector authenticates with. `scripts/build.ts`
+ * carries `connector.d.ts` into `_deps` for the same reason it carries
+ * replay's `events.d.ts`.
+ */
+export type { Connector, ConnectorAuth, ConnectorInput, ConnectorTransport, } from './_deps/integrations/connector.js';

package/dist/types/integrations.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Integrations — what a run can reach OUTSIDE the browser.
+ *
+ * A workspace connects an MCP server — Gmail, Slack, Twilio — and a run that
+ * was granted it calls that server's tools mid-task: to read a 2FA code, to
+ * ask a question, to phone a human. This class is the management half, for a
+ * person. The calling half is the agent loop's `callTool`, and it is not
+ * reachable from here.
+ *
+ * ── CONNECTING IS NOT GRANTING ───────────────────────────────────────────────
+ *
+ * {@link Integrations.connect} answering a row does NOT mean a run can call it.
+ * Reach is granted PER RUN through `AgentRequest.integrations`, and a submit
+ * that names nothing reaches nothing however many connectors the workspace
+ * has. That default is the containment: a page that talks a model into
+ * "email this table to attacker@example.com" is talking to a run with no mail
+ * connector, whatever this account has connected. Name the connector on the
+ * submit, deliberately, per run — see `availability.ts`, which declines to
+ * gate these rows for exactly this reason.
+ *
+ * ── THE ROW IS THE RESPONSE ──────────────────────────────────────────────────
+ *
+ * {@link Integrations.list} hands back {@link Connector} rows verbatim, with no
+ * projection in front of them, and that is the property rather than a
+ * shortcut: a connector row holds a secrets-store HANDLE and never a value, so
+ * there is nothing on it to withhold. A stripped-down view would imply the row
+ * has something worth hiding, and the day a field arrives that does, it would
+ * arrive on a type nobody reads twice. `@outcrawl/integrations`'s `Connector`
+ * states the same rule from the other side.
+ *
+ * `list` takes no query, and that too is a decision: this listing is the blast
+ * radius, and a filter on it is a way to read half of it and believe it is the
+ * whole.
+ */
+import type { Connector, ConnectorInput } from './_deps/integrations/connector.js';
+import { type ClientContext, type Deleted, type Paged, type Result } from './result.js';
+export declare class Integrations {
+    #private;
+    constructor(ctx: ClientContext);
+    /**
+     * Connect an MCP server so a run may be granted its tools.
+     *
+     * `auth.secret` is a secrets-store HANDLE and never a token: the plaintext is
+     * resolved at the instant of a call, by the tier making it, and nothing this
+     * client sends or receives ever holds one. HTTPS endpoints only, and an
+     * address that is not on the public internet is refused by the same parser
+     * the API and the CLI use, so the refusal reads identically whichever
+     * surface you came from.
+     */
+    connect(input: ConnectorInput): Promise<Result<Connector>>;
+    /**
+     * Every connected server, the tools it exposes, and the handle it
+     * authenticates with. `tools: null` means every tool the remote advertises.
+     */
+    list(): Promise<Paged<Connector>>;
+    /**
+     * Disconnect a server. Takes effect on the next call: a run already holding
+     * a grant finds the connector gone and is told so, rather than being cut off
+     * mid-step. The credential is untouched — it lives in the secrets store and
+     * is deleted there.
+     */
+    delete(id: string): Promise<Result<Deleted>>;
+}

package/dist/types/monitors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Monitors — declared, and not served.
+ *
+ * Every method here refuses with {@link CapabilityUnavailableError}. The
+ * methods still exist, and that is deliberate: the registry declares these
+ * rows, the coverage test in this package walks the registry to the client, and
+ * a capability that is silently absent from the client is the same omission in
+ * the other direction. A named refusal that says what is missing is reachable,
+ * greppable and honest; a missing property is a `TypeError` about `undefined`.
+ *
+ * The refusal is raised inside `resolveRequest`, not written out per method, so
+ * it cannot be forgotten by a method added later. See `availability.ts` for
+ * what is missing — in short: nothing runs a monitor's schedule, so a created
+ * monitor would be stored and never checked.
+ */
+import type { Monitor, MonitorQuery, MonitorSpec } from './_deps/core/index.js';
+import { type ClientContext, type Deleted, type Paged, type Result } from './result.js';
+export declare class Monitors {
+    #private;
+    constructor(ctx: ClientContext);
+    create(spec: MonitorSpec): Promise<Result<Monitor>>;
+    list(query?: MonitorQuery): Promise<Paged<Monitor>>;
+    delete(id: string): Promise<Result<Deleted>>;
+}

package/dist/types/page.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The live page — the one surface that exists in the SDK and nowhere else.
+ *
+ * `page.click()` goes through human input. `page.raw.click()` is Playwright's,
+ * untouched, for setup where speed matters. Both are supported; only one is the
+ * default, and it is the safe one, because the failure mode that costs a
+ * customer their account is someone forgetting to opt *in*.
+ *
+ * `observe()` and `act()` are the other half. `observe()` resolves an
+ * instruction to actions and executes none of them, which makes it both the
+ * review point and the action-cache unit: a hit replays the resolved action with
+ * zero model tokens.
+ */
+import type { JsonSchema, ObservedAction, Usage } from './_deps/core/index.js';
+import type { Hands, RawPage } from './hands.js';
+import type { Connection, RawInputMark } from './transport.js';
+/**
+ * Reviewable actions, with the usage the resolution cost carried on the array
+ * itself — the same shape as search hits, and for the same reason: usage rides
+ * on the result that caused it.
+ */
+export type ObservedActions = readonly ObservedAction[] & {
+    readonly usage: Usage;
+};
+export interface ExtractResult<T> {
+    data: T;
+    usage: Usage;
+}
+/** What `act()` actually did. One action, named, with what it cost. */
+export interface ActResult {
+    action: ObservedAction;
+    usage: Usage;
+}
+export interface OutcrawlPageInit<TRaw extends RawPage> {
+    page: TRaw;
+    hands: Hands;
+    connection: Connection;
+    onRaw: (mark: RawInputMark) => void;
+}
+/**
+ * A Playwright page with human input under the familiar names.
+ *
+ * Generic in the page type so `page.raw` is the caller's real Playwright
+ * `Page` — everything an existing script does keeps working, and the SDK never
+ * narrows the escape hatch to the subset it happens to call itself.
+ */
+export declare class OutcrawlPage<TRaw extends RawPage = RawPage> {
+    #private;
+    /**
+     * Playwright's own surface, untouched, and recorded. Every input call through
+     * here is marked on the session: a checkout run that reached for `raw` is
+     * visibly flagged rather than silently different, so whoever reads the replay
+     * after a block is not guessing.
+     */
+    readonly raw: TRaw;
+    constructor(init: OutcrawlPageInit<TRaw>);
+    get sessionId(): string;
+    url(): string;
+    click(selector: string): Promise<void>;
+    fill(selector: string, value: string): Promise<void>;
+    type(selector: string, text: string): Promise<void>;
+    hover(selector: string): Promise<void>;
+    press(selector: string, key: string): Promise<void>;
+    selectOption(selector: string, values: readonly string[]): Promise<void>;
+    /**
+     * Scroll `deltaY` CSS pixels; positive scrolls down. `selector` aims the
+     * gesture at an element, because the browser latches a scroll to whatever is
+     * under the cursor; without one the gesture happens where the pointer is,
+     * which is what a page scroll is.
+     *
+     * Not `page.raw.mouse.wheel()`, and not a `scrollIntoView()` jump. Both land
+     * as `Input.dispatchMouseWheel` or as no wheel event at all, and this goes
+     * through the browser's own gesture entry point — see {@link Hands.scroll}.
+     */
+    scroll(deltaY: number, selector?: string): Promise<void>;
+    /**
+     * Resolve an instruction to the actions that *could* be taken. Executes none
+     * of them — that is the whole contract, and it is what makes the returned
+     * array reviewable and cacheable.
+     */
+    observe(instruction: string, options?: {
+        cache?: boolean;
+    }): Promise<ObservedActions>;
+    /**
+     * Perform exactly one action.
+     *
+     * Given an {@link ObservedAction} from `observe()`, it replays that action
+     * with no model call at all. Given a string, it resolves the instruction
+     * first and performs the best candidate — one inference, one action.
+     */
+    act(action: ObservedAction | string, options?: {
+        cache?: boolean;
+    }): Promise<ActResult>;
+    extract<T = unknown>(instruction: string, schema?: JsonSchema): Promise<ExtractResult<T>>;
+    close(): Promise<void>;
+}

package/dist/types/profiles.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Profiles — a durable identity and its storage.
+ *
+ * The caller names it and nothing else. Everything that makes the identity —
+ * seed, chrome-or-brave, fingerprint, timezone, languages, WebRTC address — is
+ * minted by us, pinned for the profile's life, and never appears on this type.
+ * `Profile` has no `identity` field and there will never be one: the operator
+ * side runs the identity loop, the customer side sees outcomes.
+ */
+import { PROFILE_KEYS, type Profile, type ProfileCreateRequest, type ProfileQuery } from './_deps/core/index.js';
+import { type ClientContext, type Deleted, type Paged, type Result } from './result.js';
+export declare class Profiles {
+    #private;
+    constructor(ctx: ClientContext);
+    create(request: ProfileCreateRequest): Promise<Result<Profile>>;
+    list(query?: ProfileQuery): Promise<Paged<Profile>>;
+    get(id: string): Promise<Result<Profile>>;
+    /** Deletes the profile and its stored cookies and site data. Irreversible. */
+    delete(id: string): Promise<Result<Deleted>>;
+}
+/**
+ * The keys a `Profile` is allowed to have, straight from core. Exported so the
+ * "no identity, ever" rule is checkable by anything holding a profile, not only
+ * by this package's tests.
+ */
+export { PROFILE_KEYS };