Skip to content
ContractSpec
Start here

Package manual · integrations

·Agents, execution and context

integration.harness-runtime

Runtime adapters for the ContractSpec harness system.

integrationsintegrationv2.0.5experimentalservernode
@lssm-tech/integration.harness-runtime
bun add @lssm-tech/integration.harness-runtime
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

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.

TargetSelectorResult
textrequiredstring | null from textContent
htmlrequiredstring from innerHTML
valuerequiredstring from inputValue
titleforbiddenstring from title()
urlforbiddenstring from url()

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.

Relationships

THIS PACKAGEintegration.harness-runtime13 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

5 declarations

Declared capabilities

Integration Harness Runtime

Runtime adapters for the ContractSpec harness system.

Scripts

  • publish:pkgbun publish --tolerate-republish --ignore-scripts --verbose
  • publish:pkg:canarybun publish:pkg --tag canary
  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • devcontractspec-bun-build dev
  • cleanrimraf dist .turbo
  • lintbun run lint:fix
  • lint:fixnode ../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../scripts/biome.cjs check --write .
  • lint:checknode ../../../scripts/biome.cjs check .
  • testbun test --pass-with-no-tests
  • test:browserHARNESS_BROWSER_LIVE_TESTS=1 bun test src/adapters/playwright-browser.live.test.ts
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit