integration.harness-runtime
Runtime adapters for the ContractSpec harness system.
@lssm-tech/integration.harness-runtimebun add @lssm-tech/integration.harness-runtimeManifest 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-browservisual 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
IsolatedCodeSandboxPortfor code execution. Nodevmis 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.
| Target | Selector | Result |
|---|---|---|
text | required | string | null from textContent |
html | required | string from innerHTML |
value | required | string from inputValue |
title | forbidden | string from title() |
url | forbidden | string 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.tsexposes shared runtime-facing harness types.src/index.tsis 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/agentBrowserHarnessAdapterresolves through./src/adapters/agentBrowserHarnessAdapter.ts. - Export
./adapters/playwrightBrowserHarnessAdapterresolves through./src/adapters/playwrightBrowserHarnessAdapter.ts. - Export
./adapters/sandboxedCodeExecutionAdapterresolves through./src/adapters/sandboxedCodeExecutionAdapter.ts. - Export
./adapters/visualHarnessAdapterresolves through./src/adapters/visualHarnessAdapter.ts. - Export
./artifacts/filesystemArtifactStoreresolves through./src/artifacts/filesystemArtifactStore.ts. - Export
./artifacts/inMemoryArtifactStoreresolves through./src/artifacts/inMemoryArtifactStore.ts. - Export
./mcp/exposureresolves through./src/mcp/exposure.ts. - Export
./targets/defaultTargetResolverresolves through./src/targets/defaultTargetResolver.ts. - Export
./typesresolves through./src/types.ts.
Local Commands
bun run dev— contractspec-bun-build devbun run build— contractspec-bun-build buildbun run test— bun test --pass-with-no-testsbun run lint— bun run lint:fixbun run lint:check— biome check .bun run lint:fix— biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .bun run typecheck— tsgo --noEmitbun run publish:pkg— bun publish --tolerate-republish --ignore-scripts --verbosebun run publish:pkg:canary— bun publish:pkg --tag canarybun run clean— rimraf dist .turbobun run build:bundle— contractspec-bun-build transpilebun run build:types— contractspec-bun-build typesbun 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
Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.
5 declarations
@lssm-tech/lib.assurance-specworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-integrationsworkspace:^
Read the package manual ↗@lssm-tech/lib.crypto-utilsworkspace:^
Read the package manual ↗@lssm-tech/lib.harnessworkspace:^
Read the package manual ↗@lssm-tech/lib.schemaworkspace:^
Read the package manual ↗
Declared capabilities
Runtime adapters for the ContractSpec harness system.
Scripts
publish:pkgbun publish --tolerate-republish --ignore-scripts --verbosepublish:pkg:canarybun publish:pkg --tag canarybuildcontractspec-bun-build buildbuild:bundlecontractspec-bun-build transpilebuild:typescontractspec-bun-build typesdevcontractspec-bun-build devcleanrimraf dist .turbolintbun run lint:fixlint: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-teststest:browserHARNESS_BROWSER_LIVE_TESTS=1 bun test src/adapters/playwright-browser.live.test.tsprebuildcontractspec-bun-build prebuildtypechecktsgo --noEmit