Integration SDK

What a host does

An integration host decides how its sessions map to LayerFS projects, starts Init, shows history and Workspace state, and keeps the installation tidy. Its agents still do their work through@layerfs/agent; a host passes them the LAYERFS_* settings.

@layerfs/runtime

The runtime opens on a LayerFS home, not on a project, so it works before the first project exists, after one is removed and while the worker is down. Agents' Bash calls use thelayerfs command, the checkout's api/agent/cli/ folder over @layerfs/agent; the runtime has no command of its own (its older lfs command is retired). Link it from the checkout like the other packages:npm install "file:$LAYERFS_REPO/api/runtime" "file:$LAYERFS_REPO/api/backend".

import { LayerFSRuntime } from "@layerfs/runtime";

const runtime = await LayerFSRuntime.open({ home, image, bundle });   // a LayerFS home, not a project
try {
  const { missing } = await runtime.status();                          // settings still missing, if any
  const job = await runtime.project.start_init("shop", "/src/shop", { timeout: 600_000 });
  console.log(await runtime.project.get_init(job.id));                 // { step, scanned, totals, imported, … }
  for await (const event of runtime.events.subscribe({ project: "shop" })) {
    console.log(event.actor, event.method, event.ms);                  // one line per call, from every process
  }
} finally {
  await runtime.close();
}

start_init passes timeout unchanged to LayerFS.init, so an omitted one gets its 300 s. A failed Init removes the volume and home entry it made; an uncertain one (Unknown, or any failure on Windows) keeps everything and is recorded in init-failures.jsonl in stateDir. Init labels the project's volume layerfs.role=store, layerfs.home andlayerfs.project, which is how volume.list tells whose it is.

Settings

A missing setting doesn't refuse open; status().missing lists it.

Platforms

The worker route is open to any integration. On macOS and Windows the runtime hands its worker's endpoint to@layerfs/agent (useWorker, without changing the environment), so every client made afteropen in its process uses the worker; a client made before keeps its in-process binding. One worker per process: a second runtime of another home is refused. Another process, such as an agent's command, uses the worker when its LAYERFS_WORKER_ENDPOINT names the endpoint file, <home>/worker/endpoint.json; the integration that runs it sets that. The worker checks every file of the bundle's manifest.jsonbefore it listens.

@layerfs/backend

The backend wraps an open agent client. store.* calls read the project's Store and need no Sandbox;daemon.* calls need the Sandbox running, else NoSuchSandbox. Background processes run through the Sandbox's ordinary command launcher. Thelayerfs-sdk-observe skill covers these calls and the call trace.

import { LayerFS } from "@layerfs/agent";
import { LayerFSBackend } from "@layerfs/backend";

const layerfs = await LayerFS.open("shop");
const backend = LayerFSBackend.of(layerfs);                 // opens nothing of its own
const history = await backend.store.project.get_history();  // Branches, newest Commits, Layers, version
const storage = await backend.store.project.get_storage();
const proc = await backend.daemon.process.start(ws, "npm run dev");   // a background process in a Workspace
await backend.daemon.process.cancel(proc.process);

No UI in LayerFS

LayerFS ships no UI and serves no HTTP. Its packages are calls that take data and return data; each integration builds its own routes, authentication and views on top of them. DSH's LayerFS tab is one such view, drawn fromruntime.project.get_state, the backend's reads and runtime.events.subscribe. SeeLayerFS × DSH.