agl 22.0.4 → 24.0.0

package/ts/classes.flexservice.ts

@@ -64,7 +64,9 @@ import {
   flexIpcMaximumPromptQueueEntries,
   flexIpcMaximumQueuedSessionChangeBytes,
   flexIpcMaximumQueuedSessionChanges,
+  flexIpcMaximumDeltaBytes,
   flexIpcProtocolVersion,
+  flexIpcTargetDeltaBytes,
   isFlexHostResponseResult,
 } from './interfaces.flexipc.js';
 import { openCodeOAuthAuthFromProviderCredential } from './functions.opencodeauth.js';
@@ -78,6 +80,24 @@ type TFlexHarnessEvent = plugins.flexharness.TFlexHarnessEvent;
 
 const flexFailureStatusTimeoutMs = 1_000;
 
+const fragmentUtf8 = (valueArg: string, targetBytesArg: number): string[] => {
+  const fragments: string[] = [];
+  let fragment = '';
+  let fragmentBytes = 0;
+  for (const codePoint of valueArg) {
+    const codePointBytes = Buffer.byteLength(codePoint, 'utf8');
+    if (fragment && fragmentBytes + codePointBytes > targetBytesArg) {
+      fragments.push(fragment);
+      fragment = '';
+      fragmentBytes = 0;
+    }
+    fragment += codePoint;
+    fragmentBytes += codePointBytes;
+  }
+  if (fragment) fragments.push(fragment);
+  return fragments;
+};
+
 const waitForFlexServiceDeadline = async <TValue>(
   promiseArg: Promise<TValue>,
   timeoutMsArg: number,
@@ -452,7 +472,9 @@ export class FlexService {
   private browserFrameReservationCount = 0;
   private browserFrameReservationBytes = 0;
   private readonly sessionChangeQueue = new Map<string, TFlexChildEvent>();
+  private sessionDeltaTailKeys = new Map<string, string>();
   private sessionChangeQueueBytes = 0;
+  private sessionChangeQueueTailKey: string | undefined;
   private sessionChangeFlushRunning = false;
   private hostRequestAdmissionOpen = true;
   private admissionOpen = true;
@@ -2517,9 +2539,28 @@ export class FlexService {
         part: eventArg.part,
       });
     }
+    if (eventArg.type === 'part.delta') {
+      this.queuePartDelta({
+        type: 'part.delta',
+        scopeId: eventArg.scopeId,
+        sessionId: eventArg.sessionId,
+        runId: eventArg.runId,
+        messageId: eventArg.messageId,
+        messageIndex: eventArg.messageIndex,
+        partId: eventArg.partId,
+        partIndex: eventArg.partIndex,
+        sequence: eventArg.sequence,
+        timestamp: eventArg.timestamp,
+        partType: eventArg.partType,
+        delta: eventArg.delta,
+        baseTextUtf8Bytes: eventArg.baseTextUtf8Bytes,
+        textUtf8Bytes: eventArg.textUtf8Bytes,
+      });
+      this.queueSessionChange(eventArg.scopeId, eventArg.sessionId);
+      return;
+    }
     if (
       (eventArg.type === 'part.started'
-        || eventArg.type === 'part.delta'
         || eventArg.type === 'part.completed')
       && eventArg.part.type === 'reasoning'
     ) {
@@ -2538,7 +2579,6 @@ export class FlexService {
     }
     if (
       (eventArg.type === 'part.started'
-        || eventArg.type === 'part.delta'
         || eventArg.type === 'part.completed')
       && eventArg.part.type === 'text'
     ) {
@@ -2949,10 +2989,23 @@ export class FlexService {
     }), 'utf8');
   }
 
+  private getSessionDeltaTailKeys(): Map<string, string> {
+    this.sessionDeltaTailKeys ??= new Map<string, string>();
+    return this.sessionDeltaTailKeys;
+  }
+
   private deleteSessionChangeQueueEntry(keyArg: string): void {
     const existing = this.sessionChangeQueue.get(keyArg);
     if (!existing) return;
     this.sessionChangeQueue.delete(keyArg);
+    const deltaTailKeys = this.getSessionDeltaTailKeys();
+    for (const [partKey, tailKey] of deltaTailKeys) {
+      if (tailKey === keyArg) deltaTailKeys.delete(partKey);
+    }
+    if (this.sessionChangeQueueTailKey === keyArg) {
+      this.sessionChangeQueueTailKey = undefined;
+      for (const key of this.sessionChangeQueue.keys()) this.sessionChangeQueueTailKey = key;
+    }
     this.sessionChangeQueueBytes = Math.max(
       0,
       (this.sessionChangeQueueBytes ?? 0) - this.sessionChangeEventBytes(existing),
@@ -2961,7 +3014,9 @@ export class FlexService {
 
   private clearSessionChangeQueue(): void {
     this.sessionChangeQueue.clear();
+    this.getSessionDeltaTailKeys().clear();
     this.sessionChangeQueueBytes = 0;
+    this.sessionChangeQueueTailKey = undefined;
   }
 
   private setSessionChangeQueueEntry(keyArg: string, eventArg: TFlexChildEvent): boolean {
@@ -2978,6 +3033,7 @@ export class FlexService {
       || nextBytes > flexIpcMaximumQueuedSessionChangeBytes
     ) return false;
     this.sessionChangeQueue.set(keyArg, eventArg);
+    if (!existing) this.sessionChangeQueueTailKey = keyArg;
     this.sessionChangeQueueBytes = nextBytes;
     return true;
   }
@@ -2987,6 +3043,7 @@ export class FlexService {
     this.clearSessionChangeQueue();
     this.sessionChangeQueue.set('*', event);
     this.sessionChangeQueueBytes = this.sessionChangeEventBytes(event);
+    this.sessionChangeQueueTailKey = '*';
   }
 
   private queueToolChange(eventArg: Extract<TFlexChildEvent, {
@@ -3026,6 +3083,78 @@ export class FlexService {
     this.startSessionChangeFlush();
   }
 
+  private queuePartDelta(eventArg: Extract<TFlexChildEvent, { type: 'part.delta' }>): void {
+    if (this.disposing || this.disposed || this.sessionChangeQueue.has('*')) return;
+    const encodedDeltaBytes = Buffer.byteLength(eventArg.delta, 'utf8');
+    const boundaryCorrection = eventArg.textUtf8Bytes
+      - eventArg.baseTextUtf8Bytes
+      - encodedDeltaBytes;
+    const fragments = fragmentUtf8(eventArg.delta, flexIpcTargetDeltaBytes);
+    if (fragments.length === 0) {
+      this.collapseSessionChangeQueue();
+      this.startSessionChangeFlush();
+      return;
+    }
+    let baseTextUtf8Bytes = eventArg.baseTextUtf8Bytes;
+    for (const [fragmentIndex, fragment] of fragments.entries()) {
+      const textUtf8Bytes = baseTextUtf8Bytes
+        + Buffer.byteLength(fragment, 'utf8')
+        + (fragmentIndex === 0 ? boundaryCorrection : 0);
+      if (textUtf8Bytes <= baseTextUtf8Bytes) {
+        this.collapseSessionChangeQueue();
+        this.startSessionChangeFlush();
+        return;
+      }
+      const fragmentEvent: Extract<TFlexChildEvent, { type: 'part.delta' }> = {
+        ...eventArg,
+        delta: fragment,
+        baseTextUtf8Bytes,
+        textUtf8Bytes,
+      };
+      if (!this.enqueuePartDeltaFragment(fragmentEvent)) {
+        this.collapseSessionChangeQueue();
+        this.startSessionChangeFlush();
+        return;
+      }
+      baseTextUtf8Bytes = textUtf8Bytes;
+    }
+    if (baseTextUtf8Bytes !== eventArg.textUtf8Bytes) this.collapseSessionChangeQueue();
+    this.startSessionChangeFlush();
+  }
+
+  private enqueuePartDeltaFragment(
+    eventArg: Extract<TFlexChildEvent, { type: 'part.delta' }>,
+  ): boolean {
+    const partKey = `${eventArg.scopeId}\0${eventArg.sessionId}\0${eventArg.partType}\0${eventArg.partId}`;
+    const deltaTailKeys = this.getSessionDeltaTailKeys();
+    const tailKey = deltaTailKeys.get(partKey);
+    const tail = tailKey ? this.sessionChangeQueue.get(tailKey) : undefined;
+    if (
+      tail?.type === 'part.delta'
+      && tailKey === this.sessionChangeQueueTailKey
+      && tail.textUtf8Bytes === eventArg.baseTextUtf8Bytes
+      && tail.runId === eventArg.runId
+      && tail.messageId === eventArg.messageId
+      && tail.messageIndex === eventArg.messageIndex
+      && tail.partIndex === eventArg.partIndex
+      && Buffer.byteLength(tail.delta, 'utf8') + Buffer.byteLength(eventArg.delta, 'utf8')
+        <= flexIpcMaximumDeltaBytes
+    ) {
+      const merged: Extract<TFlexChildEvent, { type: 'part.delta' }> = {
+        ...tail,
+        sequence: eventArg.sequence,
+        timestamp: eventArg.timestamp,
+        delta: `${tail.delta}${eventArg.delta}`,
+        textUtf8Bytes: eventArg.textUtf8Bytes,
+      };
+      return this.setSessionChangeQueueEntry(tailKey!, merged);
+    }
+    const key = `${partKey}\0${eventArg.baseTextUtf8Bytes}\0${eventArg.sequence}`;
+    if (!this.setSessionChangeQueueEntry(key, eventArg)) return false;
+    deltaTailKeys.set(partKey, key);
+    return true;
+  }
+
 
   private queueSessionChange(scopeIdArg: string, sessionIdArg: string): void {
     const globalKey = '*';
@@ -3069,6 +3198,7 @@ export class FlexService {
       }
     } catch {
       this.clearSessionChangeQueue();
+      await this.closeTransport().catch(() => undefined);
     } finally {
       this.sessionChangeFlushRunning = false;
       if (this.sessionChangeQueue.size > 0 && !this.disposing && !this.disposed) {

package/ts/classes.opencodeclient.ts

@@ -54,6 +54,7 @@ const maxLiveToolExecutionBytes = controllerMaxToolEventBytes - (8 * 1024);
 const maxLiveMessageSnapshotBytes = controllerMaxLiveMessageEventBytes - (8 * 1024);
 const maxLiveMessagePartCacheEntries = 512;
 const maxLiveMessagePartCacheBytes = 4 * 1024 * 1024;
+const maxLiveMessageEventIds = 4_096;
 const maxMetadataStringBytes = 16 * 1024;
 const maxMetadataNodes = 4096;
 const maxCollectionEntries = 512;
@@ -1816,6 +1817,7 @@ export class OpenCodeClientAdapter {
   private readonly sessionMetricsCache = new Map<string, ISessionMetricsCacheEntry>();
   private readonly liveMessagePartCache = new Map<string, IOpenCodeLiveMessagePartCacheEntry>();
   private liveMessagePartCacheBytes = 0;
+  private readonly liveMessageEventIds = new Set<string>();
 
   constructor(options: IOpenCodeClientOptions) {
     this.directory = plugins.fs.realpathSync.native(options.directory);
@@ -3651,6 +3653,21 @@ export class OpenCodeClientAdapter {
   private clearLiveMessagePartCache(): void {
     this.liveMessagePartCache.clear();
     this.liveMessagePartCacheBytes = 0;
+    this.liveMessageEventIds.clear();
+  }
+
+  private acceptLiveMessageEventId(payloadArg: Record<string, unknown>): boolean {
+    if (typeof payloadArg.id !== 'string' || Buffer.byteLength(payloadArg.id, 'utf8') > 512) {
+      return true;
+    }
+    if (this.liveMessageEventIds.has(payloadArg.id)) return false;
+    this.liveMessageEventIds.add(payloadArg.id);
+    while (this.liveMessageEventIds.size > maxLiveMessageEventIds) {
+      const oldest = this.liveMessageEventIds.values().next().value;
+      if (oldest === undefined) break;
+      this.liveMessageEventIds.delete(oldest);
+    }
+    return true;
   }
 
   private clearLiveMessagePartsForSession(directoryArg: string, sessionIdArg: string): void {
@@ -3743,6 +3760,7 @@ export class OpenCodeClientAdapter {
     };
 
     if (payload.type === 'message.part.updated') {
+      if (!this.acceptLiveMessageEventId(payload)) return undefined;
       if (!isRecord(properties.part)) {
         this.clearLiveMessagePartCache();
         return {
@@ -3819,6 +3837,7 @@ export class OpenCodeClientAdapter {
     }
 
     if (payload.type === 'message.part.delta') {
+      if (!this.acceptLiveMessageEventId(payload)) return undefined;
       try {
         const validatedSessionId = requireString(
           properties.sessionID,

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.flexipc.ts

@@ -32,8 +32,10 @@ export type TFlexTurnReversionCaptureInspectionV2 =
 export type TFlexTurnReversionApplyInspection =
   plugins.flexharness.IFlexTurnReversionApplyInspection;
 
-export const flexIpcProtocolVersion = 14 as const;
+export const flexIpcProtocolVersion = 15 as const;
 export const flexIpcMaximumFrameBytes = 2 * 1024 * 1024;
+export const flexIpcTargetDeltaBytes = 16 * 1024;
+export const flexIpcMaximumDeltaBytes = 32 * 1024;
 export const flexIpcMaximumPendingRequests = 64;
 export const flexIpcMaximumBrowserChannels = 128;
 export const flexIpcMaximumBrowserFrameBytes = 256 * 1024 + 4;
@@ -764,6 +766,22 @@ export type TFlexChildEvent =
       status: 'running' | 'completed';
       part: TFlexTextMessagePart;
     }
+  | {
+      type: 'part.delta';
+      scopeId: string;
+      sessionId: string;
+      runId: string;
+      messageId: string;
+      messageIndex: number;
+      partId: string;
+      partIndex: number;
+      sequence: number;
+      timestamp: string;
+      partType: 'text' | 'reasoning';
+      delta: string;
+      baseTextUtf8Bytes: number;
+      textUtf8Bytes: number;
+    }
   | {
       type: 'prompt.queued';
       scopeId: string;
@@ -945,6 +963,20 @@ const isBoundedString = (
   && (allowEmptyArg || valueArg.length > 0)
   && Buffer.byteLength(valueArg, 'utf8') <= maximumBytesArg;
 
+const hasExactDeltaUtf8Coordinates = (
+  deltaArg: string,
+  baseTextUtf8BytesArg: number,
+  textUtf8BytesArg: number,
+): boolean => {
+  const encodedDeltaBytes = Buffer.byteLength(deltaArg, 'utf8');
+  const increment = textUtf8BytesArg - baseTextUtf8BytesArg;
+  if (increment === encodedDeltaBytes) return true;
+  const firstCodeUnit = deltaArg.charCodeAt(0);
+  return firstCodeUnit >= 0xDC00
+    && firstCodeUnit <= 0xDFFF
+    && increment === encodedDeltaBytes - 2;
+};
+
 const isIdentifier = (valueArg: unknown): valueArg is string =>
   isBoundedString(valueArg, 512) && identifierPattern.test(valueArg);
 
@@ -1244,15 +1276,15 @@ const isUsage = (valueArg: unknown): boolean => isFlexPlainObject(valueArg)
   ])
   && Object.values(valueArg).every(isNonNegativeInteger);
 
-const isMessagePart = (valueArg: unknown): boolean => {
+const isMessagePart = (valueArg: unknown, textByteLimitArg = 96 * 1024): boolean => {
   if (!isFlexPlainObject(valueArg) || !isIdentifier(valueArg.partId)) return false;
   switch (valueArg.type) {
     case 'text':
       return hasFlexExactKeys(valueArg, ['partId', 'type', 'text'])
-        && isBoundedString(valueArg.text, 96 * 1024, true);
+        && isBoundedString(valueArg.text, textByteLimitArg, true);
     case 'reasoning':
       return hasFlexExactKeys(valueArg, ['partId', 'type', 'text', 'status'])
-        && isBoundedString(valueArg.text, 96 * 1024, true)
+        && isBoundedString(valueArg.text, textByteLimitArg, true)
         && ['running', 'completed', 'cancelled'].includes(String(valueArg.status));
     case 'tool':
       return hasFlexExactKeys(
@@ -1302,7 +1334,7 @@ export const isFlexPublicMessage = (valueArg: unknown): valueArg is TFlexMessage
   && (valueArg.completedAt === undefined || isIsoDate(valueArg.completedAt))
   && Array.isArray(valueArg.parts)
   && valueArg.parts.length <= 2000
-  && valueArg.parts.every(isMessagePart)
+  && valueArg.parts.every((partArg) => isMessagePart(partArg))
   && (valueArg.model === undefined || isModelIdentity(valueArg.model))
   && (valueArg.usage === undefined || isUsage(valueArg.usage))
   && (valueArg.error === undefined || isBoundedString(valueArg.error, 2048));
@@ -2339,7 +2371,7 @@ const isFlexChildEvent = (valueArg: unknown): valueArg is TFlexChildEvent => {
         && isIsoDate(valueArg.timestamp)
         && isFlexPlainObject(valueArg.part)
         && valueArg.part.type === 'reasoning'
-        && isMessagePart(valueArg.part);
+        && isMessagePart(valueArg.part, flexIpcMaximumFrameBytes - (16 * 1024));
     case 'text.updated':
       return hasFlexExactKeys(valueArg, [
         'type', 'scopeId', 'sessionId', 'runId', 'messageId',
@@ -2357,7 +2389,33 @@ const isFlexChildEvent = (valueArg: unknown): valueArg is TFlexChildEvent => {
         && ['running', 'completed'].includes(String(valueArg.status))
         && isFlexPlainObject(valueArg.part)
         && valueArg.part.type === 'text'
-        && isMessagePart(valueArg.part);
+        && isMessagePart(valueArg.part, flexIpcMaximumFrameBytes - (16 * 1024));
+    case 'part.delta':
+      return hasFlexExactKeys(valueArg, [
+        'type', 'scopeId', 'sessionId', 'runId', 'messageId', 'messageIndex', 'partId',
+        'partIndex', 'sequence', 'timestamp', 'partType', 'delta',
+        'baseTextUtf8Bytes', 'textUtf8Bytes',
+      ])
+        && isIdentifier(valueArg.scopeId)
+        && isIdentifier(valueArg.sessionId)
+        && isIdentifier(valueArg.runId)
+        && isIdentifier(valueArg.messageId)
+        && isIdentifier(valueArg.partId)
+        && isNonNegativeInteger(valueArg.messageIndex)
+        && isNonNegativeInteger(valueArg.partIndex)
+        && isNonNegativeInteger(valueArg.sequence)
+        && valueArg.sequence >= 1
+        && isIsoDate(valueArg.timestamp)
+        && (valueArg.partType === 'text' || valueArg.partType === 'reasoning')
+        && isBoundedString(valueArg.delta, flexIpcMaximumDeltaBytes)
+        && isNonNegativeInteger(valueArg.baseTextUtf8Bytes)
+        && isNonNegativeInteger(valueArg.textUtf8Bytes)
+        && valueArg.textUtf8Bytes > valueArg.baseTextUtf8Bytes
+        && hasExactDeltaUtf8Coordinates(
+          valueArg.delta,
+          valueArg.baseTextUtf8Bytes,
+          valueArg.textUtf8Bytes,
+        );
     case 'prompt.queued':
     case 'prompt.started':
     case 'prompt.running':

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';