@modelprofile.com/browser-runtime 1.0.1 → 2.1.0

package/readme.md

@@ -1,6 +1,6 @@
 # @modelprofile.com/browser-runtime
 
-Parent-owned, project-scoped Chromium runtime with authenticated human and agent control, fail-closed egress, bounded artifacts, and Flex/MCP adapters.
+Parent-owned, resource-centric Chromium runtime with revisioned attachment fencing, authenticated human and agent control, fail-closed egress, bounded artifacts, and Flex/MCP adapters.
 
 ## Issue Reporting and Security
 
@@ -14,156 +14,127 @@ pnpm add @modelprofile.com/browser-runtime
 
 The runtime requires Node.js 24 or newer and a non-root Linux host. Production browser sessions require a sandbox-capable Chromium installation.
 
-## Runtime
+## Resource Model
 
-`BrowserRuntime` owns its lock, profile root, artifact root, project slots, Chromium sessions, egress proxies, capabilities, leases, and cleanup work. The host must make the authorization decision; there is no permissive default.
+The Controller owns durable resource and attachment truth. `BrowserRuntime` owns process-local registrations, fences, capabilities, leases, browser incarnations, artifacts, and its runtime lock. Registration never launches Chromium.
 
 ```typescript
-import { BrowserRuntime } from '@modelprofile.com/browser-runtime';
+import {
+  BrowserRuntime,
+  type TBrowserCapabilityAuthorizationRequest,
+} from '@modelprofile.com/browser-runtime';
 
 const runtime = new BrowserRuntime({
   runtimeDirectory: '/var/lib/example/browser-runtime',
-  authorizeCapability: async ({ projectId, actorId, role, peerId, source }) => {
-    return hostPolicy.authorizeBrowser({ projectId, actorId, role, peerId, source });
-  },
-});
-
-await runtime.start();
-
-const issued = await runtime.issueCapability({
-  projectId: 'project-123',
-  actorId: 'agent-456',
-  role: 'agent',
-  peerId: 'worker-789',
-  source: 'mcp',
-});
-
-// Deliver capabilityToken once to the exact authenticated peer.
-const lease = await runtime.acquireLease({
-  capabilityToken: issued.capabilityToken,
-  peerId: 'worker-789',
-  expectedRole: 'agent',
-  expectedSource: 'mcp',
+  authorizeCapability: async (binding) => hostPolicy.authorizeBrowser(binding),
+  beforeOperation: async (operation) => hostAudit.recordAttempt(operation),
 });
 
 try {
-  const observation = await lease.executeAgentAction({ action: 'snapshot' });
-  const screenshot = await lease.executeAgentAction({ action: 'screenshot' });
-  console.log(observation, screenshot);
+  await runtime.start();
+
+  const resource = runtime.createResource({
+    projectId: 'project-123',
+    attachmentBinding: {
+      attachmentAuthorityId: 'controller-attachment-1',
+      attachmentRevision: 1,
+      sessionId: { harnessId: 'opencode', nativeId: 'session-456' },
+    },
+  });
+
+  const binding = {
+    projectId: resource.projectId,
+    browserResourceId: resource.browserResourceId,
+    attachmentAuthorityId: resource.attachmentBinding.attachmentAuthorityId,
+    attachmentRevision: resource.attachmentBinding.attachmentRevision,
+    sessionId: { harnessId: 'opencode', nativeId: 'session-456' },
+    actorId: 'agent-456',
+    role: 'agent',
+    peerId: 'worker-789',
+    source: 'mcp',
+  } satisfies TBrowserCapabilityAuthorizationRequest;
+
+  const issued = await runtime.issueCapability(binding);
+
+  const lease = await runtime.acquireLease({
+    ...binding,
+    capabilityToken: issued.capabilityToken,
+  });
+
+  try {
+    console.log(await lease.executeAgentAction({ action: 'snapshot' }));
+  } finally {
+    await lease.release();
+  }
 } finally {
-  await lease.release();
   await runtime.stop();
 }
 ```
 
-Agent actions are limited to `navigate`, `snapshot`, `screenshot`, `click`, `fill`, and `press`. Screenshot results contain artifact metadata, never image bytes. Human leases additionally expose viewport, raw input, direct event/frame subscription, frame acknowledgement, and artifact read/delete methods. JavaScript evaluation is not part of either lease surface.
+Projects and qualified sessions may each own many resources. Human/agent arbitration, mutexes, leases, operations, profiles, proxies, frame subscriptions, and idle timers are per resource.
 
-The first session for a project starts a private authenticated loopback proxy and runs the mandatory confinement probe before the session becomes available. The production probe verifies loopback denial, synthetic DNS traversal, and WebRTC candidate suppression. Browser/session and host-fact injection are not part of the published API.
+`registerResource()` is idempotent only for the same project/resource key and identical attachment. `listResources()` reports process-local registration and incarnation metadata. `terminateResource()` terminates only the current incarnation and preserves registration, attachment, and artifacts. `retireResource()` permanently fences the process-local registration, revokes and quiesces authority, terminates its incarnation, purges exact-resource artifacts, and unregisters only after cleanup succeeds. The Controller separately owns durable retirement truth and must not rehydrate retired resources. Runtime tombstones and registrations are ephemeral, bounded process state. `stop()` revokes all process-local capabilities, terminates every incarnation, removes the Runtime-owned artifact root and registrations, and releases the lock without deleting Controller durable truth.
 
-## Trusted Pipe
+## Attachment Fencing
 
-The parent attaches a trusted inherited pipe and supplies the peer, Flex scope, and Flex session identities out of band. Incoming frames cannot select a project, actor, role, source, scope, session, or peer. The capability used by the pipe must have been issued with the same immutable bindings.
+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.
 
 ```typescript
-import {
-  BrowserRuntimeFramedClient,
-  type BrowserRuntime,
-} from '@modelprofile.com/browser-runtime';
-import type { Readable, Writable } from 'node:stream';
-
-declare const runtime: BrowserRuntime;
-declare const childReadable: Readable;
-declare const childWritable: Writable;
-
-const flexCapability = await runtime.issueCapability({
-  projectId: 'project-123',
-  actorId: 'agent-456',
-  role: 'agent',
-  peerId: 'worker-789',
-  source: 'flex',
-  scopeId: 'project-123',
-  sessionId: 'flex-session-1',
-});
-
-runtime.attachTrustedFramedPeer({
-  peerId: 'worker-789',
-  scopeId: 'project-123',
-  sessionId: 'flex-session-1',
-  readable: childReadable,
-  writable: childWritable,
-});
-
-const childClient = new BrowserRuntimeFramedClient({
-  scopeId: 'project-123',
-  sessionId: 'flex-session-1',
-  readable: process.stdin,
-  writable: process.stdout,
-});
-
-await childClient.acquire(flexCapability.capabilityToken);
-const result = await childClient.executeAgentAction({
-  action: 'navigate',
-  url: 'https://example.com/',
+await runtime.applyAttachmentBinding({
+  projectId: resource.projectId,
+  browserResourceId: resource.browserResourceId,
+  attachmentBinding: {
+    attachmentAuthorityId: 'controller-attachment-1',
+    attachmentRevision: 2,
+    sessionId: null,
+  },
 });
-console.log(result);
-await childClient.close();
 ```
 
-The framing protocol is versioned length-prefixed JSON with a 256 KiB hard frame ceiling, at most 16 pending requests, and a maximum 60-second request timeout. It supports only acquire, execute, cancel, and release.
+A newer binding synchronously fences admission, revokes older capabilities, and quiesces active work. It normally preserves the incarnation; work that ignores cancellation causes termination of only that resource's incarnation.
 
-## Flex Provider
+Agent capabilities require the exact current non-detached qualified session. Human capabilities deliberately carry no session ID: they bind the exact project, resource, attachment authority, and revision and may be issued while detached. Any attachment revision advance invalidates both human and agent capabilities.
 
-`BrowserRuntimeFlexToolProvider<TScope>` implements `IFlexToolProvider<TScope>` for one supervised Flex child run. Its resolver returns only the capability token; the framed server validates that token against the parent-bound peer, source, scope, and session. The provider exposes SmartAgent browser tools with only the six allowed agent actions and maps side-effect permissions to `browser.<action>` Flex permissions. Closing or aborting the run releases the lease and closes the inherited-pipe client.
+Agent actions are exactly `navigate`, `snapshot`, `screenshot`, `click`, `fill`, and `press`. Human leases additionally expose tab lifecycle, viewport, raw input, frame subscription/acknowledgement, and exact-resource artifact reads/deletes. JavaScript evaluation is not public.
 
-## MCP Handler
+`beforeOperation` is an optional awaited fail-closed gate. It receives the complete immutable authority, operation/capability/lease IDs, action, start time, and an `AbortSignal` after resource admission but before the browser side effect starts. Hosts that require durable attempt-before-side-effect auditing should persist the attempt there. Rejection denies the operation. The default `beforeOperationTimeoutMs` is 10,000 milliseconds and accepts values from 100 through 120,000; timeout fails with `TIMEOUT`. The terminal `audit` callback remains a best-effort `completed`/`failed` notification correlated by the same operation ID and runs after bounded operation cleanup releases or fences the exact reservation.
 
-`createBrowserRuntimeMcpHttpHandler()` creates a stateless SmartMCP POST handler. Independent client proof is mandatory and the bearer capability must match the authenticated peer with role `agent` and source `mcp`.
+## Trusted Pipe And Flex
 
-```typescript
-import { createBrowserRuntimeMcpHttpHandler } from '@modelprofile.com/browser-runtime';
+Trusted framed peers and clients receive the complete authority out of band: project, resource, attachment authority/revision, actor, peer, role, source, qualified session, Flex scope, and resource-specific channel. Incoming frames cannot select identity. One session may use multiple resource-specific channels concurrently.
 
-const mcp = createBrowserRuntimeMcpHttpHandler(runtime, {
-  authenticateMcpRequest: async (request) => {
-    const peerId = await verifyClientCertificateOrSignedRequest(request);
-    return { peerId };
-  },
-  allowedHosts: ['browser.example.com'],
-  trustedOrigins: ['https://browser.example.com'],
-});
+`BrowserRuntimeFlexToolProvider<TScope>` resolves only a capability token and exposes the six approved SmartAgent actions. The framed server validates the token against its complete trusted binding.
 
-export const fetch = (request: Request): Promise<Response> => mcp.handleRequest(request);
-```
+## MCP Handler
 
-The MCP tool list is exactly `browser_navigate`, `browser_snapshot`, `browser_screenshot`, `browser_click`, `browser_fill`, and `browser_press`. It does not expose state-only helpers, tab lifecycle, history, evaluation, frame streaming, artifact reads, raw input, or image bytes.
+`createBrowserRuntimeMcpHttpHandler()` requires independent request authentication to return the complete expected MCP binding. The bearer capability must match it exactly. Identity remains server-owned and no tool input contains a project, resource, authority, revision, session, actor, or peer selector.
+
+The MCP tool list is exactly `browser_navigate`, `browser_snapshot`, `browser_screenshot`, `browser_click`, `browser_fill`, and `browser_press`.
 
 ## Egress And Artifacts
 
-`BrowserEgressProxy` is exported for testing and advanced composition. It uses Basic proxy authentication, one strict DNS/IP validation path for HTTP, WebSocket Upgrade, and CONNECT, public-global-only targets, numeric selected-IP dialing, default ports `80` and `443`, and bounded DNS, request, response, connection, and tunnel lifetimes. WebSocket tunneling starts only after a bounded valid `101` response.
+Each running resource owns one authenticated loopback `BrowserEgressProxy` carrying immutable `projectId` and `browserResourceId`. HTTP, WebSocket Upgrade, and CONNECT share strict public-unicast DNS/IP validation, numeric dialing, bounded lifetimes, and fail-closed policy.
 
-`BrowserArtifactStore` exclusively creates and owns its root, writes generated artifact IDs below keyed project-digest directories, and removes the root on `stop()`. Directories use mode `0700`; files use mode `0600`. Serialized admission enforces per-file, per-project, project-count, aggregate-count, aggregate-byte, and TTL limits before writes. Reads use no-follow file handles and verify size plus SHA-256 integrity before returning trusted-host bytes. Agent, Flex, and MCP surfaces receive metadata only.
+Artifact identity and APIs use `(projectId, browserResourceId, artifactId)`. Keyed project/resource directories prevent caller IDs from entering paths. Admission is serialized across per-resource, per-project, and global count/byte quotas. Reads use no-follow handles and verify size and SHA-256. Agent, Flex, and MCP surfaces receive metadata only.
 
 ## Verification
 
 ```sh
 pnpm install
+pnpm dedupe
 pnpm run build
 pnpm run check:test
 pnpm test
-```
-
-The real Chromium release check is intentionally separate:
-
-```sh
 pnpm run test:real-chrome
 ```
 
-That command sets `BROWSER_RUNTIME_REAL_CHROME=1` and runs the production `LiveBrowserSession`, sandbox requirement, mandatory confinement probe, screenshot artifact path, confirmed shutdown, and profile deletion check.
+The real Chromium check launches two resources in one project and qualified session, verifies distinct private profiles, sandboxed renderer process trees, mandatory confinement, screenshots, confirmed shutdown, and profile deletion.
 
 ## License and Legal Information
 
 This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
 
-**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the contents of the NOTICE file.
 
 ### Trademarks
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/browser-runtime',
-  version: '1.0.1',
-  description: 'Parent-owned, project-scoped Chromium runtime with authenticated human and agent control, fail-closed egress, bounded artifacts, and Flex/MCP adapters.'
+  version: '2.1.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/actions.ts

@@ -226,11 +226,20 @@ export const validateAgentActionResult = (value: unknown): TBrowserAgentActionRe
     validateExactKeys(value, ['action', 'artifact'], 'screenshot result');
     const artifact = validateExactKeys(
       result.artifact,
-      ['artifactId', 'projectId', 'mimeType', 'size', 'createdAt', 'expiresAt'],
+      [
+        'artifactId',
+        'projectId',
+        'browserResourceId',
+        'mimeType',
+        'size',
+        'createdAt',
+        'expiresAt',
+      ],
       'artifact metadata',
     );
     validateBoundedString(artifact.artifactId, 'artifactId', 1, 128);
-    validateBoundedString(artifact.projectId, 'projectId', 1, 128);
+    validateBoundedString(artifact.projectId, 'projectId', 1, 256);
+    validateBoundedString(artifact.browserResourceId, 'browserResourceId', 16, 256);
     validateBoundedString(artifact.mimeType, 'mimeType', 1, 128);
     validateInteger(artifact.size, 'artifact.size', 0, 64 * 1024 * 1024);
     validateInteger(artifact.createdAt, 'artifact.createdAt', 0, Number.MAX_SAFE_INTEGER);