Host services

Discover your Host’s contracts#

Call host.services to inspect the running Host. Its response gives registered services and their actual parameter/result contracts, including differences between builds.

import { trove } from "@trove/plugin-sdk";

await trove.ready();
const available = await trove.call("host.services", "list", { prefix: "host." });
const storageContract = await trove.call("host.services", "describe", {
  service: "host.storage",
});
console.log(available, storageContract);

A version range mismatch rejects with service.version_mismatch. Status is Declared, Starting, Available, or Unavailable; registration alone does not prove a Backend is running.

Runtime and paths#

The final four operations require the desktop Host. Use the returned paths rather than hard-coding a user’s home or application data directory. data is for persistent files, cache for regenerable content, and temp for session work.

Store small JSON values#

host.storage isolates keys by the Host-bound Curio ID. A single serialized value is limited to 1 MiB and the serialized store to 16 MiB. It is JSON storage, not a keychain.

const storage = trove.service("host.storage");
const key = `docs-demo-${crypto.randomUUID()}`;
try {
  await storage.call("set", { key, value: { theme: "system" } });
  const saved = await storage.call<{
    found: boolean;
    value: { theme: string } | null;
  }>("get", { key });
  console.log(saved.found, saved.value);
} finally {
  await storage.call("delete", { key });
}

A missing key returns found: false, value: null. A stored JSON null returns found: true, value: null; check found before interpreting the value. Use the data directory for larger files.

Work with files#

host.fs.readText({ path }) returns { content: string }; writeText({ path, content }) returns { written: true }. Paths are filesystem paths, not browser URLs. Current text and binary transfers are limited to 4 MiB per file.

const { temp } = await trove.call<{ temp: string }>("host.runtime", "getPaths", {});
const path = `${temp}/docs-${crypto.randomUUID()}.txt`;
try {
  await trove.call("host.fs", "writeText", { path, content: "Hello Trove" });
  const file = await trove.call<{ content: string }>("host.fs", "readText", { path });
  console.log(file.content);
} finally {
  await trove.call("host.fs", "remove", { path });
}

Ask users to select their files through host.dialog when appropriate. Host filesystem calls do not imply the selected path is a Curio-only sandbox; respect the user’s intended file scope and macOS permissions.

Desktop integrations#

const clipboard = await trove.call<{ text: string }>("host.clipboard", "readText", {});
console.log(clipboard.text);
await trove.call("host.notification", "show", {
  title: "Export complete",
  body: "Your file is ready.",
});

Clipboard supports readText({}) → { text }, writeText({ text }) → { written: true }, and clear({}) → { cleared: true }. Notification currently supports only show({ title, body }) → { shown: true, curioId }.

Use describe to retrieve the full contract before integrating the following services:

Implemented and planned capabilities#

Do not infer method availability from a service name in an architecture draft. Handle service.not_found and service.method_not_found and check the installed Host version before enabling a feature.