Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

9.7 KB
Raw Blame
// The one error contract the whole Home surface speaks.
//
// Three different readers consume a failure from /api/home/*: the connect UI,
// which has to say something a person can act on; the agent tool layer, which
// hands the result to a language model; and the bridge runtime itself. If each
// route invented its own shape those three would disagree, and the disagreement
// would surface as an agent treating a refusal as a success. So the vocabulary
// lives here, once, and every route maps through `homeError`.
//
// The vocabulary is the `@three-ws/home-bridge` ERR set (bad_url, auth,
// unreachable, call_failed, needs_confirmation, no_mcp, not_connected) plus the
// transport codes a client library cannot produce on its own (not_found,
// unauthorized, validation_error). One table for the client, not two.
//
// Two mappings in here are deliberate and worth stating out loud:
//
//   * `needs_confirmation` is 409, not 403 and not 200. It is a conflict with
//     the current authorization state and it is retryable with the same body
//     plus a human's explicit yes. A 403 reads as terminal to every HTTP client
//     ever written, and a 200 with an error field reads as SUCCESS to a language
//     model, which is exactly how an agent talks itself into unlocking a door.
//   * `auth` is 400, not 401. A 401 from us would mean "your three.ws session is
//     bad"; this code means "Home Assistant rejected the token you gave us",
//     which is a problem with the submitted data. Conflating them makes a
//     browser log the user out because their house's token expired.
//
// The response body carries the code twice on purpose. `error` /
// `error_description` is the platform-wide envelope that every existing three.ws
// client and the shared `error()` helper in api/_lib/http.js already read;
// `code` / `message` is the shape the Home surface's own clients (orders 04 and
// 05) were specified against. Emitting both costs 30 bytes and means neither
// reader needs a special case.

import { ERR, HomeBridgeError } from '@three-ws/home-bridge';

import { error as httpError } from '../http.js';
import { HOME_RUNTIME_ERR } from './runtime.js';

/** The bridge vocabulary plus the codes only a transport can produce. */
export const HOME_ERR = Object.freeze({
	...ERR,
	/** Not this caller's home. Also what an unknown id returns: never confirm existence. */
	NOT_FOUND: 'not_found',
	/** No three.ws session and no valid bearer token. */
	UNAUTHORIZED: 'unauthorized',
	/**
	 * The caller IS in this household and their role does not hold the capability
	 * this route needs. Distinct from NOT_FOUND on purpose: 404 says nothing and
	 * is the answer across a tenancy boundary, while 403 is safe to say inside one
	 * and is the only answer that lets a guest refused an unlock understand it is
	 * their role rather than a broken door. See api/_lib/home/members.js.
	 */
	FORBIDDEN: 'role_forbidden',
	/** The request body or query is malformed. */
	VALIDATION: 'validation_error',
});

/**
 * HTTP status per code. Anything absent from this table is a bug in the caller,
 * not a client error, so it falls through to 500 and gets reported.
 */
const STATUS_BY_CODE = Object.freeze({
	[HOME_ERR.BAD_URL]: 400,
	[HOME_ERR.AUTH]: 400,
	[HOME_ERR.VALIDATION]: 400,
	[HOME_ERR.UNAUTHORIZED]: 401,
	[HOME_ERR.FORBIDDEN]: 403,
	[HOME_ERR.NOT_FOUND]: 404,
	[HOME_ERR.NEEDS_CONFIRMATION]: 409,
	[HOME_ERR.SERVICE_DENIED]: 403,
	[HOME_ERR.UNREACHABLE]: 502,
	[HOME_ERR.CALL_FAILED]: 502,
	[HOME_ERR.NOT_CONNECTED]: 503,
	// no_mcp is not an error on any route: a home without the Model Context
	// Protocol Server integration is an ordinary home. It reaches the client as
	// `capabilities.mcp = false` plus the setting path to turn it on. It is
	// mapped here only so a stray throw from the MCP probe still lands as a
	// client-fixable 400 rather than a 500 someone has to page about.
	[HOME_ERR.NO_MCP]: 400,
});

/**
 * The runtime raises three codes of its own (api/_lib/home/runtime.js) so its
 * internal states stay distinguishable in a log. A client must not have to learn
 * a second vocabulary for them, so each one collapses onto the published code
 * that means the same thing to a person, and the precise one rides along as
 * `detail_code` for whoever is reading the server log at 3am.
 *
 *   home_not_found   -> not_found      "no such home", said without confirming one
 *   home_revoked     -> auth           the credential is gone; reconnect the home
 *   home_breaker_open-> not_connected  retries are paused; try again shortly
 *   home_at_capacity -> not_connected  this instance is full; retry-after is set
 *   home_stream_shed -> not_connected  live updates yielded to actions; same
 *
 * The last two are the backpressure ladder's refusals (api/_lib/home/admission.js)
 * and they are the reason `retry_after` exists on this envelope at all. A 503
 * without one is indistinguishable from an outage, and a client that cannot tell
 * "full for a moment" from "broken" backs off for far too long or not at all.
 */
const RUNTIME_CODE_ALIASES = Object.freeze({
	[HOME_RUNTIME_ERR.NOT_FOUND]: HOME_ERR.NOT_FOUND,
	[HOME_RUNTIME_ERR.REVOKED]: HOME_ERR.AUTH,
	[HOME_RUNTIME_ERR.BREAKER_OPEN]: HOME_ERR.NOT_CONNECTED,
	[HOME_RUNTIME_ERR.AT_CAPACITY]: HOME_ERR.NOT_CONNECTED,
	[HOME_RUNTIME_ERR.STREAM_SHED]: HOME_ERR.NOT_CONNECTED,
});

/**
 * Build a coded failure. Returns (never throws) a `HomeBridgeError` so the
 * runtime, the store and the routes all raise one class.
 *
 * @param {string} code one of HOME_ERR
 * @param {string} message a sentence a person can act on
 * @param {{ pending?: object, detail?: object, cause?: unknown }} [extra]
 * @returns {HomeBridgeError}
 */
export function homeFailure(code, message, extra = {}) {
	const err = new HomeBridgeError(code, message, extra.cause);
	if (extra.pending) err.pending = extra.pending;
	if (extra.detail) err.detail = extra.detail;
	return err;
}

/** The 404 every ownership miss returns, worded so it reveals nothing. */
export function notFound(what = 'home') {
	return homeFailure(HOME_ERR.NOT_FOUND, `No such ${what}.`);
}

/**
 * Normalize anything throwable into the wire shape, without deciding to send it.
 * Exported so order 04's tools can render the same fields into a tool result and
 * a test can assert the mapping without an HTTP round trip.
 *
 * @param {unknown} err
 * @returns {{ status: number, code: string, message: string, pending: object|null, unexpected: boolean }}
 */
export function toHomeFailure(err) {
	const raw = err instanceof HomeBridgeError ? err.code : null;
	const code = raw ? RUNTIME_CODE_ALIASES[raw] ?? raw : null;
	const status = code ? STATUS_BY_CODE[code] : undefined;
	if (!code || !status) {
		return {
			status: 500,
			code: 'internal_error',
			// Never echo an unknown throwable's message: it can carry a URL with a
			// token in it, a stack, or a database string. The correlation id in the
			// server log is how this one gets diagnosed.
			message: 'Something went wrong reaching your home.',
			pending: null,
			detailCode: null,
			retryAfterSeconds: null,
			unexpected: true,
		};
	}
	return {
		status,
		code,
		message: err.message || 'Your home could not be reached.',
		pending: err.pending ? sanitizePending(err.pending) : null,
		detailCode: raw !== code ? raw : null,
		retryAfterSeconds: Number.isFinite(err?.retryAfterSeconds) ? err.retryAfterSeconds : null,
		unexpected: false,
	};
}

/**
 * Send a coded failure. The single exit every /api/home/* route uses for a
 * non-2xx, so the body shape cannot drift between them.
 *
 * A 5xx that did not come from the vocabulary is re-thrown to `wrap`, which owns
 * correlation ids, Sentry capture and the ops alert. Swallowing it here would
 * turn a real outage into a quiet 500 nobody sees.
 *
 * @param {import('node:http').ServerResponse} res
 * @param {unknown} err
 */
export function homeError(res, err) {
	const failure = toHomeFailure(err);
	if (failure.unexpected) throw err;
	// A shed request is retryable and says so in the one place every HTTP client
	// already looks, as well as in the body for the ones that do not.
	if (failure.retryAfterSeconds != null) res.setHeader('Retry-After', String(failure.retryAfterSeconds));
	return httpError(res, failure.status, failure.code, failure.message, {
		code: failure.code,
		message: failure.message,
		...(failure.detailCode ? { detail_code: failure.detailCode } : {}),
		...(failure.retryAfterSeconds != null ? { retry_after: failure.retryAfterSeconds } : {}),
		...(failure.pending ? { pending: failure.pending } : {}),
	});
}

/**
 * What a 409 tells the client about the action it must confirm.
 *
 * The point of `pending` is that the client can re-POST it verbatim with
 * `confirmed: true` after a human says yes, so it has to carry the RESOLVED
 * target (the entity id the gate actually matched), not the phrase or the area
 * name the caller sent. Confirming "the door" and having a different door open
 * is the failure mode this shape exists to prevent.
 *
 * Nothing but the known keys survives, because `pending` originates inside a
 * bridge error whose `data` came from the caller and is echoed straight back
 * into a model prompt in order 04.
 */
function sanitizePending(pending) {
	const out = {};
	if (pending.domain) out.domain = String(pending.domain);
	if (pending.service) out.service = String(pending.service);
	if (pending.tool) out.tool = String(pending.tool);
	if (pending.entityId) out.entityId = String(pending.entityId);
	if (Array.isArray(pending.targets)) out.targets = pending.targets.map(String);
	if (pending.risk) out.risk = String(pending.risk);
	if (pending.data && typeof pending.data === 'object') out.data = pending.data;
	if (pending.arguments && typeof pending.arguments === 'object') out.arguments = pending.arguments;
	if (pending.phrase) out.phrase = String(pending.phrase);
	return out;
}