@bctrl/sdk 1.0.4 → 1.0.6

package/dist/invocations.d.ts

@@ -1,8 +1,6 @@
-import type { V1HttpClient } from './http.js';
-import type { JsonObject, V1Invocation, V1RuntimeInvocationCreateRequest, V1RuntimeInvocationFileInput, V1InvocationWaitRequest, V1InvocationWaitResponse } from './types.js';
-type JsonSchemaLike = JsonObject | {
-    toJSONSchema: () => unknown;
-};
+import { type V1HttpClient, type V1IdempotencyOptions } from './http.js';
+import { type JsonSchemaLike } from './schemas.js';
+import type { JsonObject, V1Invocation, V1RuntimeInvocationCreateRequest, V1RuntimeInvocationFileInput, V1RuntimeTargetSelector, V1InvocationWaitRequest, V1InvocationWaitResponse, V1AiModelSelection } from './types.js';
 export type StagehandVariablePrimitive = string | number | boolean;
 export type StagehandVariableValue = StagehandVariablePrimitive | {
     value: StagehandVariablePrimitive;
@@ -10,77 +8,114 @@ export type StagehandVariableValue = StagehandVariablePrimitive | {
 };
 export type StagehandVariables = Record<string, StagehandVariableValue>;
 interface RuntimeInvocationCommonOptions {
-    target?: JsonObject;
-    idempotencyKey?: string;
+    target?: V1RuntimeTargetSelector;
     metadata?: JsonObject;
 }
 interface RuntimeAgentCommonOptions extends RuntimeInvocationCommonOptions {
     toolsetId?: string;
+    toolIds?: string[];
     files?: V1RuntimeInvocationFileInput[];
-    outputSchema?: JsonObject;
+    schema?: JsonSchemaLike;
+    timeoutMs?: number;
 }
-export interface StagehandActOptions extends RuntimeInvocationCommonOptions {
+interface AiSelectionOptions {
+    model?: V1AiModelSelection;
+    temperature?: number;
+}
+export interface StagehandActOptions extends RuntimeInvocationCommonOptions, AiSelectionOptions {
     instruction: string;
+    stagehandAction?: JsonObject;
     timeoutMs?: number;
 }
-export interface StagehandObserveOptions extends RuntimeInvocationCommonOptions {
+export interface StagehandObserveOptions extends RuntimeInvocationCommonOptions, AiSelectionOptions {
     instruction: string;
     selector?: string;
     timeoutMs?: number;
 }
-export type StagehandExtractOptions<TSchema extends JsonSchemaLike | undefined = undefined> = RuntimeInvocationCommonOptions & {
-    instruction: string;
+export type StagehandExtractOptions<TSchema extends JsonSchemaLike | undefined = undefined> = RuntimeInvocationCommonOptions & AiSelectionOptions & {
+    instruction?: string;
+    selector?: string;
     schema?: TSchema;
+    timeoutMs?: number;
 };
-export interface StagehandAgentOptions extends RuntimeAgentCommonOptions {
+export interface StagehandAgentOptions extends RuntimeAgentCommonOptions, AiSelectionOptions {
     instruction: string;
     maxSteps?: number;
-    timeoutMs?: number;
     variables?: StagehandVariables;
-    config?: JsonObject;
-    options?: JsonObject;
+    executionModel?: V1AiModelSelection;
+    systemPrompt?: string;
+    highlightCursor?: boolean;
 }
-export interface BrowserUseAgentOptions extends RuntimeAgentCommonOptions {
+export interface BrowserUseAgentOptions extends RuntimeAgentCommonOptions, AiSelectionOptions {
     instruction: string;
     maxSteps?: number;
-    config?: JsonObject;
-    options?: JsonObject;
+    extractionModel?: V1AiModelSelection;
+    fallbackModel?: V1AiModelSelection;
+    useVision?: boolean | 'auto';
+    visionDetailLevel?: 'low' | 'high' | 'auto';
+    flashMode?: boolean;
+    enablePlanning?: boolean;
+    maxFailures?: number;
+    stepTimeoutMs?: number;
+    maxActionsPerStep?: number;
+    maxHistoryItems?: number | null;
+    useThinking?: boolean;
+    directlyOpenUrl?: boolean;
+    includeAttributes?: string[];
+    overrideSystemMessage?: string;
+    extendSystemMessage?: string;
+    sensitiveData?: Record<string, string | Record<string, string>>;
 }
-export declare class V1InvocationResource {
-    private readonly http;
-    readonly data: V1Invocation;
-    constructor(http: V1HttpClient, data: V1Invocation);
-    get id(): string;
-    refresh(): Promise<V1Invocation>;
-    wait(request?: V1InvocationWaitRequest): Promise<V1InvocationWaitResponse>;
-    cancel(): Promise<V1Invocation>;
+type InvocationCreateWithSchema<T extends V1RuntimeInvocationCreateRequest> = Omit<T, 'outputSchema'> & {
+    schema?: JsonSchemaLike;
+};
+type ExtractInvocationCreateRequest = Extract<V1RuntimeInvocationCreateRequest, {
+    action: 'extract';
+}>;
+type StagehandAgentInvocationCreateRequest = Extract<V1RuntimeInvocationCreateRequest, {
+    action: 'stagehandAgent';
+}>;
+type BrowserUseInvocationCreateRequest = Extract<V1RuntimeInvocationCreateRequest, {
+    action: 'browserUse';
+}>;
+type InvocationCreateSchemaInput = InvocationCreateWithSchema<ExtractInvocationCreateRequest> | InvocationCreateWithSchema<StagehandAgentInvocationCreateRequest> | InvocationCreateWithSchema<BrowserUseInvocationCreateRequest>;
+export type V1RuntimeInvocationCreateInput = Exclude<V1RuntimeInvocationCreateRequest, ExtractInvocationCreateRequest | StagehandAgentInvocationCreateRequest | BrowserUseInvocationCreateRequest> | InvocationCreateSchemaInput;
+export interface V1InvocationWaitOptions extends V1InvocationWaitRequest {
+    signal?: AbortSignal;
 }
-export declare class V1InvocationsClient {
-    private readonly http;
-    constructor(http: V1HttpClient);
-    get(id: string): Promise<V1InvocationResource>;
-    wait(id: string, request?: V1InvocationWaitRequest): Promise<V1InvocationWaitResponse>;
-    cancel(id: string): Promise<V1InvocationResource>;
+export interface V1InvocationCreateAndWaitOptions extends V1IdempotencyOptions {
+    /**
+     * Overall client-side wait budget across repeated long-poll requests.
+     * The server-side invocation timeout still belongs in the invocation body.
+     */
+    timeoutMs?: number;
+    /**
+     * Per-request long-poll timeout sent to the wait endpoint.
+     */
+    pollTimeoutMs?: number;
+    signal?: AbortSignal;
 }
-export declare class V1RuntimeInvocationsClient {
+export declare class V1RuntimeInvocationsNamespaceClient {
     private readonly http;
-    private readonly runtimeId;
-    readonly stagehand: V1RuntimeStagehandInvocationsClient;
-    readonly browserUse: V1RuntimeBrowserUseInvocationsClient;
-    constructor(http: V1HttpClient, runtimeId: string);
-    create(request: V1RuntimeInvocationCreateRequest): Promise<V1InvocationResource>;
+    readonly stagehand: V1RuntimeStagehandInvocationsNamespaceClient;
+    readonly browserUse: V1RuntimeBrowserUseInvocationsNamespaceClient;
+    constructor(http: V1HttpClient);
+    create(runtimeId: string, request: V1RuntimeInvocationCreateInput, options?: V1IdempotencyOptions): Promise<V1Invocation>;
+    wait(runtimeId: string, invocationId: string, request?: V1InvocationWaitOptions): Promise<V1InvocationWaitResponse>;
+    cancel(runtimeId: string, invocationId: string): Promise<V1Invocation>;
+    createAndWait(runtimeId: string, request: V1RuntimeInvocationCreateInput, options?: V1InvocationCreateAndWaitOptions): Promise<V1Invocation>;
 }
-export declare class V1RuntimeStagehandInvocationsClient {
+export declare class V1RuntimeStagehandInvocationsNamespaceClient {
     private readonly invocations;
-    constructor(invocations: V1RuntimeInvocationsClient);
-    act(options: StagehandActOptions): Promise<V1InvocationResource>;
-    observe(options: StagehandObserveOptions): Promise<V1InvocationResource>;
-    extract<TSchema extends JsonSchemaLike | undefined = undefined>(options: StagehandExtractOptions<TSchema>): Promise<V1InvocationResource>;
-    agent(options: StagehandAgentOptions): Promise<V1InvocationResource>;
+    constructor(invocations: V1RuntimeInvocationsNamespaceClient);
+    act(runtimeId: string, options: StagehandActOptions): Promise<V1Invocation>;
+    observe(runtimeId: string, options: StagehandObserveOptions): Promise<V1Invocation>;
+    extract<TSchema extends JsonSchemaLike | undefined = undefined>(runtimeId: string, options: StagehandExtractOptions<TSchema>): Promise<V1Invocation>;
+    agent(runtimeId: string, options: StagehandAgentOptions): Promise<V1Invocation>;
 }
-export declare class V1RuntimeBrowserUseInvocationsClient {
+export declare class V1RuntimeBrowserUseInvocationsNamespaceClient {
     private readonly invocations;
-    constructor(invocations: V1RuntimeInvocationsClient);
-    agent(options: BrowserUseAgentOptions): Promise<V1InvocationResource>;
+    constructor(invocations: V1RuntimeInvocationsNamespaceClient);
+    agent(runtimeId: string, options: BrowserUseAgentOptions): Promise<V1Invocation>;
 }
 export {};

package/dist/invocations.js

@@ -1,55 +1,40 @@
-export class V1InvocationResource {
-    http;
-    data;
-    constructor(http, data) {
-        this.http = http;
-        this.data = data;
-    }
-    get id() {
-        return this.data.id;
-    }
-    refresh() {
-        return this.http
-            .request(`/invocations/${encodeURIComponent(this.id)}`)
-            .then((response) => response.data);
-    }
-    wait(request) {
-        return this.http.request(`/invocations/${encodeURIComponent(this.id)}/wait`, {
-            method: 'POST',
-            body: request ?? {},
-        });
-    }
-    cancel() {
-        return this.http
-            .request(`/invocations/${encodeURIComponent(this.id)}/cancel`, {
-            method: 'POST',
-        })
-            .then((response) => response.data);
-    }
+import { v1IdempotencyHeaders } from './http.js';
+import { toOutputSchema } from './schemas.js';
+import { abortableSleep } from './utils.js';
+// Live control is runtime-scoped; observability reads are run-scoped.
+function runtimeInvocationActionPath(runtimeId, invocationId, action) {
+    return `/runtimes/${encodeURIComponent(runtimeId)}/invocations/${encodeURIComponent(invocationId)}/${action}`;
 }
-export class V1InvocationsClient {
+function createRuntimeInvocation(http, runtimeId, request, options) {
+    return http.request(`/runtimes/${encodeURIComponent(runtimeId)}/invocations`, {
+        method: 'POST',
+        body: prepareInvocationCreateRequest(request),
+        headers: v1IdempotencyHeaders(options),
+    });
+}
+export class V1RuntimeInvocationsNamespaceClient {
     http;
+    stagehand;
+    browserUse;
     constructor(http) {
         this.http = http;
+        this.stagehand = new V1RuntimeStagehandInvocationsNamespaceClient(this);
+        this.browserUse = new V1RuntimeBrowserUseInvocationsNamespaceClient(this);
     }
-    async get(id) {
-        const response = await this.http.request(`/invocations/${encodeURIComponent(id)}`);
-        return new V1InvocationResource(this.http, response.data);
+    create(runtimeId, request, options) {
+        return createRuntimeInvocation(this.http, runtimeId, request, options);
     }
-    wait(id, request) {
-        return this.http.request(`/invocations/${encodeURIComponent(id)}/wait`, {
-            method: 'POST',
-            body: request ?? {},
-        });
+    wait(runtimeId, invocationId, request = {}) {
+        return new V1RuntimeInvocationsClient(this.http, runtimeId).wait(invocationId, request);
     }
-    async cancel(id) {
-        const response = await this.http.request(`/invocations/${encodeURIComponent(id)}/cancel`, {
-            method: 'POST',
-        });
-        return new V1InvocationResource(this.http, response.data);
+    cancel(runtimeId, invocationId) {
+        return new V1RuntimeInvocationsClient(this.http, runtimeId).cancel(invocationId);
+    }
+    createAndWait(runtimeId, request, options = {}) {
+        return new V1RuntimeInvocationsClient(this.http, runtimeId).createAndWait(request, options);
     }
 }
-export class V1RuntimeInvocationsClient {
+class V1RuntimeInvocationsClient {
     http;
     runtimeId;
     stagehand;
@@ -60,100 +45,154 @@ export class V1RuntimeInvocationsClient {
         this.stagehand = new V1RuntimeStagehandInvocationsClient(this);
         this.browserUse = new V1RuntimeBrowserUseInvocationsClient(this);
     }
-    async create(request) {
-        const response = await this.http.request(`/runtimes/${encodeURIComponent(this.runtimeId)}/invocations`, {
+    async create(request, options) {
+        return createRuntimeInvocation(this.http, this.runtimeId, request, options);
+    }
+    wait(invocationId, request = {}) {
+        const { signal, ...body } = request;
+        return this.http.request(runtimeInvocationActionPath(this.runtimeId, invocationId, 'wait'), {
             method: 'POST',
-            body: request,
+            body,
+            signal,
         });
-        return new V1InvocationResource(this.http, response.data);
+    }
+    cancel(invocationId) {
+        return this.http.request(runtimeInvocationActionPath(this.runtimeId, invocationId, 'cancel'), {
+            method: 'POST',
+        });
+    }
+    async createAndWait(request, options = {}) {
+        const invocation = await this.create(request, options);
+        return waitForInvocation(this, invocation.id, options);
     }
 }
-export class V1RuntimeStagehandInvocationsClient {
+class V1RuntimeStagehandInvocationsClient {
     invocations;
     constructor(invocations) {
         this.invocations = invocations;
     }
     act(options) {
-        const { instruction, timeoutMs, ...common } = options;
         return this.invocations.create({
-            provider: 'stagehand',
-            method: 'act',
-            ...common,
-            input: {
-                instruction,
-                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-            },
+            action: 'act',
+            ...options,
         });
     }
     observe(options) {
-        const { instruction, selector, timeoutMs, ...common } = options;
         return this.invocations.create({
-            provider: 'stagehand',
-            method: 'observe',
-            ...common,
-            input: {
-                instruction,
-                ...(selector !== undefined ? { selector } : {}),
-                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-            },
+            action: 'observe',
+            ...options,
         });
     }
     extract(options) {
-        const { instruction, schema, ...common } = options;
+        const { schema, ...common } = options;
         return this.invocations.create({
-            provider: 'stagehand',
-            method: 'extract',
+            action: 'extract',
             ...common,
-            input: { instruction },
-            ...(schema !== undefined ? { outputSchema: toJsonSchemaObject(schema) } : {}),
+            ...(schema !== undefined
+                ? { outputSchema: toOutputSchema(schema, 'Stagehand extract schema') }
+                : {}),
         });
     }
     agent(options) {
-        const { instruction, maxSteps, timeoutMs, variables, config, options: agentOptions, ...common } = options;
         return this.invocations.create({
-            provider: 'stagehand',
-            method: 'agent',
-            ...common,
-            input: {
-                instruction,
-                ...(maxSteps !== undefined ? { maxSteps } : {}),
-                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-                ...(variables !== undefined ? { variables } : {}),
-            },
-            ...(config !== undefined ? { config } : {}),
-            ...(agentOptions !== undefined ? { options: agentOptions } : {}),
+            action: 'stagehandAgent',
+            ...options,
         });
     }
 }
-export class V1RuntimeBrowserUseInvocationsClient {
+class V1RuntimeBrowserUseInvocationsClient {
     invocations;
     constructor(invocations) {
         this.invocations = invocations;
     }
     agent(options) {
-        const { instruction, maxSteps, config, options: agentOptions, ...common } = options;
         return this.invocations.create({
-            provider: 'browserUse',
-            method: 'agent',
+            action: 'browserUse',
+            ...options,
+        });
+    }
+}
+export class V1RuntimeStagehandInvocationsNamespaceClient {
+    invocations;
+    constructor(invocations) {
+        this.invocations = invocations;
+    }
+    act(runtimeId, options) {
+        return this.invocations.create(runtimeId, {
+            action: 'act',
+            ...options,
+        });
+    }
+    observe(runtimeId, options) {
+        return this.invocations.create(runtimeId, {
+            action: 'observe',
+            ...options,
+        });
+    }
+    extract(runtimeId, options) {
+        const { schema, ...common } = options;
+        return this.invocations.create(runtimeId, {
+            action: 'extract',
             ...common,
-            input: {
-                instruction,
-                ...(maxSteps !== undefined ? { maxSteps } : {}),
-            },
-            ...(config !== undefined ? { config } : {}),
-            ...(agentOptions !== undefined ? { options: agentOptions } : {}),
+            ...(schema !== undefined
+                ? { outputSchema: toOutputSchema(schema, 'Stagehand extract schema') }
+                : {}),
+        });
+    }
+    agent(runtimeId, options) {
+        return this.invocations.create(runtimeId, {
+            action: 'stagehandAgent',
+            ...options,
+        });
+    }
+}
+export class V1RuntimeBrowserUseInvocationsNamespaceClient {
+    invocations;
+    constructor(invocations) {
+        this.invocations = invocations;
+    }
+    agent(runtimeId, options) {
+        return this.invocations.create(runtimeId, {
+            action: 'browserUse',
+            ...options,
         });
     }
 }
-function toJsonSchemaObject(schema) {
-    const value = typeof schema.toJSONSchema === 'function' ? schema.toJSONSchema() : schema;
-    if (!isJsonObject(value)) {
-        throw new TypeError('Stagehand extract schema must resolve to a JSON object');
-    }
-    const { $schema, ...jsonSchema } = value;
-    void $schema;
-    return jsonSchema;
+function prepareInvocationCreateRequest(request) {
+    if (!hasInvocationSchema(request)) {
+        return request;
+    }
+    const { schema, ...body } = request;
+    return {
+        ...body,
+        outputSchema: toOutputSchema(schema, 'Invocation schema'),
+    };
 }
-function isJsonObject(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
+function hasInvocationSchema(request) {
+    return 'schema' in request && request.schema !== undefined;
+}
+async function waitForInvocation(client, invocationId, options) {
+    const deadline = options.timeoutMs === undefined ? undefined : Date.now() + options.timeoutMs;
+    for (;;) {
+        if (deadline !== undefined && Date.now() >= deadline) {
+            throw new Error(`Invocation ${invocationId} did not finish before timeout`);
+        }
+        const remaining = deadline === undefined ? undefined : Math.max(1, deadline - Date.now());
+        const timeoutMs = options.pollTimeoutMs === undefined
+            ? remaining
+            : remaining === undefined
+                ? options.pollTimeoutMs
+                : Math.min(options.pollTimeoutMs, remaining);
+        const result = await client.wait(invocationId, {
+            ...(timeoutMs === undefined ? {} : { timeoutMs }),
+            signal: options.signal,
+        });
+        if (result.waitStatus === 'completed') {
+            return result;
+        }
+        const sleepMs = deadline === undefined
+            ? (result.retryAfterMs ?? 1000)
+            : Math.min(result.retryAfterMs ?? 1000, Math.max(0, deadline - Date.now()));
+        await abortableSleep(sleepMs, options.signal);
+    }
 }

package/dist/node.d.ts

@@ -0,0 +1,12 @@
+import { BctrlV1 } from './bctrl.js';
+import type { V1ToolCreateRequest, V1ToolVersionCreateRequest } from './types.js';
+type V1HostedToolCreateRequest = Extract<V1ToolCreateRequest, {
+    type: 'hosted';
+}>;
+export declare function createHostedToolFromFile(client: BctrlV1, request: Omit<V1HostedToolCreateRequest, 'source'> & {
+    filePath: string;
+}): Promise<import("./types.js").V1Tool>;
+export declare function createToolVersionFromFile(client: BctrlV1, toolId: string, request: Omit<V1ToolVersionCreateRequest, 'source'> & {
+    filePath: string;
+}): Promise<import("./types.js").V1ToolVersion>;
+export {};

package/dist/node.js

@@ -0,0 +1,11 @@
+import { readFile } from 'node:fs/promises';
+export async function createHostedToolFromFile(client, request) {
+    const source = await readFile(request.filePath, 'utf8');
+    const { filePath: _filePath, ...rest } = request;
+    return client.tools.create({ ...rest, source });
+}
+export async function createToolVersionFromFile(client, toolId, request) {
+    const source = await readFile(request.filePath, 'utf8');
+    const { filePath: _filePath, ...rest } = request;
+    return client.tools.createVersion(toolId, { ...rest, source });
+}

package/dist/proxies.d.ts

@@ -0,0 +1,21 @@
+import type { V1HttpClient } from './http.js';
+import type { V1ListEnvelope, V1Proxy, V1ProxyCreateRequest, V1ProxyDeleteResponse, V1ProxyListQuery, V1ProxyPool, V1ProxyPoolListQuery, V1ProxyTestResponse, V1ProxyUpdateRequest } from './types.js';
+export declare class V1ProxyPoolsClient {
+    private readonly http;
+    constructor(http: V1HttpClient);
+    list(query?: V1ProxyPoolListQuery): Promise<V1ListEnvelope<V1ProxyPool>>;
+    iter(query?: V1ProxyPoolListQuery): AsyncGenerator<V1ProxyPool, void, undefined>;
+    get(poolId: string): Promise<V1ProxyPool>;
+}
+export declare class V1ProxiesClient {
+    private readonly http;
+    readonly pools: V1ProxyPoolsClient;
+    constructor(http: V1HttpClient);
+    list(query?: V1ProxyListQuery): Promise<V1ListEnvelope<V1Proxy>>;
+    iter(query?: V1ProxyListQuery): AsyncGenerator<V1Proxy, void, undefined>;
+    create(request: V1ProxyCreateRequest): Promise<V1Proxy>;
+    get(proxyId: string): Promise<V1Proxy>;
+    update(proxyId: string, request: V1ProxyUpdateRequest): Promise<V1Proxy>;
+    test(proxyId: string): Promise<V1ProxyTestResponse>;
+    delete(proxyId: string): Promise<V1ProxyDeleteResponse>;
+}

package/dist/proxies.js

@@ -0,0 +1,55 @@
+import { iterateV1Pages } from './pagination.js';
+export class V1ProxyPoolsClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    list(query = {}) {
+        return this.http.request('/proxies/pools', { query });
+    }
+    iter(query = {}) {
+        return iterateV1Pages(query, (pageQuery) => this.list(pageQuery));
+    }
+    get(poolId) {
+        return this.http.request(`/proxies/pools/${encodeURIComponent(poolId)}`);
+    }
+}
+export class V1ProxiesClient {
+    http;
+    pools;
+    constructor(http) {
+        this.http = http;
+        this.pools = new V1ProxyPoolsClient(http);
+    }
+    list(query = {}) {
+        return this.http.request('/proxies', { query });
+    }
+    iter(query = {}) {
+        return iterateV1Pages(query, (pageQuery) => this.list(pageQuery));
+    }
+    create(request) {
+        return this.http.request('/proxies', {
+            method: 'POST',
+            body: request,
+        });
+    }
+    get(proxyId) {
+        return this.http.request(`/proxies/${encodeURIComponent(proxyId)}`);
+    }
+    update(proxyId, request) {
+        return this.http.request(`/proxies/${encodeURIComponent(proxyId)}`, {
+            method: 'PATCH',
+            body: request,
+        });
+    }
+    test(proxyId) {
+        return this.http.request(`/proxies/${encodeURIComponent(proxyId)}/test`, {
+            method: 'POST',
+        });
+    }
+    delete(proxyId) {
+        return this.http.request(`/proxies/${encodeURIComponent(proxyId)}`, {
+            method: 'DELETE',
+        });
+    }
+}