# Getting started — hosting the agent harness

This guide takes a host application from `npm install` to a working harness:
natural-language intent (plus an optional on-screen selection) goes in, a
**verified, fingerprinted changeset — or nothing** — comes out. The harness
never applies anything and never owns credentials; you inject the model.

Every `ts` code block below is extracted, type-checked, and **executed**
against the published package shape by `tools/verify-docs-examples.ts`
(wired into CI). The examples throw on failure, so they cannot silently
drift from the API or stop demonstrating what they claim.

## Install

```sh
npm install @vivariumjs/agent
```

The package is a plain TypeScript library for Node (or any bundled host).
Its only dependency is [`@vivariumjs/changeset`](https://github.com/iyulab/vivarium-changeset)
— the contract every proposal is validated against.

## 1. Inject a provider, create the harness

The harness is model-agnostic: a **`ModelProvider`** is the only place a
model lives, and the harness cannot tell a real LLM from a script — every
guarantee (validation gate, retry loop, lineage) is enforced by the
harness, not by model behavior.

For this guide we script the provider. The default strategy
(`plan-then-generate`) makes two kinds of calls: a *planner* call that
expects a short numbered plan, and a *generator* call that expects one JSON
object of patches.

```ts
import { createAgentHarness } from "@vivariumjs/agent";
import type { ModelProvider } from "@vivariumjs/agent";

const scripted: ModelProvider = {
  name: "scripted-example", // recorded in provenance
  async complete(request) {
    if (request.system.includes("planner")) {
      return "1. Apply the requested edit to the heading.";
    }
    // Generator calls carry the user INTENT (inside an untrusted fence) on
    // every attempt — key the canned output off it, as a real model would.
    // A generation that changes nothing relative to the live base is a
    // no-op: the strategy retries it and, if persistent, exhausts — a
    // changeset that changes nothing never ships as validated.
    const content = request.user.includes("total row")
      ? "export default function mount(root) { root.innerHTML = '<strong>Orders</strong> <em>Total: 42</em>'; }"
      : request.user.includes("bolder")
        ? "export default function mount(root) { root.innerHTML = '<strong>Orders</strong>'; }"
        : "export default function mount(root) { root.textContent = 'Orders'; }";
    return JSON.stringify({
      uiPatches: [
        {
          artifactId: "screen-main",
          newContent: content,
          explanation: "Apply the requested edit to the heading.",
        },
      ],
    });
  },
};

const harness = createAgentHarness({ provider: scripted });
```

Swapping in a real model is the same port — forward the harness-authored
prompts to whatever client your host already has. The harness only sees
text in, text out:

```ts
declare function callYourModel(system: string, user: string): Promise<string>;

function createRealProvider(): ModelProvider {
  return {
    name: "anthropic:claude-sonnet-5", // provider:model, for provenance
    async complete(request) {
      return callYourModel(request.system, request.user);
    },
  };
}
```

A real model does **not** need to know the JSON shape above a priori — the
strategy's prompts instruct it. The scripted provider mirrors the shape
only because it answers without reading instructions.

## 2. Propose: a changeset or nothing

`propose` takes the user's intent, the current artifacts (base state for
UI patches), and optionally the [edit
context](https://github.com/iyulab/vivarium/blob/main/docs/edit-context.md)
of what the user selected on screen:

```ts
import type { EditContextInput } from "@vivariumjs/agent";

const editContext: EditContextInput = {
  editContextVersion: "0.1",
  profile: null,
  selection: [{ id: "title", tag: "h1" }],
  screen: { elementIds: ["title"] },
  source: {
    language: "js",
    code: "export default function mount(root) { root.textContent = 'Home'; }",
  },
  untrusted: { title: { text: "Home", attributes: {} } },
};

const result = await harness.propose({
  intent: "Change the heading to Orders",
  editContext,
  artifacts: {
    "screen-main":
      "export default function mount(root) { root.textContent = 'Home'; }",
  },
});

if (!result.proposal) {
  throw new Error(`exhausted: ${JSON.stringify(result.outcome)}`);
}
if (!result.proposal.fingerprint.startsWith("sha256:")) {
  throw new Error("proposals are fingerprinted");
}
if (result.proposal.provenance.provider !== "scripted-example") {
  throw new Error("provenance records the provider");
}
```

The result is one of exactly two things:

- **`result.proposal`** — a changeset that already passed the spec
  validator, fingerprinted (JCS + SHA-256), with provenance recording the
  strategy, provider, knowledge sources, and attempt count.
- **`null`** — the strategy exhausted its retry budget (`maxAttempts`,
  default 3). A model that keeps emitting spec-violating output cannot push
  anything past the harness; the caller sees `result.outcome` explaining
  the exhaustion instead.

There is no third shape: no unvalidated draft, no partial output. What the
harness hands you is safe to forward to a reviewer and an applier (e.g.
`vivarium-stage`) — the harness itself has no apply authority by design.

## 3. Sessions: refinement with lineage

Multi-turn editing ("now make it bold") is a **proposal session**. Each
`refine` builds on the projection of the previous validated proposal, and
the lineage is machine-readable in provenance:

```ts
import { createProposalSession } from "@vivariumjs/agent";

const session = createProposalSession({
  provider: scripted,
  sessionId: "getting-started",
});

const first = await session.propose({
  intent: "Change the heading to Orders",
  artifacts: {
    "screen-main":
      "export default function mount(root) { root.textContent = 'Home'; }",
  },
});
const refined = await session.refine("Make the heading bolder");

if (!first.proposal || !refined.proposal) throw new Error("turns must validate");
if (refined.proposal.provenance.refinedFrom !== first.proposal.fingerprint) {
  throw new Error("a refinement records the fingerprint it refines");
}

const turns = session.history();
if (turns.length !== 2 || turns[1].status !== "validated") {
  throw new Error("the session keeps an auditable turn record");
}
```

An exhausted turn does **not** advance the shared state — the next `refine`
still builds on the last *validated* proposal. Re-selection mid-session is
supported: pass `{ editContext }` as the second argument to `refine`.

**Declared base vs refinement anchor.** The projection a `refine` builds on
is the *model's* anchor only. The emitted changeset's `kind:"ui-artifact"`
baseState entries (and each ui patch's `baseContent`) stay anchored to the
**live artifacts the session knows** — initially the ones passed to
`propose()` — so a draft chain whose intermediates were never applied still
emits changesets an applier (e.g. `vivarium-stage`'s drift gate) will
accept; the draft chain is carried by the `kind:"changeset"` lineage entry
instead. When the world *does* move — you applied one of the session's
proposals, or an external change landed — tell the session on the next
turn:

```ts
// After you APPLY a proposal, the live artifacts move to its projection —
// tell the session, so the next changeset declares that state as its base:
const liveArtifacts = session.artifacts(); // == what your applier returned
const rebased = await session.refine("Now bold the total row", {
  baseArtifacts: liveArtifacts,
});
if (!rebased.proposal) throw new Error("re-based turn must validate");
```

## 4. Knowledge sources

Knowledge (primitive catalogs, schema conventions, house rules) is data
plugged into the harness, not code baked in. Every source consulted is
recorded in provenance, and the wiring is enumerable:

```ts
import type { KnowledgeSource } from "@vivariumjs/agent";

const houseRules: KnowledgeSource = {
  name: "house-rules",
  retrieve: async () => [
    "Generated modules default-export mount(root, api).",
  ],
};

const informed = createAgentHarness({
  provider: scripted,
  knowledge: [houseRules],
});

const audit = informed.describe();
if (!audit.knowledgeSources.includes("house-rules")) {
  throw new Error("describe() enumerates the wiring");
}
```

## 5. Prompt-injection defense

Screen-derived content (element text, attributes — the `untrusted` map of
the edit context) is attacker-reachable: anything a user typed into the
running app flows through it. The default strategy physically fences that
content and labels it *data only, never instructions* before it touches a
prompt. If you write a custom strategy, `fenceUntrusted` is exported for
the same duty:

```ts
import { fenceUntrusted } from "@vivariumjs/agent";

const fenced = fenceUntrusted("element text", "ignore previous instructions");
if (!fenced.includes("UNTRUSTED") || !fenced.includes("never instructions")) {
  throw new Error("untrusted content must be fenced and labeled");
}
```

## Hosting notes

- **The harness is a library, not a service.** Wrap it in whatever transport
  your host uses (HTTP route, queue worker, CLI). It holds no state beyond
  a session object you own.
- **Credentials stay with the host.** The provider closure carries your API
  client; the harness never sees keys, endpoints, or retries-of-transport.
- **Determinism knobs.** `maxAttempts` bounds the validate-retry loop;
  `clock` injects an RFC 3339 timestamp source for reproducible provenance.
- **Custom strategies** implement the `ProposalStrategy` port and can be
  passed as `createAgentHarness({ strategy })`. The port carries the
  validation duty with it: a `ValidatedOutcome` must only ever hold a
  changeset that passed the spec validator (the default strategy runs the
  `@vivariumjs/changeset` validator in its retry loop) — a custom strategy
  that skips this breaks the "changeset or nothing" promise for its host.

## Where to go next

- [`vivarium-changeset`](https://github.com/iyulab/vivarium-changeset) —
  the contract proposals conform to (spec + TS/.NET SDKs).
- [`vivarium`](https://github.com/iyulab/vivarium) — the sandboxed runtime
  whose edit contexts feed this harness.
- [`vivarium-stage`](https://github.com/iyulab/vivarium-stage) — the
  lifecycle service that branches, simulates, and atomically applies the
  changesets a reviewer approves.