@modelprofile.com/browser-runtime 5.8.0 → 6.0.0

package/dist_ts/interfaces.d.ts

@@ -24,7 +24,11 @@ export interface IBrowserResourceKey {
 export interface IBrowserAttachmentBinding {
     attachmentAuthorityId: string;
     attachmentRevision: number;
-    sessionId: TQualifiedBrowserSessionId | null;
+    /**
+     * The set of sessions attached to the resource. Order is not significant and duplicates are
+     * rejected. An empty set is detached, and revision `0` requires an empty set.
+     */
+    sessionIds: TQualifiedBrowserSessionId[];
 }
 export interface ICreateBrowserResourceRequest {
     projectId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelprofile.com/browser-runtime",
-  "version": "5.8.0",
+  "version": "6.0.0",
   "private": false,
   "description": "Parent-owned, resource-centric Chromium runtime with revisioned attachment fencing, authenticated human and agent control, fail-closed egress, bounded artifacts, and Flex/MCP adapters.",
   "main": "dist_ts/index.js",
@@ -35,7 +35,7 @@
   "devDependencies": {
     "@git.zone/tsbuild": "4.4.3",
     "@git.zone/tsrun": "2.0.6",
-    "@git.zone/tstest": "6.0.0",
+    "@git.zone/tstest": "6.1.1",
     "@types/node": "26.5.0"
   },
   "files": [

package/readme.md

@@ -86,7 +86,7 @@ try {
     attachmentBinding: {
       attachmentAuthorityId: 'controller-attachment-1',
       attachmentRevision: 1,
-      sessionId: { harnessId: 'opencode', nativeId: 'session-456' },
+      sessionIds: [{ harnessId: 'opencode', nativeId: 'session-456' }],
     },
   });
 
@@ -149,7 +149,7 @@ To downgrade, first stop the new runtime and verify that no process still uses a
 
 ## Attachment Fencing
 
-Attachment bindings are Controller-owned `{ attachmentAuthorityId, attachmentRevision, sessionId }` values. Any binding with `sessionId: null` is detached; revision `0` is the initial detached/no-agent-authority state. Reapplying the identical revision and binding is idempotent; lower revisions and conflicting equal revisions fail.
+Attachment bindings are Controller-owned `{ attachmentAuthorityId, attachmentRevision, sessionIds }` values. `sessionIds` is the set of sessions attached to the resource, so one browser resource can serve several conversations at once. Order is not significant, duplicate members are rejected with `INVALID_INPUT`, and a set larger than 64 members is rejected with `QUOTA_EXCEEDED`. An empty set is detached; revision `0` is the initial detached/no-agent-authority state and requires an empty set. Reapplying the identical revision and set is idempotent, including in a different order; lower revisions and conflicting equal revisions fail.
 
 ```typescript
 await runtime.applyAttachmentBinding({
@@ -158,12 +158,14 @@ await runtime.applyAttachmentBinding({
   attachmentBinding: {
     attachmentAuthorityId: 'controller-attachment-1',
     attachmentRevision: 2,
-    sessionId: null,
+    sessionIds: [],
   },
 });
 ```
 
-A newer binding fences agent admission, revokes older agent capabilities, and quiesces their active work. Human viewers retain their resource authority and subscriptions. The incarnation is preserved unless an operation cannot quiesce; that failure requires terminating the resource's browser process.
+A newer binding fences only the sessions that left the set. Their leases and in-flight operations are aborted with `CAPABILITY_REVOKED` naming the session, their framed channels are closed, and their agent capabilities are revoked. Sessions that stay in the set keep their leases, framed channels and capabilities: nothing of theirs is aborted, closed or revoked, so once the rebind completes they carry on exactly as before and adding a session never interrupts the sessions already attached. While the rebind is still fencing, a session that is still in the set is never revoked: both issuing a new capability and operating an existing lease fail with `BUSY`, which is retryable, and the same call succeeds once the rebind settles. From the moment the rebind commits the new set, a session it removed is told it is gone — `CAPABILITY_REVOKED` — for the rest of that rebind, so the two outcomes are never confused. Before that commit the removal has not happened yet and may still not happen, so a session the queued rebind will remove also reports `BUSY` and should retry. Detaching with an empty set therefore releases every attached session. Human viewers retain their resource authority and subscriptions. The incarnation is preserved unless an operation cannot quiesce; that failure requires terminating the resource's browser process.
+
+The revision fence is per session: a capability survives exactly as long as its session stays continuously attached; leaving and rejoining invalidates the old ones. Concretely, a capability is admitted while its session is a current member and the capability's `attachmentRevision` is at least the revision at which that session joined the set and no newer than the current revision. A session that leaves and later rejoins gets the newer join revision, so every capability it held before it left is rejected. Human capabilities carry no session and keep the exact-revision fence.
 
 Agent capabilities require the exact current non-detached qualified session. Human capabilities carry no session ID and may be issued while detached. Issuance validates the current attachment binding, but an issued human capability remains valid across attachment changes: hosts must authorize it against its project, resource, actor and peer rather than the resource's later agent assignment.
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/browser-runtime',
-  version: '5.8.0',
+  version: '6.0.0',
   description: 'Parent-owned, resource-centric Chromium runtime with revisioned attachment fencing, authenticated human and agent control, fail-closed egress, bounded artifacts, and Flex/MCP adapters.'
 }

package/ts/classes.framed.ts

@@ -292,6 +292,11 @@ export class BrowserRuntimeFramedServerPeer {
     return this.trustedChannelId;
   }
 
+  /** The single session this peer acts for. Used to fence only the sessions a rebind removed. */
+  public get sessionId(): IBrowserFlexSessionId {
+    return { ...this.trustedSessionId };
+  }
+
   /** @internal */
   public get activeCapabilityId(): string | undefined {
     return this.capabilityId ?? this.pendingCapabilityId;

package/ts/classes.runtime.ts

@@ -61,6 +61,8 @@ import { BrowserRuntimeFramedServerPeer } from './classes.framed.js';
 
 // @push.rocks/smartpuppeteer LiveBrowserSession rejects screencast bounds above this area.
 const maxScreencastPixelArea = 8_294_400;
+/** Upper bound on how many conversations may share one browser resource at once. */
+const maximumAttachedSessions = 64;
 
 interface INormalizedScreencastOptions {
   quality: number;
@@ -259,7 +261,16 @@ interface IResourceSlot {
   permanentlyFenced: boolean;
   retirementPending: boolean;
   attachmentFenceCount: number;
+  /**
+   * Revision at which each currently attached session joined the set, keyed by session key. Only
+   * current members are present, so this doubles as the membership index. A member that stays
+   * across a rebind keeps its original join revision; a member that leaves and rejoins gets the
+   * new one, which is what invalidates its older capabilities.
+   */
+  sessionJoinRevisions: Map<string, number>;
   attachmentRetryBinding?: IBrowserAttachmentBinding;
+  /** Sessions that left the set in the rebind `attachmentRetryBinding` is retrying. */
+  attachmentRetryRemovedKeys?: Set<string>;
   session?: ILiveBrowserSessionLike;
   proxy?: BrowserEgressProxy;
   profileDirectory?: string;
@@ -743,6 +754,9 @@ export class BrowserRuntime {
       permanentlyFenced: false,
       retirementPending: false,
       attachmentFenceCount: 0,
+      sessionJoinRevisions: new Map(attachmentBinding.sessionIds.map((session) => (
+        [this.sessionKey(session), attachmentBinding.attachmentRevision]
+      ))),
       leases: new Map(),
       frameSubscriptions: new Map(),
       highestFrameSequence: 0,
@@ -4037,34 +4051,65 @@ export class BrowserRuntime {
     if (slot.attachmentRetryBinding && !this.bindingsEqual(binding, slot.attachmentRetryBinding)) {
       throw new BrowserRuntimeError('BUSY');
     }
+    // Members that stay keep their original join revision, so their capabilities stay valid and
+    // nothing of theirs is torn down. Only the sessions that left the set are fenced.
+    const nextJoinRevisions = new Map<string, number>();
+    for (const session of binding.sessionIds) {
+      const key = this.sessionKey(session);
+      nextJoinRevisions.set(
+        key,
+        slot.sessionJoinRevisions.get(key) ?? binding.attachmentRevision,
+      );
+    }
+    const removedKeys = slot.attachmentRetryRemovedKeys ?? new Set(
+      [...slot.sessionJoinRevisions.keys()].filter((key) => !nextJoinRevisions.has(key)),
+    );
+    const revokedFor = (key: string): BrowserRuntimeError => new BrowserRuntimeError(
+      'CAPABILITY_REVOKED',
+      `attachment released session ${key}`,
+    );
     const release = await slot.mutex.acquire();
     try {
       slot.attachmentBinding = binding;
       slot.attachmentRetryBinding = binding;
+      slot.attachmentRetryRemovedKeys = removedKeys;
+      slot.sessionJoinRevisions = nextJoinRevisions;
       for (const lease of slot.leases.values()) {
-        if (lease.role === 'agent') {
-          lease.controller.abort(new BrowserRuntimeError('CAPABILITY_REVOKED'));
-        }
+        if (lease.role !== 'agent') continue;
+        const key = this.leaseSessionKey(lease);
+        if (key === undefined || !removedKeys.has(key)) continue;
+        lease.controller.abort(revokedFor(key));
       }
       for (const operation of slot.operations) {
-        if (operation.lease.role === 'agent') operation.controller.abort(new BrowserRuntimeError('CAPABILITY_REVOKED'));
+        if (operation.lease.role !== 'agent') continue;
+        const key = this.leaseSessionKey(operation.lease);
+        if (key === undefined || !removedKeys.has(key)) continue;
+        operation.controller.abort(revokedFor(key));
       }
     } finally {
       release();
     }
     const peerResults = await Promise.allSettled(
-      this.framedPeersForResource(slot).map((peer) => peer.close()),
+      this.framedPeersForResource(slot)
+        .filter((peer) => removedKeys.has(this.sessionKey(peer.sessionId)))
+        .map((peer) => peer.close()),
     );
     const capabilityResults = await Promise.allSettled(
-      this.capabilitiesForResource(slot).filter((record) => record.role === 'agent')
-        .map((record) => this.revokeCapabilityRecord(record)),
+      this.capabilitiesForResource(slot).filter((record) => (
+        record.role === 'agent'
+        && record.sessionId !== undefined
+        && removedKeys.has(this.sessionKey(record.sessionId))
+      )).map((record) => this.revokeCapabilityRecord(record)),
     );
     const errors = [...peerResults, ...capabilityResults]
       .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
       .map((result) => result.reason);
     const finalRelease = await slot.mutex.acquire();
     try {
-      if (errors.length === 0) slot.attachmentRetryBinding = undefined;
+      if (errors.length === 0) {
+        slot.attachmentRetryBinding = undefined;
+        slot.attachmentRetryRemovedKeys = undefined;
+      }
     } finally {
       finalRelease();
     }
@@ -4073,10 +4118,9 @@ export class BrowserRuntime {
   }
 
   private attachmentBindingKey(binding: IBrowserAttachmentBinding): string {
-    const session = binding.sessionId
-      ? `${binding.sessionId.harnessId}:${binding.sessionId.nativeId}`
-      : 'detached';
-    return `${binding.attachmentRevision}:${binding.attachmentAuthorityId}:${session}`;
+    return `${binding.attachmentRevision}:${binding.attachmentAuthorityId}:${
+      this.sessionSetKey(binding.sessionIds)
+    }`;
   }
 
   private tombstoneIndex(value: string, seed: number): number {
@@ -4141,7 +4185,7 @@ export class BrowserRuntime {
     if (Object.keys(record).some((key) => (
       key !== 'attachmentAuthorityId'
       && key !== 'attachmentRevision'
-      && key !== 'sessionId'
+      && key !== 'sessionIds'
     ))) throw new BrowserRuntimeError('INVALID_INPUT');
     const attachmentRevision = validateInteger(
       record.attachmentRevision,
@@ -4149,10 +4193,21 @@ export class BrowserRuntime {
       0,
       Number.MAX_SAFE_INTEGER,
     );
-    const sessionId = record.sessionId === null
-      ? null
-      : this.validateQualifiedSessionId(record.sessionId);
-    if (attachmentRevision === 0 && sessionId !== null) {
+    if (!Array.isArray(record.sessionIds)) throw new BrowserRuntimeError('INVALID_INPUT');
+    if (record.sessionIds.length > maximumAttachedSessions) {
+      throw new BrowserRuntimeError('QUOTA_EXCEEDED');
+    }
+    const sessionIds: TQualifiedBrowserSessionId[] = [];
+    const seen = new Set<string>();
+    for (const entry of record.sessionIds) {
+      const session = this.validateQualifiedSessionId(entry);
+      const key = this.sessionKey(session);
+      // The binding is a set. A repeated member is a caller defect, not something to collapse.
+      if (seen.has(key)) throw new BrowserRuntimeError('INVALID_INPUT');
+      seen.add(key);
+      sessionIds.push(session);
+    }
+    if (attachmentRevision === 0 && sessionIds.length > 0) {
       throw new BrowserRuntimeError('INVALID_INPUT');
     }
     return {
@@ -4161,17 +4216,32 @@ export class BrowserRuntime {
         'attachmentAuthorityId',
       ),
       attachmentRevision,
-      sessionId,
+      sessionIds,
     };
   }
 
+  private sessionKey(session: TQualifiedBrowserSessionId): string {
+    return `${session.harnessId}:${session.nativeId}`;
+  }
+
+  private leaseSessionKey(lease: ILeaseRecord): string | undefined {
+    const session = lease.capability.sessionId;
+    return session ? this.sessionKey(session) : undefined;
+  }
+
+  /** Order-insensitive: the same members in any order are the same binding. */
+  private sessionSetKey(sessionIdsArg: readonly TQualifiedBrowserSessionId[]): string {
+    if (sessionIdsArg.length === 0) return 'detached';
+    return sessionIdsArg.map((session) => this.sessionKey(session)).sort().join(',');
+  }
+
   private bindingsEqual(
     left: IBrowserAttachmentBinding,
     right: IBrowserAttachmentBinding,
   ): boolean {
     return left.attachmentAuthorityId === right.attachmentAuthorityId
       && left.attachmentRevision === right.attachmentRevision
-      && this.sessionsEqual(left.sessionId, right.sessionId);
+      && this.sessionSetKey(left.sessionIds) === this.sessionSetKey(right.sessionIds);
   }
 
   private sessionsEqual(
@@ -4211,9 +4281,7 @@ export class BrowserRuntime {
       registeredAt: slot.registeredAt,
       attachmentBinding: {
         ...slot.attachmentBinding,
-        sessionId: slot.attachmentBinding.sessionId
-          ? { ...slot.attachmentBinding.sessionId }
-          : null,
+        sessionIds: slot.attachmentBinding.sessionIds.map((session) => ({ ...session })),
       },
       incarnationStatus: slot.permanentlyFenced || slot.attachmentRetryBinding
         ? 'fenced'
@@ -4233,19 +4301,33 @@ export class BrowserRuntime {
     >,
   ): void {
     const binding = slot.attachmentBinding;
-    if (
-      binding.attachmentAuthorityId !== expected.attachmentAuthorityId
-      || binding.attachmentRevision !== expected.attachmentRevision
-    ) throw new BrowserRuntimeError('ATTACHMENT_CONFLICT');
+    if (binding.attachmentAuthorityId !== expected.attachmentAuthorityId) {
+      throw new BrowserRuntimeError('ATTACHMENT_CONFLICT');
+    }
+    // A capability may never claim a revision the authority has not published yet, whatever its
+    // role. For an agent the lower bound is its own join revision, not the current one.
+    if (expected.attachmentRevision > binding.attachmentRevision) {
+      throw new BrowserRuntimeError('ATTACHMENT_CONFLICT');
+    }
     if (expected.role === 'agent') {
+      if (!expected.sessionId) throw new BrowserRuntimeError('ATTACHMENT_CONFLICT');
+      // A capability survives exactly as long as its session stays continuously attached:
+      // membership is the presence of a join revision, and continuity is the capability having
+      // been minted at or after it. Leaving the set drops the entry; rejoining raises it.
+      // This is decided before the in-progress check, so a session the rebind already removed is
+      // told it is gone rather than told to retry.
+      const joinedAtRevision = slot.sessionJoinRevisions.get(this.sessionKey(expected.sessionId));
+      if (joinedAtRevision === undefined || expected.attachmentRevision < joinedAtRevision) {
+        throw new BrowserRuntimeError('ATTACHMENT_CONFLICT');
+      }
       if (slot.attachmentFenceCount > 0 || slot.attachmentRetryBinding) {
         throw new BrowserRuntimeError('BUSY');
       }
-      if (!binding.sessionId || !this.sessionsEqual(binding.sessionId, expected.sessionId)) {
-        throw new BrowserRuntimeError('ATTACHMENT_CONFLICT');
-      }
     } else if (expected.sessionId !== undefined) {
       throw new BrowserRuntimeError('ATTACHMENT_CONFLICT');
+    } else if (binding.attachmentRevision !== expected.attachmentRevision) {
+      // Human capabilities keep the exact-revision fence; they carry no session to be continuous.
+      throw new BrowserRuntimeError('ATTACHMENT_CONFLICT');
     }
   }
 
@@ -4260,7 +4342,10 @@ export class BrowserRuntime {
     if (capability.role === 'human') return;
     try {
       this.assertCapabilityBinding(slot, capability);
-    } catch {
+    } catch (error) {
+      // An in-progress rebind is transient and says nothing about this capability's authority. A
+      // session that is still in the set must be told to retry, not that it has been revoked.
+      if (error instanceof BrowserRuntimeError && error.code === 'BUSY') throw error;
       throw new BrowserRuntimeError('CAPABILITY_REVOKED');
     }
   }

package/ts/interfaces.ts

@@ -31,7 +31,11 @@ export interface IBrowserResourceKey {
 export interface IBrowserAttachmentBinding {
   attachmentAuthorityId: string;
   attachmentRevision: number;
-  sessionId: TQualifiedBrowserSessionId | null;
+  /**
+   * The set of sessions attached to the resource. Order is not significant and duplicates are
+   * rejected. An empty set is detached, and revision `0` requires an empty set.
+   */
+  sessionIds: TQualifiedBrowserSessionId[];
 }
 
 export interface ICreateBrowserResourceRequest {