@modelprofile.com/browser-runtime 1.0.0

package/ts/classes.framed.ts

@@ -0,0 +1,649 @@
+import * as plugins from './plugins.js';
+import { validateAgentAction, validateAgentActionResult } from './actions.js';
+import type { BrowserRuntime, BrowserRuntimeLease } from './classes.runtime.js';
+import { BrowserRuntimeError, type TBrowserRuntimeErrorCode } from './errors.js';
+import type {
+  IAttachTrustedFramedPeerOptions,
+  IBrowserRuntimeFramedClientOptions,
+  IBrowserRuntimeOperationOptions,
+  TBrowserAgentAction,
+  TBrowserAgentActionResult,
+} from './interfaces.js';
+import {
+  assertJsonWithoutBytes,
+  randomId,
+  validateBoundedString,
+  validateExactKeys,
+  validateInteger,
+  waitBounded,
+} from './utils.js';
+
+interface IFramedSuccessResponse {
+  version: 1;
+  id: string;
+  ok: true;
+  result: unknown;
+}
+
+interface IFramedErrorResponse {
+  version: 1;
+  id: string;
+  ok: false;
+  error: {
+    code: TBrowserRuntimeErrorCode;
+    message: string;
+  };
+}
+
+type TFramedResponse = IFramedSuccessResponse | IFramedErrorResponse;
+
+interface IPendingClientRequest {
+  resolve(value: unknown): void;
+  reject(error: unknown): void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+const protocolVersion = 1;
+const hardMaxFrameBytes = 256 * 1024;
+const hardMaxPendingRequests = 16;
+const hardRequestTimeoutMs = 60_000;
+
+class JsonFramedChannel {
+  private buffer = plugins.Buffer.alloc(0);
+  private writeTail = Promise.resolve();
+  private started = false;
+  private closed = false;
+  private queuedBytes = 0;
+  private readonly onDataBound = (chunk: plugins.Buffer | string): void => {
+    this.onData(chunk);
+  };
+  private readonly onCloseBound = (): void => {
+    this.closeFromStream();
+  };
+
+  constructor(
+    private readonly readable: plugins.stream.Readable,
+    private readonly writable: plugins.stream.Writable,
+    private readonly maxFrameBytes: number,
+    private readonly writeTimeoutMs: number,
+    private readonly onMessage: (message: unknown) => void,
+    private readonly onClose: () => void,
+  ) {}
+
+  public start(): void {
+    if (this.started || this.closed) return;
+    this.started = true;
+    this.readable.on('data', this.onDataBound);
+    this.readable.once('end', this.onCloseBound);
+    this.readable.once('close', this.onCloseBound);
+    this.readable.once('error', this.onCloseBound);
+    this.writable.once('close', this.onCloseBound);
+    this.writable.once('error', this.onCloseBound);
+  }
+
+  public send(message: unknown): Promise<void> {
+    if (this.closed) return Promise.reject(new BrowserRuntimeError('PROTOCOL_ERROR'));
+    assertJsonWithoutBytes(message, this.maxFrameBytes);
+    const payload = plugins.Buffer.from(JSON.stringify(message), 'utf8');
+    if (payload.byteLength > this.maxFrameBytes) {
+      return Promise.reject(new BrowserRuntimeError('PROTOCOL_ERROR'));
+    }
+    const header = plugins.Buffer.allocUnsafe(4);
+    header.writeUInt32BE(payload.byteLength, 0);
+    const frame = plugins.Buffer.concat([header, payload]);
+    if (this.queuedBytes + frame.byteLength > this.maxFrameBytes * hardMaxPendingRequests) {
+      return Promise.reject(new BrowserRuntimeError('BUSY'));
+    }
+    this.queuedBytes += frame.byteLength;
+    const write = this.writeTail.then(() => this.write(frame)).finally(() => {
+      this.queuedBytes -= frame.byteLength;
+    });
+    this.writeTail = write.catch(() => undefined);
+    return write;
+  }
+
+  public async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    this.removeListeners();
+    if (typeof this.readable.destroy === 'function') this.readable.destroy();
+    if (typeof this.writable.destroy === 'function') this.writable.destroy();
+    await waitBounded(this.writeTail, this.writeTimeoutMs).catch(() => undefined);
+    this.onClose();
+  }
+
+  private onData(chunkArg: plugins.Buffer | string): void {
+    if (this.closed) return;
+    const chunk = typeof chunkArg === 'string'
+      ? plugins.Buffer.from(chunkArg, 'utf8')
+      : chunkArg;
+    this.buffer = plugins.Buffer.concat([this.buffer, chunk]);
+    while (this.buffer.byteLength >= 4) {
+      const length = this.buffer.readUInt32BE(0);
+      if (length < 2 || length > this.maxFrameBytes) {
+        void this.close();
+        return;
+      }
+      if (this.buffer.byteLength < length + 4) return;
+      const payload = this.buffer.subarray(4, length + 4);
+      this.buffer = this.buffer.subarray(length + 4);
+      try {
+        const message = JSON.parse(payload.toString('utf8')) as unknown;
+        assertJsonWithoutBytes(message, this.maxFrameBytes);
+        this.onMessage(message);
+      } catch {
+        void this.close();
+        return;
+      }
+    }
+    if (this.buffer.byteLength > this.maxFrameBytes + 4) void this.close();
+  }
+
+  private write(frame: plugins.Buffer): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      if (this.closed || !this.writable.writable) {
+        reject(new BrowserRuntimeError('PROTOCOL_ERROR'));
+        return;
+      }
+      let settled = false;
+      const timer = setTimeout(() => {
+        finish(new BrowserRuntimeError('TIMEOUT'));
+        this.closeFromStream();
+      }, this.writeTimeoutMs);
+      const cleanup = (): void => {
+        clearTimeout(timer);
+        this.writable.off('error', onError);
+        this.writable.off('close', onClose);
+      };
+      const finish = (error?: Error): void => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        if (error) reject(error);
+        else resolve();
+      };
+      const onError = (error: Error): void => finish(error);
+      const onClose = (): void => finish(new BrowserRuntimeError('PROTOCOL_ERROR'));
+      this.writable.once('error', onError);
+      this.writable.once('close', onClose);
+      this.writable.write(frame, (error?: Error | null) => finish(error ?? undefined));
+    });
+  }
+
+  private closeFromStream(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.removeListeners();
+    if (typeof this.readable.destroy === 'function') this.readable.destroy();
+    if (typeof this.writable.destroy === 'function') this.writable.destroy();
+    this.onClose();
+  }
+
+  private removeListeners(): void {
+    this.readable.off('data', this.onDataBound);
+    this.readable.off('end', this.onCloseBound);
+    this.readable.off('close', this.onCloseBound);
+    this.readable.off('error', this.onCloseBound);
+    this.writable.off('close', this.onCloseBound);
+    this.writable.off('error', this.onCloseBound);
+  }
+}
+
+export class BrowserRuntimeFramedServerPeer {
+  private readonly trustedPeerId: string;
+  private readonly trustedScopeId: string;
+  private readonly trustedSessionId: string;
+  private readonly channel: JsonFramedChannel;
+  private readonly activeRequests = new Map<string, AbortController>();
+  private lease?: BrowserRuntimeLease;
+  private started = false;
+  private closePromise?: Promise<void>;
+  private closing = false;
+  private readonly dispatches = new Set<Promise<void>>();
+
+  constructor(
+    private readonly runtime: BrowserRuntime,
+    options: IAttachTrustedFramedPeerOptions,
+    private readonly onClosed: () => void = () => undefined,
+  ) {
+    this.trustedPeerId = validateBoundedString(options.peerId, 'peerId', 1, 128);
+    this.trustedScopeId = validateBoundedString(options.scopeId, 'scopeId', 1, 128);
+    this.trustedSessionId = validateBoundedString(options.sessionId, 'sessionId', 1, 128);
+    if (
+      !(options.readable instanceof plugins.stream.Readable)
+      || !(options.writable instanceof plugins.stream.Writable)
+    ) {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    this.channel = new JsonFramedChannel(
+      options.readable,
+      options.writable,
+      hardMaxFrameBytes,
+      hardRequestTimeoutMs,
+      (message) => this.handleMessage(message),
+      () => { void this.closeFromStream().catch(() => undefined); },
+    );
+  }
+
+  public get peerId(): string {
+    return this.trustedPeerId;
+  }
+
+  public start(): void {
+    if (this.started) return;
+    this.started = true;
+    this.channel.start();
+  }
+
+  public close(): Promise<void> {
+    if (this.closePromise) return this.closePromise;
+    this.closePromise = this.closeInternal().catch((error) => {
+      this.closePromise = undefined;
+      throw error;
+    });
+    return this.closePromise;
+  }
+
+  private handleMessage(message: unknown): void {
+    if (this.closing) return;
+    let id = 'invalid';
+    try {
+      const request = validateExactKeys(
+        message,
+        ['version', 'id', 'method', 'capabilityToken', 'action', 'targetRequestId'],
+        'framed request',
+      );
+      if (request.version !== protocolVersion) throw new BrowserRuntimeError('PROTOCOL_ERROR');
+      id = validateBoundedString(request.id, 'id', 1, 128);
+      const method = validateBoundedString(request.method, 'method', 1, 32);
+      if (
+        this.activeRequests.size >= hardMaxPendingRequests
+        && (method !== 'cancel' || this.activeRequests.size >= hardMaxPendingRequests + 4)
+      ) {
+        throw new BrowserRuntimeError('BUSY');
+      }
+      const controller = new AbortController();
+      if (this.activeRequests.has(id)) throw new BrowserRuntimeError('PROTOCOL_ERROR');
+      this.activeRequests.set(id, controller);
+      const dispatch = this.dispatchRequest(id, method, request, controller).finally(() => {
+        this.activeRequests.delete(id);
+        this.dispatches.delete(dispatch);
+      });
+      this.dispatches.add(dispatch);
+    } catch (error) {
+      void this.sendError(id, error);
+    }
+  }
+
+  private async dispatchRequest(
+    id: string,
+    method: string,
+    request: Record<string, unknown>,
+    controller: AbortController,
+  ): Promise<void> {
+    try {
+      let result: unknown;
+      if (method === 'acquire') {
+        validateExactKeys(request, ['version', 'id', 'method', 'capabilityToken'], 'acquire request');
+        if (this.lease) throw new BrowserRuntimeError('BUSY');
+        const capabilityToken = validateBoundedString(
+          request.capabilityToken,
+          'capabilityToken',
+          16,
+          512,
+        );
+        this.lease = await this.runtime.acquireLease({
+          capabilityToken,
+          peerId: this.trustedPeerId,
+          expectedRole: 'agent',
+          expectedSource: 'flex',
+          scopeId: this.trustedScopeId,
+          sessionId: this.trustedSessionId,
+          signal: controller.signal,
+        });
+        if (this.closing || controller.signal.aborted) {
+          await this.lease.release();
+          this.lease = undefined;
+          throw new BrowserRuntimeError('ABORTED');
+        }
+        result = {
+          leaseId: this.lease.leaseId,
+          role: this.lease.role,
+          scopeId: this.trustedScopeId,
+          sessionId: this.trustedSessionId,
+        };
+      } else if (method === 'execute') {
+        validateExactKeys(request, ['version', 'id', 'method', 'action'], 'execute request');
+        const lease = this.requireLease();
+        const action = validateAgentAction(request.action);
+        result = await lease.executeAgentAction(action, { signal: controller.signal });
+      } else if (method === 'cancel') {
+        validateExactKeys(
+          request,
+          ['version', 'id', 'method', 'targetRequestId'],
+          'cancel request',
+        );
+        const targetRequestId = validateBoundedString(
+          request.targetRequestId,
+          'targetRequestId',
+          1,
+          128,
+        );
+        const target = this.activeRequests.get(targetRequestId);
+        target?.abort(new BrowserRuntimeError('ABORTED'));
+        const cancelled = Boolean(target);
+        result = { cancelled };
+      } else if (method === 'release') {
+        validateExactKeys(request, ['version', 'id', 'method'], 'release request');
+        const lease = this.requireLease();
+        await lease.release();
+        this.lease = undefined;
+        result = { released: true };
+      } else {
+        throw new BrowserRuntimeError('PROTOCOL_ERROR');
+      }
+      assertJsonWithoutBytes(result, hardMaxFrameBytes);
+      await this.channel.send({ version: protocolVersion, id, ok: true, result });
+    } catch (error) {
+      await this.sendError(id, error);
+    }
+  }
+
+  private requireLease(): BrowserRuntimeLease {
+    if (!this.lease) throw new BrowserRuntimeError('CAPABILITY_INVALID');
+    return this.lease;
+  }
+
+  private async sendError(id: string, error: unknown): Promise<void> {
+    const runtimeError = error instanceof BrowserRuntimeError
+      ? error
+      : new BrowserRuntimeError('PROTOCOL_ERROR');
+    await this.channel.send({
+      version: protocolVersion,
+      id,
+      ok: false,
+      error: { code: runtimeError.code, message: runtimeError.publicMessage },
+    } satisfies IFramedErrorResponse).catch(() => undefined);
+  }
+
+  private async closeInternal(): Promise<void> {
+    this.closing = true;
+    for (const controller of this.activeRequests.values()) {
+      controller.abort(new BrowserRuntimeError('ABORTED'));
+    }
+    const dispatchResult = await waitBounded(
+      Promise.allSettled([...this.dispatches]).then(() => undefined),
+      hardRequestTimeoutMs,
+    );
+    if (!dispatchResult.settled) {
+      await this.runtime.disconnectPeer(this.trustedPeerId);
+    }
+    await this.lease?.release();
+    this.lease = undefined;
+    await this.runtime.disconnectPeer(this.trustedPeerId);
+    await this.channel.close();
+    this.onClosed();
+  }
+
+  private async closeFromStream(): Promise<void> {
+    if (this.closePromise) return;
+    this.closePromise = (async () => {
+      this.closing = true;
+      for (const controller of this.activeRequests.values()) {
+        controller.abort(new BrowserRuntimeError('ABORTED'));
+      }
+      await waitBounded(
+        Promise.allSettled([...this.dispatches]).then(() => undefined),
+        hardRequestTimeoutMs,
+      );
+      await this.lease?.release();
+      this.lease = undefined;
+      await this.runtime.disconnectPeer(this.trustedPeerId);
+      this.onClosed();
+    })().catch((error) => {
+      this.closePromise = undefined;
+      throw error;
+    });
+    await this.closePromise;
+  }
+}
+
+export class BrowserRuntimeFramedClient {
+  private readonly channel: JsonFramedChannel;
+  private readonly maxPendingRequests: number;
+  private readonly requestTimeoutMs: number;
+  private readonly pending = new Map<string, IPendingClientRequest>();
+  private acquired = false;
+  private started = false;
+  private closePromise?: Promise<void>;
+  private readonly scopeIdValue: string;
+  private readonly sessionIdValue: string;
+
+  constructor(options: IBrowserRuntimeFramedClientOptions) {
+    this.scopeIdValue = validateBoundedString(options.scopeId, 'scopeId', 1, 128);
+    this.sessionIdValue = validateBoundedString(options.sessionId, 'sessionId', 1, 128);
+    if (
+      !(options.readable instanceof plugins.stream.Readable)
+      || !(options.writable instanceof plugins.stream.Writable)
+    ) {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    const maxFrameBytes = options.maxFrameBytes === undefined
+      ? hardMaxFrameBytes
+      : validateInteger(options.maxFrameBytes, 'maxFrameBytes', 1024, hardMaxFrameBytes);
+    this.maxPendingRequests = options.maxPendingRequests === undefined
+      ? hardMaxPendingRequests
+      : validateInteger(
+          options.maxPendingRequests,
+          'maxPendingRequests',
+          1,
+          hardMaxPendingRequests,
+        );
+    this.requestTimeoutMs = options.requestTimeoutMs === undefined
+      ? hardRequestTimeoutMs
+      : validateInteger(options.requestTimeoutMs, 'requestTimeoutMs', 100, hardRequestTimeoutMs);
+    this.channel = new JsonFramedChannel(
+      options.readable,
+      options.writable,
+      maxFrameBytes,
+      this.requestTimeoutMs,
+      (message) => this.handleResponse(message),
+      () => this.handleClose(),
+    );
+  }
+
+  public start(): void {
+    if (this.started) return;
+    this.started = true;
+    this.channel.start();
+  }
+
+  public get scopeId(): string {
+    return this.scopeIdValue;
+  }
+
+  public get sessionId(): string {
+    return this.sessionIdValue;
+  }
+
+  public async acquire(capabilityTokenArg: string, signal?: AbortSignal): Promise<void> {
+    if (this.acquired) throw new BrowserRuntimeError('BUSY');
+    signal?.throwIfAborted();
+    const capabilityToken = validateBoundedString(
+      capabilityTokenArg,
+      'capabilityToken',
+      16,
+      512,
+    );
+    this.start();
+    const id = randomId(12);
+    const acquisition = this.requestWithId(id, 'acquire', { capabilityToken });
+    const onAbort = (): void => {
+      void this.request('cancel', { targetRequestId: id }).catch(() => undefined);
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+      await acquisition;
+      signal?.throwIfAborted();
+      this.acquired = true;
+    } finally {
+      signal?.removeEventListener('abort', onAbort);
+    }
+  }
+
+  public async executeAgentAction(
+    actionArg: TBrowserAgentAction,
+    options: IBrowserRuntimeOperationOptions = {},
+  ): Promise<TBrowserAgentActionResult> {
+    if (!this.acquired) throw new BrowserRuntimeError('CAPABILITY_INVALID');
+    options.signal?.throwIfAborted();
+    const action = validateAgentAction(actionArg);
+    const id = randomId(12);
+    const requestPromise = this.requestWithId(id, 'execute', { action });
+    const onAbort = (): void => {
+      void this.request('cancel', { targetRequestId: id }).catch(() => undefined);
+    };
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+      const result = await requestPromise;
+      assertJsonWithoutBytes(result, hardMaxFrameBytes);
+      return validateAgentActionResult(result);
+    } finally {
+      options.signal?.removeEventListener('abort', onAbort);
+    }
+  }
+
+  public asToolBrowserContext(): plugins.smartagent.IToolBrowserContext {
+    return {
+      execute: async (input, options) => {
+        const record = validateExactKeys(
+          input,
+          ['action', 'url', 'selector', 'text', 'timeoutMs'],
+          'browser tool input',
+        );
+        const actionName = validateBoundedString(record.action ?? 'snapshot', 'action', 1, 32);
+        let action: TBrowserAgentAction;
+        if (actionName === 'navigate') {
+          action = { action: 'navigate', url: String(record.url ?? '') };
+        } else if (actionName === 'snapshot') {
+          action = { action: 'snapshot' };
+        } else if (actionName === 'screenshot') {
+          action = { action: 'screenshot' };
+        } else if (actionName === 'click') {
+          action = { action: 'click', selector: String(record.selector ?? '') };
+        } else if (actionName === 'fill') {
+          action = {
+            action: 'fill',
+            selector: String(record.selector ?? ''),
+            text: String(record.text ?? ''),
+          };
+        } else if (actionName === 'press') {
+          action = {
+            action: 'press',
+            selector: String(record.selector ?? ''),
+            key: String(record.text ?? ''),
+          };
+        } else {
+          throw new BrowserRuntimeError('INVALID_INPUT');
+        }
+        if (record.timeoutMs !== undefined) {
+          const timeoutMs = validateInteger(record.timeoutMs, 'timeoutMs', 100, 120_000);
+          if (
+            action.action === 'navigate'
+            || action.action === 'click'
+            || action.action === 'fill'
+            || action.action === 'press'
+          ) action.timeoutMs = timeoutMs;
+        }
+        return this.executeAgentAction(action, { signal: options?.abortSignal });
+      },
+    };
+  }
+
+  public async release(): Promise<void> {
+    if (!this.acquired) return;
+    await this.request('release', {});
+    this.acquired = false;
+  }
+
+  public close(): Promise<void> {
+    if (this.closePromise) return this.closePromise;
+    this.closePromise = this.closeInternal();
+    return this.closePromise;
+  }
+
+  private request(method: string, fields: Record<string, unknown>): Promise<unknown> {
+    return this.requestWithId(randomId(12), method, fields);
+  }
+
+  private async requestWithId(
+    id: string,
+    method: string,
+    fields: Record<string, unknown>,
+  ): Promise<unknown> {
+    this.start();
+    if (this.pending.size >= this.maxPendingRequests) throw new BrowserRuntimeError('BUSY');
+    const responsePromise = new Promise<unknown>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new BrowserRuntimeError('TIMEOUT'));
+      }, this.requestTimeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+    });
+    void responsePromise.catch(() => undefined);
+    try {
+      await this.channel.send({ version: protocolVersion, id, method, ...fields });
+    } catch (error) {
+      const pending = this.pending.get(id);
+      if (pending) {
+        clearTimeout(pending.timer);
+        this.pending.delete(id);
+        pending.reject(error);
+      }
+    }
+    return responsePromise;
+  }
+
+  private handleResponse(message: unknown): void {
+    try {
+      const response = validateExactKeys(message, ['version', 'id', 'ok', 'result', 'error'], 'response');
+      if (response.version !== protocolVersion || typeof response.ok !== 'boolean') {
+        throw new BrowserRuntimeError('PROTOCOL_ERROR');
+      }
+      const id = validateBoundedString(response.id, 'id', 1, 128);
+      const pending = this.pending.get(id);
+      if (!pending) throw new BrowserRuntimeError('PROTOCOL_ERROR');
+      clearTimeout(pending.timer);
+      this.pending.delete(id);
+      if (response.ok) {
+        validateExactKeys(message, ['version', 'id', 'ok', 'result'], 'success response');
+        assertJsonWithoutBytes(response.result, hardMaxFrameBytes);
+        pending.resolve(response.result);
+      } else {
+        validateExactKeys(message, ['version', 'id', 'ok', 'error'], 'error response');
+        const error = validateExactKeys(response.error, ['code', 'message'], 'protocol error');
+        const code = validateBoundedString(error.code, 'error code', 1, 64) as TBrowserRuntimeErrorCode;
+        pending.reject(new BrowserRuntimeError(code));
+      }
+    } catch {
+      void this.close();
+    }
+  }
+
+  private handleClose(): void {
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new BrowserRuntimeError('PROTOCOL_ERROR'));
+    }
+    this.pending.clear();
+    this.acquired = false;
+  }
+
+  private async closeInternal(): Promise<void> {
+    let releaseError: unknown;
+    await this.release().catch((error) => { releaseError = error; });
+    await this.channel.close();
+    this.handleClose();
+    if (releaseError) throw releaseError;
+  }
+}