agl 23.0.0 → 24.0.0

package/ts/classes.validation.ts

@@ -5,6 +5,7 @@ import {
   controllerMaxDraftAttachmentTotalBytes,
   controllerMaxDraftAttachments,
   controllerMaxDraftTextBytes,
+  controllerBrowserTransportProtocol,
   controllerRuntimeIdKey,
   controllerSessionHarnessIds,
 } from '../ts_interfaces/index.js';
@@ -1065,7 +1066,7 @@ const assertBrowserViewport = (
     || typeof value.deviceScaleFactor !== 'number'
     || !Number.isFinite(value.deviceScaleFactor)
     || value.deviceScaleFactor < 0.25
-    || value.deviceScaleFactor > 4
+    || value.deviceScaleFactor > 3
   ) throw new Error(`${nameArg} is invalid.`);
   return value as unknown as interfaces.IControllerBrowserViewport;
 };
@@ -1121,21 +1122,50 @@ export const assertBrowserViewCloseRequest = (
   valueArg: unknown,
 ): interfaces.IReq_ControllerBrowserViewClose['request'] => {
   const value = assertObject(valueArg, 'browser view close request');
-  assertKeys(value, ['viewId']);
-  return { viewId: assertIdentifier(value.viewId, 'viewId') };
+  assertKeys(value, ['viewId', 'expectedStreamGeneration']);
+  return {
+    viewId: assertIdentifier(value.viewId, 'viewId'),
+    expectedStreamGeneration: assertBrowserStreamGeneration(value.expectedStreamGeneration),
+  };
 };
 
 export const assertBrowserViewActivateRequest = (
   valueArg: unknown,
 ): interfaces.IReq_ControllerBrowserViewActivate['request'] => {
   const value = assertObject(valueArg, 'browser view activation request');
-  assertKeys(value, ['viewId']);
-  return { viewId: assertIdentifier(value.viewId, 'viewId') };
+  assertKeys(value, ['viewId', 'streamGeneration']);
+  return {
+    viewId: assertIdentifier(value.viewId, 'viewId'),
+    streamGeneration: assertBrowserStreamGeneration(value.streamGeneration),
+  };
+};
+
+const assertBrowserStreamGeneration = (valueArg: unknown): number => {
+  if (!Number.isSafeInteger(valueArg) || (valueArg as number) < 1) {
+    throw new Error('streamGeneration is invalid.');
+  }
+  return valueArg as number;
 };
 
+export const assertBrowserViewRecoverRequest = (
+  valueArg: unknown,
+): interfaces.IReq_ControllerBrowserViewRecover['request'] => {
+  const value = assertObject(valueArg, 'browser view recovery request');
+  assertKeys(value, ['viewId', 'expectedStreamGeneration']);
+  return {
+    viewId: assertIdentifier(value.viewId, 'viewId'),
+    expectedStreamGeneration: assertBrowserStreamGeneration(value.expectedStreamGeneration),
+  };
+};
+
+interface IBrowserViewOperationEnvelope {
+  viewId: string;
+  operation: interfaces.TControllerBrowserViewOperation;
+}
+
 export const assertBrowserViewOperateRequest = (
   valueArg: unknown,
-): interfaces.IReq_ControllerBrowserViewOperate['request'] => {
+): IBrowserViewOperationEnvelope => {
   const value = assertObject(valueArg, 'browser view operation request');
   assertKeys(value, ['viewId', 'operation']);
   const operation = assertObject(value.operation, 'operation');
@@ -1304,6 +1334,47 @@ export const assertBrowserViewOperateRequest = (
   throw new Error('operation.type is unsupported.');
 };
 
+export const assertBrowserViewOperation = (
+  valueArg: unknown,
+): interfaces.TControllerBrowserViewOperation => assertBrowserViewOperateRequest({
+  viewId: 'browser-operation',
+  operation: valueArg,
+}).operation;
+
+export const assertControllerBrowserClientPacket = (
+  valueArg: unknown,
+): interfaces.TControllerBrowserClientPacket => {
+  const value = assertObject(valueArg, 'browser transport packet');
+  if (value.protocol !== controllerBrowserTransportProtocol) {
+    throw new Error('browser transport protocol is invalid.');
+  }
+  const streamGeneration = assertBrowserStreamGeneration(value.streamGeneration);
+  if (!Number.isSafeInteger(value.operationId) || (value.operationId as number) < 1) {
+    throw new Error('operationId is invalid.');
+  }
+  const operationId = value.operationId as number;
+  if (value.type === 'operation') {
+    assertKeys(value, ['protocol', 'streamGeneration', 'type', 'operationId', 'operation']);
+    return {
+      protocol: controllerBrowserTransportProtocol,
+      streamGeneration,
+      type: 'operation',
+      operationId,
+      operation: assertBrowserViewOperation(value.operation),
+    };
+  }
+  if (value.type === 'cancel') {
+    assertKeys(value, ['protocol', 'streamGeneration', 'type', 'operationId']);
+    return {
+      protocol: controllerBrowserTransportProtocol,
+      streamGeneration,
+      type: 'cancel',
+      operationId,
+    };
+  }
+  throw new Error('browser transport packet type is unsupported.');
+};
+
 export const assertTerminalCreateRequest = (
   valueArg: unknown,
 ): interfaces.IReq_ControllerTerminalCreate['request'] => {

package/ts_interfaces/browsertransport.ts

@@ -0,0 +1,126 @@
+import type {
+  IControllerBrowserFrameMetadata,
+  IControllerBrowserViewState,
+  TControllerBrowserViewOperation,
+} from './interfaces.js';
+
+export const controllerBrowserTransportProtocol = 'agl-browser-v24' as const;
+export const controllerBrowserTransportEventContentType =
+  'application/vnd.agl.browser-events.v24' as const;
+export const controllerBrowserTransportOperationContentType =
+  'application/vnd.agl.browser-operations.v24' as const;
+export const controllerBrowserTransportMaximumJsonBytes = 64 * 1024;
+export const controllerBrowserTransportMaximumFrameBytes = 4 * 1024 * 1024;
+export const controllerBrowserTransportPairOpenTimeoutMs = 9_000;
+export const controllerBrowserTransportRecoveryGraceMs = 15_000;
+export const controllerBrowserTransportMaximumRecoveryAttempts = 3;
+export const controllerBrowserTransportMaximumPendingOperations = 64;
+export const controllerBrowserTransportMaximumQueuedOperationBytes = 256 * 1024;
+export const controllerBrowserTransportMaximumActiveAcknowledgements = 16;
+export const controllerBrowserTransportMaximumPendingEvents = 16;
+export const controllerBrowserTransportMaximumPendingEventBytes = 16 * 1024 * 1024;
+
+interface IControllerBrowserTransportPacketBase {
+  protocol: typeof controllerBrowserTransportProtocol;
+  streamGeneration: number;
+}
+
+export interface IControllerBrowserOperationPacket extends IControllerBrowserTransportPacketBase {
+  type: 'operation';
+  operationId: number;
+  operation: TControllerBrowserViewOperation;
+}
+
+export interface IControllerBrowserCancelPacket extends IControllerBrowserTransportPacketBase {
+  type: 'cancel';
+  operationId: number;
+}
+
+export type TControllerBrowserClientPacket =
+  | IControllerBrowserOperationPacket
+  | IControllerBrowserCancelPacket;
+
+export type TControllerBrowserOperationResult =
+  | {
+      status: 'succeeded';
+      accepted?: boolean;
+      state?: IControllerBrowserViewState;
+    }
+  | { status: 'failed'; error: { code: string; message: string } }
+  | { status: 'cancelled' }
+  | { status: 'superseded' };
+
+export interface IControllerBrowserStatePacket extends IControllerBrowserTransportPacketBase {
+  type: 'state';
+  state: IControllerBrowserViewState;
+}
+
+export interface IControllerBrowserErrorPacket extends IControllerBrowserTransportPacketBase {
+  type: 'error';
+  error: { code: string; message: string; fatal: boolean; tabId?: string };
+}
+
+export interface IControllerBrowserOperationResultPacket
+  extends IControllerBrowserTransportPacketBase {
+  type: 'operationResult';
+  operationId: number;
+  result: TControllerBrowserOperationResult;
+}
+
+export interface IControllerBrowserFramePacket extends IControllerBrowserTransportPacketBase {
+  type: 'frame';
+  frame: IControllerBrowserFrameMetadata;
+}
+
+export type TControllerBrowserServerPacket =
+  | IControllerBrowserStatePacket
+  | IControllerBrowserErrorPacket
+  | IControllerBrowserOperationResultPacket
+  | IControllerBrowserFramePacket;
+
+export class ControllerBrowserTransportProtocolError extends Error {
+  constructor(messageArg: string, optionsArg?: ErrorOptions) {
+    super(messageArg, optionsArg);
+    this.name = 'ControllerBrowserTransportProtocolError';
+  }
+}
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder('utf-8', { fatal: true });
+
+export const encodeControllerBrowserTransportPacket = (
+  packetArg: TControllerBrowserClientPacket | TControllerBrowserServerPacket,
+): Uint8Array => {
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(packetArg);
+  } catch (errorArg) {
+    throw new ControllerBrowserTransportProtocolError(
+      'The browser transport packet is not JSON serializable.',
+      { cause: errorArg },
+    );
+  }
+  const bytes = textEncoder.encode(serialized);
+  if (bytes.byteLength > controllerBrowserTransportMaximumJsonBytes) {
+    throw new ControllerBrowserTransportProtocolError(
+      'The browser transport packet exceeds the JSON byte limit.',
+    );
+  }
+  return bytes;
+};
+
+export const decodeControllerBrowserTransportPacket = (bytesArg: Uint8Array): unknown => {
+  if (bytesArg.byteLength > controllerBrowserTransportMaximumJsonBytes) {
+    throw new ControllerBrowserTransportProtocolError(
+      'The browser transport packet exceeds the JSON byte limit.',
+    );
+  }
+  try {
+    return JSON.parse(textDecoder.decode(bytesArg));
+  } catch (errorArg) {
+    throw new ControllerBrowserTransportProtocolError(
+      'The browser transport packet is not valid UTF-8 JSON.',
+      { cause: errorArg },
+    );
+  }
+};

package/ts_interfaces/index.ts

@@ -1,2 +1,3 @@
 export * from './interfaces.js';
+export * from './browsertransport.js';
 export * from './requests.js';

package/ts_interfaces/interfaces.ts

@@ -1,6 +1,4 @@
-import * as plugins from './plugins.js';
-
-export const controllerProtocolVersion = 23 as const;
+export const controllerProtocolVersion = 24 as const;
 export const controllerUpgradeManagementVersion = 2 as const;
 export const controllerPackageName = 'agl' as const;
 export const controllerMaxToolEventBytes = 48 * 1024;
@@ -223,6 +221,8 @@ export interface IControllerBrowserTabState {
 }
 
 export interface IControllerBrowserViewState {
+  /** Monotonic for the complete lifetime of one browser view. */
+  revision: number;
   status: 'stopped' | 'starting' | 'running' | 'stopping';
   activeTabId: string | null;
   viewportRevision: number;
@@ -231,9 +231,7 @@ export interface IControllerBrowserViewState {
   lastError?: { code: string; message: string; fatal: boolean; tabId?: string };
 }
 
-export interface IControllerBrowserFrame<
-  TDirection extends plugins.typedrequestInterfaces.TVirtualStreamDirection,
-> {
+export interface IControllerBrowserFrameMetadata {
   tabId: string;
   sequence: number;
   generation: number;
@@ -252,14 +250,16 @@ export interface IControllerBrowserFrame<
     scrollOffsetY: number;
     timestamp?: number;
   };
-  dataStream: plugins.typedrequestInterfaces.TVirtualStream<TDirection>;
+  dataByteLength: number;
+}
+
+export interface IControllerBrowserFrame extends Omit<IControllerBrowserFrameMetadata, 'dataByteLength'> {
+  data: Uint8Array;
 }
 
-export type TControllerBrowserViewEvent<
-  TDirection extends plugins.typedrequestInterfaces.TVirtualStreamDirection,
-> =
+export type TControllerBrowserViewEvent =
   | { type: 'state'; state: IControllerBrowserViewState }
-  | { type: 'frame'; frame: IControllerBrowserFrame<TDirection> }
+  | { type: 'frame'; frame: IControllerBrowserFrame }
   | { type: 'error'; error: { code: string; message: string; fatal: boolean; tabId?: string } };
 
 export interface IControllerBrowserFrameAcknowledgement {

package/ts_interfaces/requests.ts

@@ -10,8 +10,6 @@ import type {
   TControllerResource,
   TControllerResourceKind,
   IControllerBrowserViewState,
-  TControllerBrowserViewEvent,
-  TControllerBrowserViewOperation,
   IControllerProvider,
   IControllerProviderAccountRateLimits,
   IControllerProviderConnection,
@@ -927,6 +925,9 @@ export interface IReq_ControllerBrowserViewOpen extends plugins.typedrequestInte
     viewId: string;
     resourceId: string;
     attachmentRevision: number;
+    streamGeneration: number;
+    events: plugins.typedrequestInterfaces.TVirtualStream<'receive'>;
+    operations: plugins.typedrequestInterfaces.TVirtualStream<'send'>;
     state: IControllerBrowserViewState;
   };
 }
@@ -936,41 +937,34 @@ export interface IReq_ControllerBrowserViewActivate extends plugins.typedrequest
   IReq_ControllerBrowserViewActivate
 > {
   method: 'controller.browser.view.activate';
-  request: { viewId: string };
+  request: { viewId: string; streamGeneration: number };
   response: { activated: true };
 }
 
-export interface IReq_ControllerBrowserViewClose extends plugins.typedrequestInterfaces.implementsTR<
-  plugins.typedrequestInterfaces.ITypedRequest,
-  IReq_ControllerBrowserViewClose
-> {
-  method: 'controller.browser.view.close';
-  request: { viewId: string };
-  response: { closed: true };
-}
-
-export interface IReq_ControllerBrowserViewOperate extends plugins.typedrequestInterfaces.implementsTR<
-  plugins.typedrequestInterfaces.ITypedRequest,
-  IReq_ControllerBrowserViewOperate
-> {
-  method: 'controller.browser.view.operate';
-  request: { viewId: string; operation: TControllerBrowserViewOperation };
-  response: { accepted: boolean; state: IControllerBrowserViewState };
-}
-
-/** Server to client push for one exact human browser view. */
-export interface IReq_ControllerBrowserViewEvent extends plugins.typedrequestInterfaces.implementsTR<
+export interface IReq_ControllerBrowserViewRecover extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
-  IReq_ControllerBrowserViewEvent
+  IReq_ControllerBrowserViewRecover
 > {
-  method: 'controller.browser.view.event';
-  request: {
+  method: 'controller.browser.view.recover';
+  request: { viewId: string; expectedStreamGeneration: number };
+  response: {
     viewId: string;
     resourceId: string;
     attachmentRevision: number;
-    event: TControllerBrowserViewEvent<'send'>;
+    streamGeneration: number;
+    events: plugins.typedrequestInterfaces.TVirtualStream<'receive'>;
+    operations: plugins.typedrequestInterfaces.TVirtualStream<'send'>;
+    state: IControllerBrowserViewState;
   };
-  response: Record<string, never>;
+}
+
+export interface IReq_ControllerBrowserViewClose extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ControllerBrowserViewClose
+> {
+  method: 'controller.browser.view.close';
+  request: { viewId: string; expectedStreamGeneration: number };
+  response: { closed: boolean };
 }
 
 export interface IReq_ControllerTerminalCreate extends plugins.typedrequestInterfaces.implementsTR<
@@ -1171,8 +1165,8 @@ export type TControllerRequest =
   | IReq_ControllerResourceStop
   | IReq_ControllerBrowserViewOpen
   | IReq_ControllerBrowserViewActivate
+  | IReq_ControllerBrowserViewRecover
   | IReq_ControllerBrowserViewClose
-  | IReq_ControllerBrowserViewOperate
   | IReq_ControllerTerminalList
   | IReq_ControllerTerminalCreate
   | IReq_ControllerTerminalRename
@@ -1182,5 +1176,4 @@ export type TControllerRequest =
   | IReq_ControllerTerminalInput
   | IReq_ControllerTerminalResize
   | IReq_ControllerTerminalOutput
-  | IReq_ControllerBrowserViewEvent
   | IReq_ControllerEvent;

package/ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: 'agl',
-  version: '23.0.0',
+  version: '24.0.0',
   description: 'Agent Gateway Layer for OpenCode and FlexHarness sessions'
 }