Provider-neutral harness DTOs, adapter contracts, and boundary validation for HCon integrations. The package separates provider semantics from HCon's controller RPC, browser, persistence, and product policy.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Draft Status

This package is an unpublished draft. Its initial contract remains subject to validation against the finalized HCon v19.0.1 archive behavior and concrete FlexHarness and OpenCode adapters. Do not depend on version 0.1.0 as a stable public contract.

The draft intentionally excludes archive mutations, projects, workspaces, provider authentication, persistence stores, browser resources, and background execution. Those concepts either remain HCon product policy or require additional cross-provider evidence.

Install

After the first stable release:

pnpm add @modelprofile.com/hcon-harness-contracts

The package requires Node.js 24 or newer and has no runtime dependencies.

Contract Layers

The package exposes four entry points:

@modelprofile.com/hcon-harness-contracts exports the complete public surface.
@modelprofile.com/hcon-harness-contracts/dto exports JSON-safe transfer values.
@modelprofile.com/hcon-harness-contracts/spi exports process-local asynchronous adapter contracts.
@modelprofile.com/hcon-harness-contracts/validation exports boundary validators and stream sequencing checks.

DTOs use open source and capability identifiers, opaque scope and native identifiers, canonical UTC timestamps, ordered message parts, opaque paging cursors, and explicit unknown/native states. Adapter methods may return promises, but every value crossing the semantic boundary remains bounded and JSON-safe.

Adapter Example

import type {
  IHconHarnessAdapter,
  IHconRunHandle,
} from '@modelprofile.com/hcon-harness-contracts/spi';
import {
  type IHconRunInput,
} from '@modelprofile.com/hcon-harness-contracts/dto';
import {
  HconEventSequenceTracker,
} from '@modelprofile.com/hcon-harness-contracts/validation';

const runPrompt = async (
  adapter: IHconHarnessAdapter,
  input: IHconRunInput,
): Promise<IHconRunHandle> => {
  const handle = await adapter.startRun(input);

  // Acceptance and completion are separate. Aborting an admission signal after
  // this point must not silently abort the accepted run.
  void handle.completion.then((completion) => {
    console.log(completion.outcome);
  });

  return handle;
};

const sequenceTracker = new HconEventSequenceTracker();

const subscribe = async (adapter: IHconHarnessAdapter, scopeId: string) =>
  adapter.subscribe({ scopeId }, (event) => {
    // accept() validates the envelope before checking stream order.
    sequenceTracker.accept(event);
  });

Event Recovery

Event sequence values describe adapter delivery order within one streamId; they do not claim a provider-wide source order. Any reconnect, overflow, invalid provider delta, or possible event loss must emit stream.gap. The next event starts a new stream at sequence 1, and consumers recover through authoritative session, message, and permission reads.

Message and part events carry cumulative replacement snapshots. Provider-specific deltas are accumulated inside the adapter and never leak into the shared contract.

Validation

Boundary validators reject class instances, cycles, undefined, non-finite numbers, functions, symbols, bigint, malformed timestamps, invalid discriminants, and oversized values. Validation errors include a bounded field path and stable code without retaining or printing the rejected value.

Unknown object properties remain allowed when they are JSON-safe. Unknown provider part kinds must use the explicit extension representation instead of being silently discarded or interpreted as a known kind.

Verification

pnpm install
pnpm dedupe
pnpm run build
pnpm run check:test
pnpm test

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.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@modelprofile.com/hcon-harness-contracts