Hio Client Server

Canonical Human Is Offline agent loop for npm and MCP.

Source repo for the public npm package. The hosted app lives in a separate private monorepo.

Install

npm install @humanisoffline/hio-client

API

import {
  createHioClient,
  buildAskFirstEnvelopeFromCard,
  HIO_PROTOCOL_VERSION,
} from "@humanisoffline/hio-client";

const hio = createHioClient({ baseUrl: "https://humanisoffline.com" });

const resolved = await hio.resolveCard({
  type: "github",
  identifier: "octocat",
});

const markdown = await hio.fetchCardMarkdown(resolved.cardMarkdown);
const cardJson = await hio.fetchCardJson(resolved.cardJson);

const result = await hio.submitAskFirstNotePlaintext({
  cardJson,
  plaintext: {
    schemaVersion: HIO_PROTOCOL_VERSION,
    type: "inform",
    title: "Need approval",
    summary: "Deploy staging after tests pass.",
    urgency: "normal",
    riskLevel: "medium",
  },
  interpretedBoundary: {
    outcome: "ask_first",
    summary: "Deploy staging",
  },
});

const receipt = await hio.getReceipt(result.receiptUrl);

Lower-level envelope builder

If you already have card fields and the public encryption key:

import { buildAskFirstEnvelope } from "@humanisoffline/hio-client";

const envelope = buildAskFirstEnvelope({
  cardSlug: "example",
  cardUpdatedAt: "2026-07-12T12:00:00.000Z",
  cardSchemaVersion: 3,
  publicEncryptionKey: "…",
  publicKeyId: "pk_…",
  plaintext: { /* see agent-request.v3.json */ schemaVersion: 3, … },
});

await hio.submitAskFirstNote({ cardSlug: "example", envelope });

Encryption uses sealed_box_v1 (NaCl box). Plaintext is never sent to the server.

MCP server

HIO_BASE_URL=https://humanisoffline.com npx @humanisoffline/hio-client hio-mcp

One agent loop via tools:

1. fetch_card_markdown — read authority from /c/{slug}.md
2. fetch_card_json — structured fields and encryption keys
3. submit_ask_first_note — pass cardJsonUrl + plaintext; encrypts and posts one inbox note
4. get_receipt — fetch delegation receipt JSON

Optional: resolve_card when the human shared an alias instead of a card URL.

submit_ask_first_note is the only submit path. It fetches card JSON, builds the sealed envelope, and stops after one POST.

Discovery: read /llms.txt on the configured base URL for routes and schemas.

Network access

This package makes outbound HTTPS requests to the configured Human Is Offline base URL (https://humanisoffline.com by default). It does not phone home elsewhere, collect telemetry, or run code at install time.