Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

4.2 KB
Raw Blame
/**
 * The plugin contract: what a plugin package compiles against.
 *
 * Types, plus the five decorators — the same ones the harness's own modules are written
 * with (core kernel/decorators.ts: no imports, so a plugin's bundle carries them and
 * nothing else of the SDK) — and `sessionShell`, which a plugin reads from the host's copy
 * (see below). The host that drives a plugin lives in whatever embeds this SDK (for the
 * harness, `@adelie/server/plugin`); a plugin reaches THAT with `import type`
 * only and stays a self-contained library that happens to satisfy an interface.
 *
 * A plugin is an npm package; what it carries is what it ships. Its MODULES — the same
 * unit the harness itself is built from — are written the same way: a `@Component` (or
 * `@Module`) class whose `@Use` / `@Provide` / `@Bind` fields are its requirements,
 * provisions and contribution code halves. Their manifests are GENERATED, not written:
 * the package's build runs `scripts/gen-ifaces.mjs` over its own tsconfig and ships the
 * resulting `ifaces.json` beside its `package.json` — the same table the harness
 * generates for itself, holding the manifest of every decorated class and the signature
 * of every interface they name. That table IS the module payload: the host reads it
 * without executing the package, and the package's default export names the classes to
 * boot. A package without one ships no modules.
 *
 *   // package.json
 *   "files": ["dist", "ifaces.json"],
 *   "scripts": { "build": "node ../../scripts/gen-ifaces.mjs --project tsconfig.json --out ifaces.json && tsup" }
 *   // src/index.ts
 *   @Component({ contributes: { "SandboxModule.providers": [{ id: "sandbox-bwrap.provider", name: "penguin-bwrap", dimensions: ["fs-write", "network", "mask-paths"] }] } })
 *   export class SandboxBwrap {
 *     @Bind("sandbox-bwrap.provider") provider!: SandboxProviderSource;
 *     setup() { this.provider = createProvider(); }
 *   }
 *   export default { modules: [SandboxBwrap] } satisfies Plugin;
 *
 * The modules boot as children of the host's tree, once per App creation — the
 * packaged boot and each hot-swap boot alike — so what a module registers never
 * survives into a generation it did not register with. What it may require is what the
 * host publishes as interfaces (for the harness: everything under
 * `@adelie/server/plugin`); the requirement is checked structurally,
 * at signature level, before the module is created.
 */
import type { ModuleClass } from "../kernel/decorators.js";

export type { ClassCtx } from "../kernel/module.js";
export type { ComponentMeta, ModuleClass, ModuleMeta } from "../kernel/decorators.js";
export { Bind, Component, Module, Provide, Use } from "../kernel/decorators.js";
export type { Opaque, Slot } from "../kernel/markers.js";
export { Interface } from "../kernel/markers.js";

/**
 * The harness's session shell — resolved once per process, the shell of the system prompt's
 * `Shell:` line — for a backend whose confinement depends on which program that is (DSH's
 * Windows ACL runner cannot start bash). Unlike the decorators it is the HOST's value: a
 * plugin that bundles this entry reads it from the host's copy at run time, by a specifier its
 * bundler leaves alone and by namespace, because a host core from before this export has none.
 */
export { sessionShell } from "../environment/tools/command/shell.js";

export type * from "./sandbox.js";

/**
 * What a plugin package's default export is.
 *
 * `modules` ADD nodes under the host's root. `replaces` STAND IN for nodes the host
 * already has, by name — any node: a component, a module, a whole group with its
 * children — a class of the replaced node's NAME, whose manifest in the package's
 * `ifaces.json` declares its own requires / provides / contributes / children / exports.
 * Nothing about a replacement is checked when it is put in place; the tree it results
 * in is checked as one, before any node runs — every requirement resolved at signature
 * level, every provision present on the instance — so a replacement that offers less
 * than its consumers need is refused by name, and the App does not boot.
 */
export interface Plugin {
  modules?: readonly ModuleClass[];
  replaces?: readonly ModuleClass[];
}