Files
stack/packages/plugins/src/kinds.mjs
T
jason.woltje c216f47dbb plugins, cli, bus, business, webui: harness, model and thinking from the instance vars, a fallback route, and a harness plug-in kind (row 65, #1558)
Adds the harness plug-in kind (interface 1). packages/plugins/harness/pi
and claude-code hold what core branched on: the adapter, thinking levels,
preflight, version probe, sandbox mounts, builtins line, typed tool names,
gate timeout, bundle files, adapter env, turn end and session-files path.
Core reaches a module only through the loader.

A session's route is the instance's harness, model and thinking vars, or
the three fallback. vars; a missing one refuses no-route, and the system
file's execution keys are never read for a session. The launcher checks
the primary route, then the fallback: harness-off, harness-refused,
thinking-unsupported, then preflight. A failed preflight falls back when
a fallback is set, and any refusal of the fallback names the primary's
failure too. Account checks run
only when the route's module counts an account. The manifest records
route, routeReason and harnessVersion, replacing piVersion and
claudeVersion. pi gets --thinking, Claude Code --effort, both from
MOSAIC_THINKING.

The business file refuses a partial fallback. routes and routes.set are
human-only bus verbs outside ORGANIZATION_KEYS; checkRoutes is shared by
routes.set, instances.set and limits.set and checks only changed routes.
The chief of staff changes an instance's model, and the assistant's whole
vars (Q169), through limits.set, so its route write runs the same checks.
A model outside launch.models refuses unknown-model, primary or fallback,
and routes.set passes that code through.
A new run binds only on a switched-on harness module name and records
its transcript path, which the usage reader uses. Settings gains a
Routing table with six selects per instance and loses the Role models
fieldset; it posts changed rows to /api/routes. webui/src/bus.mjs is
unchanged.

Until Jason's `mosaic plugins set` adds "harness": ["claude-code"], a new
launch refuses harness-off.
2026-10-19 11:27:19 -05:00

106 lines
5.6 KiB
JavaScript

// The plug-in kind registry (REQ-PLUG-1; the first two kinds are
// REQ-LIMIT-4's). A kind names the exports its modules must provide, the
// interface version they implement, and whether the organization file
// switches on one module or a list. Adding a kind, or changing one, is a
// core change: a reviewed edit to this file.
export const NAME = /^[a-z][a-z0-9-]*$/;
export const KINDS = Object.freeze({
// Reads one turn's usage for the limit checks (row 124 converts the first).
"usage-source": Object.freeze({
kind: "usage-source", interfaceVersion: 1, exports: Object.freeze(["readTurn"]), switch: "list",
}),
// Decides whether a launch may start, whether a running session must stop,
// and what each limit has used (REQ-LIMIT-3; version 2 since row 125). Core
// calls each with the business's limits and usage rows, never a store:
// mayLaunch({ business, limits, subject, records, now }) -> { allow: true } | { allow: false, hit }
// mustStop({ business, limits, subject, records, now }) -> { stop: false } | { stop: true, hit }
// report({ business, limits, records, now }) -> [{ path, limit, since, count, kinds, unknownTurns }]
// with hit = { path, limit, count, unknownTurns } and subject = { instance, provider, model, account }.
"limit-check": Object.freeze({
kind: "limit-check", interfaceVersion: 2, exports: Object.freeze(["mayLaunch", "mustStop", "report"]), switch: "list",
}),
// Answers web_search for a role's web tool (REQ-HARN-2, REQ-PLUG-2). The organization file names
// one source, and the module's name is the choice: harness-builtin, searxng-bundled or
// searxng-url (technical decision 0b81b0c5). The broker calls `search` with the business's
// settings and an AbortSignal (`search(settings, query, deps, { signal })`); harness-builtin's `search` only refuses, since the harness serves web itself.
"search-source": Object.freeze({
kind: "search-source", interfaceVersion: 1, exports: Object.freeze(["search"]), switch: "one",
}),
// Human project/thread surfaces; proof and the recovery writer remain in core.
channel: Object.freeze({
kind: "channel", interfaceVersion: 1, exports: Object.freeze(["dispatch"]), switch: "list",
}),
// A managed session's harness (row 65, REQ-PLUG-2, Q156). Core reaches a harness only through
// these, each a function the launcher, the bundle and the usage reader call on the host; the
// sandboxed runner gets their answers as data in session.json. The organization file switches
// on a list, and an instance's `harness` var names one of them. packages/plugins/README.md has
// each one's contract:
// adapter() -> the adapter script's absolute path levels() -> the thinking levels it applies
// preflight({ env }) -> null | { code, message } version({ env }) -> string | null
// countsAccount() -> true when its launches spend launch.account
// mounts({ env }) -> read-only binds [{ src, dest, why }]
// builtinWeb() -> true when it serves harness-builtin web
// builtins({ tools, webBuiltin }) -> its names for the built-in tools
// typedName(name) -> its name for a typed bus tool reliesOn() -> the row S0 lines
// gateTimeout() -> the gate hook's timeouts | null
// bundle({ dir, files, session, write, quote }) -> { files, digests, sources }, its own bundle files
// env({ files, policy, tools, session }) -> its adapter variables, written into session.json
// turnEnd() -> "marker" (a turn ends only with the turn marker) | "exit"
// transcript({ runDir, store }) -> the directory its transcripts land in, for usage
harness: Object.freeze({
kind: "harness", interfaceVersion: 1, switch: "list",
exports: Object.freeze(["adapter", "levels", "preflight", "version", "countsAccount", "mounts", "builtinWeb", "builtins",
"typedName", "reliesOn", "gateTimeout", "bundle", "env", "turnEnd", "transcript"]),
}),
});
export class PluginError extends Error {
constructor(code, message, name = null) {
super(message);
this.code = code;
this.name = "PluginError";
this.plugin = name;
}
}
const raise = (code, message, name) => {
throw new PluginError(code, message, name);
};
// The module names one kind's setting switches on, checked against the
// kind's cardinality and the name pattern. A list may be empty.
export function namesFor(spec, setting, where, fail = raise) {
if (spec.switch === "one") {
if (typeof setting !== "string") fail("bad-setting", `${where} must be one module name`);
} else if (!Array.isArray(setting)) {
fail("bad-setting", `${where} must be a list of module names`);
}
const names = spec.switch === "one" ? [setting] : setting;
const seen = new Set();
for (const name of names) {
if (typeof name !== "string" || !NAME.test(name)) {
fail("bad-name", `${where} names ${JSON.stringify(name)}, which doesn't match ${NAME}`,
typeof name === "string" ? name : null);
}
if (seen.has(name)) fail("bad-setting", `${where} names ${name} twice`, name);
seen.add(name);
}
return names;
}
// The organization file's `plugins` object: one key per kind, each a known kind.
export function checkPlugins(value, where, { kinds = KINDS, fail = raise } = {}) {
if (value === null || typeof value !== "object" || Array.isArray(value)) {
fail("bad-setting", `${where} must be an object with one key per kind`);
}
for (const [kind, setting] of Object.entries(value)) {
if (!Object.hasOwn(kinds, kind)) {
fail("unknown-kind", `${where} names unknown kind ${JSON.stringify(kind)}; adding a kind is a core change`);
}
namesFor(kinds[kind], setting, `${where}.${kind}`, fail);
}
return value;
}