integration.harness-runtime

@lssm-tech/integration.harness-runtime

Website: https://contractspec.io

Runtime adapters that bridge the ContractSpec harness core into browser, sandbox, artifact, and MCP-backed execution targets.

What It Provides

• Provides concrete adapters for deterministic Playwright browser automation, optional agent-browser visual computer-use runs, sandboxed execution, and artifact storage.
• Exposes MCP helpers and default target resolution on top of the mode-agnostic harness core.
• Keeps higher-cost runtime integrations optional so consumers can opt into heavier execution targets deliberately.
• Enforces browser navigation and request-domain allowlists at runtime, emits sanitized network/trace and accessibility evidence, and keeps visual baseline updates manual and permit-bound.
• Requires an injected container, process, or remote IsolatedCodeSandboxPort for code execution. Node vm is not represented as a security boundary; missing isolation fails closed.
• src/adapters/ contains runtime, provider, or environment-specific adapters.
• src/mcp/ contains MCP handlers, tools, prompts, and resources.

Playwright keyed reads

PlaywrightBrowserHarnessAdapter implements structured output for browser get actions that declare a non-empty key. It validates the complete keyed read set before creating a run session or navigating, then evaluates valid reads in authored order after the other actions complete.

Unkeyed reads remain legacy no-ops. Duplicate/empty keys, invalid selectors, and unavailable page methods fail the step without returning partial output; existing screenshot, DOM, and console capture remains unchanged.

Deterministic browser admission

The Playwright adapter checks all requested interactions and keyed-read methods before navigation. Missing methods fail instead of silently skipping a step; double-click and typing keep their exact semantics. Text waits require visible matching text. A requested viewport also requires runtime support.

Restricted targets require a fresh context with HTTP and WebSocket routing and service workers blocked. Page-only custom browser factories cannot claim this coverage. Setup failures close partially created pages and contexts. Host-level egress restrictions are still required: browser routing alone does not isolate DNS, redirect destinations or other network protocols.

Run bun run test:browser with the pinned Playwright peer and its Chromium binary installed. This opt-in real-browser suite exercises actual local HTTP, popup, WebSocket and service-worker behavior. Missing browser support fails the suite; skipped live tests in ordinary unit runs are not qualification evidence.

Low-level factory types are exported from ./adapters/playwright-types; ./adapters/playwright-actions exports exact action validation/execution helpers. Use the full adapter for session lifecycle, network guards and evidence capture. The helpers do not authorize actions or establish an isolated browser context.

Installation

npm install @lssm-tech/integration.harness-runtime

or

bun add @lssm-tech/integration.harness-runtime

Usage

Import the root entrypoint from @lssm-tech/integration.harness-runtime, or choose a documented subpath when you only need one part of the package surface.

Architecture

• src/adapters/ contains Playwright, agent-browser, sandbox, and visual harness adapters.
• src/artifacts/ contains filesystem and in-memory artifact-store implementations.
• src/mcp/ exposes harness execution surfaces to MCP-aware runtimes.
• src/targets/ contains target resolution helpers and target-selection logic.
• src/types.ts exposes shared runtime-facing harness types.
• src/index.ts is the root public barrel and package entrypoint.

Public Entry Points

• Exports runtime adapters, artifact stores, MCP exposure helpers, target resolution, and shared types.
• Export . resolves through ./src/index.ts.
• Export ./adapters/agentBrowserHarnessAdapter resolves through ./src/adapters/agentBrowserHarnessAdapter.ts.
• Export ./adapters/playwrightBrowserHarnessAdapter resolves through ./src/adapters/playwrightBrowserHarnessAdapter.ts.
• Export ./adapters/sandboxedCodeExecutionAdapter resolves through ./src/adapters/sandboxedCodeExecutionAdapter.ts.
• Export ./adapters/visualHarnessAdapter resolves through ./src/adapters/visualHarnessAdapter.ts.
• Export ./artifacts/filesystemArtifactStore resolves through ./src/artifacts/filesystemArtifactStore.ts.
• Export ./artifacts/inMemoryArtifactStore resolves through ./src/artifacts/inMemoryArtifactStore.ts.
• Export ./mcp/exposure resolves through ./src/mcp/exposure.ts.
• Export ./targets/defaultTargetResolver resolves through ./src/targets/defaultTargetResolver.ts.
• Export ./types resolves through ./src/types.ts.

Local Commands

• bun run dev — contractspec-bun-build dev
• bun run build — contractspec-bun-build build
• bun run test — bun test --pass-with-no-tests
• bun run lint — bun run lint:fix
• bun run lint:check — biome check .
• bun run lint:fix — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
• bun run typecheck — tsgo --noEmit
• bun run publish:pkg — bun publish --tolerate-republish --ignore-scripts --verbose
• bun run publish:pkg:canary — bun publish:pkg --tag canary
• bun run clean — rimraf dist .turbo
• bun run build:bundle — contractspec-bun-build transpile
• bun run build:types — contractspec-bun-build types
• bun run prebuild — contractspec-bun-build prebuild

Recent Updates

• Replace eslint+prettier by biomejs to optimize speed.
• Add a first-class harness system for controlled inspection, testing, evaluation, and proof generation.
• Add OSS full-app verification adapters for Playwright and agent-browser, including auth profile refs, visual diff evidence, and replay-friendly browser artifacts.

Notes

• Works alongside @lssm-tech/lib.contracts-spec, @lssm-tech/lib.harness, @lssm-tech/tool.bun, @lssm-tech/tool.typescript.
• Authenticated browser runs should use named storage-state, browser-profile, session-name, or headers-env refs. Do not embed raw credentials, cookies, or bearer tokens in scenario specs or replay bundles.