@lovelace-ai/lattice-relay-client

This package is for services that submit durable work to one account-owned Lattice runtime. It builds schema-version-2 agent tasks, seals submissions, polls cursor-based progress, opens terminal results, sends cancellation, and acknowledges stored results.

The package is incubating at 0.0.x. Consumers must pin a compatible patch range until the public contract completes an AI-deslop review.

Install

pnpm add @lovelace-ai/lattice-relay-client \
  @lovelace-ai/lattice-relay-crypto

Create a controller

The caller owns OAuth token refresh and durable state. The client requests a current token for each call.

import { RelayControllerClient } from "@lovelace-ai/lattice-relay-client";
import { sealWork } from "@lovelace-ai/lattice-relay-crypto";

const controller = new RelayControllerClient({
  baseUrl: "https://lattice.uselovelace.com/v1/personal-relay",
  getToken: () => accessToken,
  seal: sealWork,
});

Submit one agent task

Callers must mint and persist the logical submission ID, work ID, and encrypted reply private key before the network request. A retry must reuse those values so the relay returns the original work item. Build the schema-version-2 command with buildAgentTaskCommand, then submit its encoded bytes.

const submitted = await controller.submitWork({
  latticeId,
  accountId,
  controllerId: "docket:athena",
  keyId: runtimeWorkKey.keyId,
  recipientPublicKey: runtimeWorkKey.publicKey,
  workId,
  logicalSubmissionId,
  plaintext: new TextEncoder().encode(JSON.stringify(command)),
  deadlineAt: deadline.toISOString(),
});

Poll with pollEvents(workId, lastCursor). Persist each new cursor before the next poll. Open progress and results with the stored reply private key. After storing the terminal result, call acknowledgeResult(workId) so the relay can release its ciphertext.

DelegateService composes the same operations for process-bound tools. InMemoryDelegateSessionStore loses reply keys and in-flight work on restart. Do not use that store in a durable scheduler.

Explicit personal relay work never falls back to shared or hosted compute. An offline runtime returns a visible queued state or a typed failure.

License

MIT