> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Export portable manifests

> Serialize harness configuration and resolve its versioned capabilities against host-approved factories.

A manifest is JSON configuration with `contractVersion: 1`. It contains stable IDs, ability selections, defaults, limits, and optional versioned runtime references. It does not contain executable callbacks or credentials.

## Export and load a definition

```typescript theme={null}
import {
  defineHarness,
  describeHarness,
  exportManifest,
  hashManifest,
  loadManifest,
  textContext,
} from "@agentium/harness";

const definition = defineHarness({
  id: "portable-notes",
  abilities: [textContext(
    { id: "notes", entries: [{ id: "scope", text: "Study shipping delays." }] },
    { instanceId: "notes-source" },
  )],
});

const manifest = exportManifest(definition);
const encoded = JSON.stringify(manifest);
const factory = textContext.factory;
if (!factory) throw new Error("textContext must provide a portable factory");

// The host chooses the approved factories; JSON does not load code.
const restored = loadManifest(JSON.parse(encoded), [factory]);
console.log(hashManifest(manifest));
console.log(describeHarness(restored).id); // portable-notes
```

`exportManifest()` requires an explicit stable definition ID and a portable selection plus factory mapping for every ability. `textContext` supports this with an explicit `instanceId`. Local callbacks, client instances, filesystem abilities, and supplied tools cannot be serialized by implication.

`loadManifest(input, factories, runtimeRegistry?)` validates unknown input and resolves each ability by its exact `type` and `version`. Unknown fields, duplicate IDs, unsupported contract versions, missing factories, or conflicting factories fail. Loading and describing are pure; binding and I/O happen when a runtime runs.

`hashManifest()` computes a stable manifest hash for comparison and identification. A hash is not a signature, authorization decision, or proof that an implementation is safe.

## Make a custom ability portable

Add `portable` to `defineAbility()` only when you have an explicit JSON representation:

| Callback | Responsibility |
| - | - |
| `validateOptions(json)` | Validate and normalize JSON input. |
| `toOptions(json)` | Convert approved JSON to typed local options. |
| `toJSON(options)` | Produce the portable JSON representation. |

Use stable type/version semantics and explicit instance IDs. Plain JSON must not smuggle in host service references. The approved `AbilityFactory` supplies executable binding behavior on the receiving host.

## Reference runtime implementations

`HarnessRuntimeReferences` supports `driver`, `controller`, `contextPolicy`, and `completionPolicy`, each as `{ id, version }`. `modelRoles` maps public role names to host model-binding names.

This complete helper accepts a trusted driver and returns an exportable definition:

```typescript theme={null}
import { defineHarness, exportManifest, type ExecutionDriver } from "@agentium/harness";

export function driverManifest(driver: ExecutionDriver) {
  return exportManifest(defineHarness({
    id: "registered-runtime",
    runtimeReferences: { driver: { id: "approved-driver", version: 1 } },
    runtimeRegistry: {
      driver: [{ id: "approved-driver", version: 1, implementation: driver }],
    },
  }));
}
```

On load, provide the registry again. Registry collections are `driver`, `controller`, `contextPolicy`, and `completionPolicy`. Each entry has `id`, `version`, and `implementation`. Exactly one entry must match each requested reference. A direct runtime binding paired with a reference must be the same approved implementation object.

`resolveHarnessRuntime(definition)` performs this lookup and returns runtime bindings without executing them. When constructing a runtime, direct `driver`, `controller`, `contextPolicy`, and `completionPolicy` options take precedence over resolved definition bindings. Referenced model-role aliases must resolve to entries in the runtime's `models` registry.

Export fails when a direct executable binding lacks an approved registry reference. A receiving host may use a different approved implementation registry, but it must explicitly satisfy every requested reference.

See [definition and manifest types](/harness/api/definitions) and [runtime registry signatures](/harness/api/manifests).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.