Host API

There is no ambient global and no client you construct. The API arrives as the argument to activate(), everything you register comes back as a disposable, and every door to the daemon on it is gated by the route allowlist in your manifest. If you are writing your first extension, start with Build an extension — this page is the reference it links back to.

Getting the handle#

import type { ExtensionContext, IntenticApi } from "@intentic/extension-api";
import { bindHost } from "./host.js";

export const activate = (api: IntenticApi, context: ExtensionContext): void => {
    bindHost(api);

    context.subscriptions.push(
        api.views.register({ /* … */ }),
        api.commands.register(`incidents.acknowledge`, () => { /* … */ }),
    );
};

Views and composables that render later need the same handle, and passing it down through props is not what anyone wants to write. hostSlot() gives your extension its own module-scoped accessor:

import { hostSlot } from "@intentic/extension-api";

// One slot per extension, bound by activate() before anything renders. The shell publishes ONE copy of the
// API module to every bundle, so a handle held at module scope would be a global the last extension to
// activate silently takes over.
export const { bindHost, host } = hostSlot(`ext-incidents`);

Push every registration onto context.subscriptions. They are disposed in reverse order when the extension is switched off, which is what makes turning it off actually unwind it rather than leave tiles behind.

api.sandbox — talking to the daemon#

Auth is injected host-side; an extension never sees a token. Reach is scoped: every door here is checked against your manifest's permissions.sandbox allowlist, so a call to an undeclared method and path throws rather than reaching the whole daemon.

import { useQuery } from "@tanstack/vue-query";
import { computed } from "vue";
import { host } from "./host.js";

const api = host();

const query = useQuery({
    // Scoped to the ACTIVE sandbox, so a switch can't serve you another box's data.
    queryKey: computed(() => api.sandbox.key(`incidents`, `log`, repo.value)),
    // A procedure, not a URL: the input shape and the answer's shape are both checked at build time.
    queryFn: () => api.sandbox.rpc.git.log({ repo: repo.value, limit: 300 }),
    // A sleeping sandbox produces no wall of errors.
    enabled: computed(() => api.sandbox.reachable()),
});

You get the shell's own Vue and vue-query instances, so your components join the app's single query cache and re-theme with it. The routes behind rpc are the ones on the HTTP API page.

api.workspace — repos, files and diffs#

Keep durable state in the workspace rather than in settings. It survives a reload, it is shared across the owner's browsers, and the agent writing into it out of band is usually the whole point. The file routes still need declaring — api.workspace.file removes the encoding, not the grant.

api.views — the sidebar surfaces#

A view registers once and produces one activation per sidebar element, decided by detect() against the facts. Activate on evidence, not names: "this repo has a vitest config" survives a rename, "this repo is called api" does not.

// Module state, not view state: a badge you only see once you have already navigated to the view is
// pointless, so the count has to keep working while the view is unmounted.
let openCount = 0;

api.views.register({
    id: `incidents`,
    label: `Incidents`,
    surface: `rail`,
    detect: (repos) => repos.filter((repo) => repo.vitest).map((repo) => ({ key: repo.repo, title: repo.repo, repo: repo.repo })),
    badge: () => (openCount > 0 ? { count: openCount, tone: `warning`, tooltip: `${openCount} need triage` } : undefined),
    view: async () => (await import(`./IncidentsView.vue`)).default,
});

A badge is a claim on someone's attention, so the bar is high: it must mean "something happened here you don't know about", never "here is a statistic". A count lit most of the day teaches people to stop seeing the rail. count is for work whose size is what you act on; mark is a glyph for a pending action where the size changes nothing; tone is info (the resting tone), warning (a risk being carried) or danger (something is broken — stay sparing, its value is that it is rare).

badge is read inside the host's own computed and runs on every render of every surface that draws tiles, so it must be cheap and pure: derive it from state you already keep, never fetch.

api.viewers and api.documents#

documents.detect is called for every visible directory row on every render of the tree. Like badge, it must be a lookup and never a fetch, and the state it reads has to outlive the view being unmounted — so it belongs in module state owned by activate().

api.commands and api.settings#

api.processes, api.terminal and api.chat#

api.models — which model a run will spend#

The picker is not a widget: it is a live read of every connected provider's catalog, which credentials the sandbox actually holds, and what each model can do. An extension that rendered its own control could only offer a worse list — and would happily offer models the sandbox has no credential for, which is a run that fails minutes later.

A PickedModel covers the whole choice: provider, model, a display label, and optionally which connected account and which harness. The last two are pins, and absent — "whatever the daemon resolves" — is the state most callers want, because it is what keeps a saved choice working after an account is disconnected. Pin the account when the surface starts unattended runs: nobody is watching at 6am, and a first account that has run out of headroom is a run that errors every time until someone reads the row.

api.navigate, api.route and api.theme#

A view's own route space is the query, not the path: /ext/:ext/:key? is the whole route and :key already means "which activation". So a view with internal navigation — an open document, a selected run — puts that state in the query, which is what lets a reload keep it and a link carry it. Derive from the URL rather than mirroring it into a ref; back and forward then work for free.

The backend half — activateServer()#

An extension with a manifest server entry has a second, smaller surface. The bundle exports activateServer(api, context), and the daemon's backend host — one supervised node process shared by every enabled backend — imports it and calls it once per host start. There is no deactivate: retirement is the host process ending, which is the one teardown that cannot leak.

The surface is deliberately small because the trust model is full trust: installs are owner-only and sha-pinned, and the backend runs as the same user the daemon does. What the API mediates is exactly the two things a path cannot carry — your route namespace, and your declared reach into the daemon.

Versioning#

api.apiVersion is the host's extension-API version, and it is what your manifest's engines.intentic range is checked against before your code is loaded. Current API: 2.1.0. Additive surface is a minor bump, breaking is a major — so "^2.0.0" is the range you want, or "^2.1.0" if you ship a backend.

The packages#

Mark all of them external when you bundle, along with vue and @tanstack/vue-query. The host supplies them at runtime, and bundling your own copy forks reactivity and the query cache.

Next#

• HTTP API: the routes behind api.sandbox.rpc, and how to call them without a browser.
• Build an extension: the same surface as a walkthrough, ending in a real install.
• Manifest reference: every contribution point these registrations have to match.