@nomix-ai/nomix-harness 0.2.6 → 0.2.7

package/node_modules/@nomix-ai/nomix-agent-presets/lib/types/authoring.js

@@ -0,0 +1,183 @@
+/**
+ * Copying, reading, and deleting locally authored presets.
+ *
+ * Authoring is confined to a `user` root: the shipped `.system` set is part of
+ * the deployment, and letting a browser rewrite it would turn "reset to a known
+ * preset" into something the same caller could have broken first.
+ *
+ * The only authoring write is a whole-directory copy of an existing preset.
+ * No caller supplies composition text: the inputs are ids the host resolves
+ * against its own roots plus an optional display name, so authoring grants no
+ * capability the copied preset did not already carry.
+ * @module @nomix-ai/nomix-agent-presets/authoring
+ */
+import { chmod, cp, readdir, readFile, rm, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { writeFileAtomic } from '@nomix-ai/nomix-atomic-write';
+import { expandHomePath } from '@nomix-ai/nomix-home-paths';
+import { METADATA_FILE, renderPresetMetadata } from "./metadata.js";
+import { PRESET_ID } from "./preset.js";
+/** A preset id that cannot be used as a directory name under a root. */
+export class InvalidPresetIdError extends Error {
+    presetId;
+    constructor(
+    /** The rejected id. */
+    presetId) {
+        super(`agent-presets: preset id ${JSON.stringify(presetId)} must match ${String(PRESET_ID)} — `
+            + 'the id is a directory name, so anything else could escape the preset root');
+        this.presetId = presetId;
+    }
+}
+/** A copy target that is already occupied — a copy never overwrites. */
+export class PresetExistsError extends Error {
+    presetId;
+    constructor(
+    /** The id that is already taken. */
+    presetId) {
+        super(`agent-presets: preset "${presetId}" already exists — `
+            + 'a copy never overwrites; delete the existing preset first or choose another id');
+        this.presetId = presetId;
+    }
+}
+/** Authoring was attempted where the deployment allows none. */
+export class PresetNotWritableError extends Error {
+    presetId;
+    constructor(
+    /** What the caller tried to change, for the diagnostic. */
+    presetId, reason) {
+        super(`agent-presets: preset "${presetId}" cannot be written: ${reason}`);
+        this.presetId = presetId;
+    }
+}
+/**
+ * The root locally authored presets are written to.
+ * @param roots - the configured roots in precedence order.
+ * @returns the absolute path of the first `user` root.
+ * @throws when the deployment configured no writable root.
+ */
+export function writableRoot(roots) {
+    const root = roots.find(candidate => candidate.trust === 'user');
+    if (root === undefined) {
+        throw new PresetNotWritableError('', 'this deployment configures no user-writable preset root');
+    }
+    return resolve(expandHomePath(root.path));
+}
+/**
+ * Read one preset's composition text.
+ * @param preset - the resolved preset.
+ * @returns the file's contents.
+ */
+export async function readComposition(preset) {
+    return await readFile(preset.path, 'utf8');
+}
+/** Whether anything occupies the path (cp's own errorOnExist backstops races). */
+async function occupied(path) {
+    let present = true;
+    try {
+        await stat(path);
+    }
+    catch {
+        // Every stat failure means the same thing here: nothing usable occupies
+        // the path, so the copy may claim it.
+        present = false;
+    }
+    return present;
+}
+/**
+ * Re-tighten a copied tree to owner-only. A shipped preset is world-readable
+ * in its install and `cp` preserves that; the copy carries the same weight as
+ * the settings document beside it, so group/other access is stripped. A
+ * file's owner-execute bit survives — a preset may ship runnable helpers.
+ */
+async function tightenModes(dir) {
+    await chmod(dir, 0o700);
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const target = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            await tightenModes(target);
+        }
+        else {
+            /* v8 ignore next -- Windows exposes no POSIX owner-execute bit; the POSIX lane covers both file modes. */
+            await chmod(target, ((await stat(target)).mode & 0o100) === 0 ? 0o600 : 0o700);
+        }
+    }
+}
+/**
+ * Create a preset by copying an existing one's whole directory.
+ *
+ * The copy carries everything the source directory holds — composition,
+ * metadata, skill directories, assets — because a preset is its directory,
+ * not one file. Symlinks are dereferenced so the copy is self-contained
+ * rather than a set of links back into the install it was copied from.
+ *
+ * The copied metadata is then rewritten: the source's description is kept
+ * (the file is the author's to edit afterwards), but its name and roster
+ * `order` are not — a copy presenting itself identically to its source, or
+ * sorted into the shipped set's declared order, would make the roster stop
+ * distinguishing them. With no name given and no description to keep, the
+ * file is removed so the copy publishes nothing rather than a blank.
+ * @param roots - the configured roots; the first `user` one receives the copy.
+ * @param source - the resolved preset the copy starts from.
+ * @param id - the new preset's id, which becomes its directory name.
+ * @param name - display name for the copy; omitted falls back to the id.
+ * @returns the absolute path of the new preset directory.
+ * @throws when the id is unusable or already occupied on disk, or the
+ * deployment configures no writable root.
+ */
+export async function copyComposition(roots, source, id, name) {
+    if (!PRESET_ID.test(id))
+        throw new InvalidPresetIdError(id);
+    const dir = join(writableRoot(roots), id);
+    // The roster check upstream only sees discovered presets; a directory with
+    // no composition file still occupies the name and deserves a readable
+    // refusal rather than a filesystem error code.
+    if (await occupied(dir))
+        throw new PresetExistsError(id);
+    try {
+        await cp(dirname(source.path), dir, {
+            recursive: true, dereference: true, force: false, errorOnExist: true,
+        });
+        await tightenModes(dir);
+        const rendered = renderPresetMetadata({
+            ...name === undefined ? {} : { name },
+            ...source.description === undefined ? {} : { description: source.description },
+        });
+        const metadataPath = join(dir, METADATA_FILE);
+        if (rendered === undefined) {
+            await rm(metadataPath, { force: true });
+        }
+        else {
+            await writeFileAtomic(metadataPath, rendered, { mode: 0o600, dirMode: 0o700 });
+        }
+    }
+    catch (error) {
+        // A half-copied directory would be invisible to discovery at best and a
+        // mountable-but-incomplete preset at worst; a failed copy leaves nothing.
+        await rm(dir, { recursive: true, force: true });
+        throw error;
+    }
+    return dir;
+}
+/**
+ * Delete a locally authored preset.
+ *
+ * A shipped preset is refused: it belongs to the deployment. A preset a live
+ * session mounted is NOT refused — the composition was read at creation and is
+ * never re-read, so that session keeps running exactly as it was.
+ * @param roots - the configured roots.
+ * @param preset - the resolved preset to remove.
+ * @throws when the preset ships with the deployment or lies outside the writable root.
+ */
+export async function deleteComposition(roots, preset) {
+    if (preset.trust !== 'user') {
+        throw new PresetNotWritableError(preset.id, 'it ships with the deployment');
+    }
+    const dir = join(writableRoot(roots), preset.id);
+    // Belt and braces over the id pattern: the resolved directory must still be
+    // the one the writable root owns, whatever discovery reported.
+    if (!isAbsolute(preset.path) || !preset.path.startsWith(dir)) {
+        throw new PresetNotWritableError(preset.id, 'it does not live under the writable preset root');
+    }
+    await rm(dir, { recursive: true, force: true });
+}
+//# sourceMappingURL=authoring.js.map

package/node_modules/@nomix-ai/nomix-agent-presets/lib/types/discovery.js

@@ -0,0 +1,187 @@
+/**
+ * Filesystem discovery of agent presets. A preset is a directory holding
+ * {@link COMPOSITION_FILE}, optionally beside a {@link METADATA_FILE} carrying
+ * its display text; the directory name is the preset id. Discovery
+ * re-reads the roots on every call so a preset authored while the process is
+ * running is visible without a restart.
+ *
+ * Discovery also owns preset HEALTH: a directory whose composition is
+ * missing or unloadable is reported as a broken roster row rather than
+ * skipped. A skipped directory would still occupy its id on disk — the copy
+ * path refuses the name while no surface shows anything to delete — and a
+ * malformed composition would otherwise read as an ordinary preset until the
+ * first session fails to mount it.
+ * @module @nomix-ai/nomix-agent-presets/discovery
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { load } from 'js-yaml';
+import { entryListSchema } from '@nomix-ai/cordis-plugin-include';
+import { expandHomePath } from '@nomix-ai/nomix-home-paths';
+import { readPresetMetadata } from "./metadata.js";
+import { PRESET_ID } from "./preset.js";
+/** The composition file that makes a directory a preset. */
+export const COMPOSITION_FILE = 'agent.cordis.yml';
+/**
+ * Harness-home directory holding locally authored presets.
+ *
+ * This package owns the writable root the way `nomix-skill-filesystem` owns
+ * `<nomixHome>/skills`. An app must assemble the SHIPPED root, whose path only
+ * the installed app can resolve; where a person's own presets go is the same
+ * place in every deployment that does not say otherwise, so a launcher that
+ * forgets to configure one still finds them.
+ *
+ * Package-internal on purpose: no consumer outside this package addresses the
+ * directory by name, and a test that imported it could not catch this value
+ * being wrong — the expected segment is spelled out where it is asserted.
+ */
+export const USER_PRESET_DIR = '.agent-presets';
+/**
+ * Why `rows` cannot be an entry list, or undefined when it can.
+ *
+ * A shallow shape check, deliberately short of the loader's work: it does not
+ * resolve plugin names or apply configs. What it catches is the hand-edit
+ * that produces a file the loader cannot even begin with — and it must accept
+ * everything the loader accepts, which is why rows are only required to be
+ * maps carrying a plugin `name` (groups recurse into their own lists).
+ * @param rows - the parsed composition document.
+ * @param at - row-path prefix for nested diagnostics, empty at the top level.
+ * @returns one human-readable reason, or undefined when the shape holds.
+ */
+function entryListProblem(rows, at = '') {
+    if (!Array.isArray(rows)) {
+        return at === ''
+            ? 'the composition must be a top-level list of plugin rows'
+            : `group ${at} must hold a list of plugin rows`;
+    }
+    for (const [index, row] of rows.entries()) {
+        const label = at === '' ? `row ${String(index + 1)}` : `${at} row ${String(index + 1)}`;
+        if (typeof row !== 'object' || row === null || Array.isArray(row)) {
+            return `${label} is not a plugin row (expected a map with a "name")`;
+        }
+        const { name, group, config } = row;
+        if (typeof name !== 'string' || name === '') {
+            return `${label} names no plugin (a "name" string is required)`;
+        }
+        if (group === true) {
+            const nested = entryListProblem(config, label);
+            if (nested !== undefined)
+                return nested;
+        }
+    }
+    return undefined;
+}
+/**
+ * Why the composition at `path` cannot mount, or undefined when it looks
+ * loadable. Parsed with the loader's own YAML dialect ({@link entryListSchema},
+ * the one carrying `!!js`), so health can never call a composition broken
+ * that the loader would accept.
+ * @param path - absolute path of the composition file.
+ * @returns one human-readable reason, or undefined when the file is loadable.
+ */
+async function compositionProblem(path) {
+    let content;
+    try {
+        content = await readFile(path, 'utf8');
+    }
+    catch {
+        // The caller statted this file moments ago; any read failure now —
+        // deleted in between, permissions — is the same answer as unparsable.
+        return `the composition file ${COMPOSITION_FILE} cannot be read`;
+    }
+    let rows;
+    try {
+        rows = load(content, { schema: entryListSchema });
+    }
+    catch (error) {
+        /* v8 ignore next -- js-yaml throws YAMLException (an Error) for every parse failure; the fallback keeps a hostile value readable */
+        const full = error instanceof Error ? error.message : String(error);
+        // First line only: js-yaml appends a multi-line code-frame snippet, and
+        // the reason is displayed on a roster card, not in a terminal.
+        return `the composition is not valid YAML: ${full.replace(/\n[\s\S]*$/, '')}`;
+    }
+    return entryListProblem(rows);
+}
+/**
+ * Whether `path` names an existing regular file.
+ * @param path - absolute path to test.
+ * @returns true when the path resolves to a file.
+ */
+async function isFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        // Any stat failure — absent, unreadable, a dangling link — means this
+        // directory does not present a composition, which is not an error: the
+        // directory simply is not a preset.
+        return false;
+    }
+}
+/**
+ * Scan one root for preset directories.
+ *
+ * An absent root yields no presets rather than throwing: the user root does
+ * not exist until the first locally authored preset, and naming a default
+ * that no root supplies already fails loud at resolution.
+ *
+ * Every directory whose name is a usable preset id is a roster row — broken
+ * when its composition is missing or unloadable. A directory named outside
+ * {@link PRESET_ID} is skipped instead: no copy could ever claim that name,
+ * so it blocks nothing, and reporting `.DS_Store`-grade residue as broken
+ * presets would teach users to ignore the marker.
+ * @param root - the directory and the trust its presets inherit.
+ * @returns the root's presets ordered by id.
+ */
+export async function scanRoot(root) {
+    const dir = resolve(expandHomePath(root.path));
+    let children;
+    try {
+        children = await readdir(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw new Error(`agent-presets: cannot read preset root ${dir}: ${String(error)}`, { cause: error });
+    }
+    const found = [];
+    for (const child of children) {
+        if (!child.isDirectory() || !PRESET_ID.test(child.name))
+            continue;
+        const directory = join(dir, child.name);
+        const path = join(directory, COMPOSITION_FILE);
+        const broken = await isFile(path)
+            ? await compositionProblem(path)
+            : `the composition file ${COMPOSITION_FILE} is missing — the directory still occupies the id; delete it or restore the file`;
+        // Display text only, and never fatal: a preset with unreadable metadata
+        // still mounts, it just shows its id.
+        const metadata = await readPresetMetadata(directory);
+        found.push({
+            id: child.name, trust: root.trust, path, ...metadata,
+            ...broken === undefined ? {} : { broken },
+        });
+    }
+    // Declared order first so the shipped set reads by capability; everything
+    // else falls back to the id, which keeps authored presets stable.
+    return found.sort((left, right) => {
+        const byOrder = (left.order ?? Number.POSITIVE_INFINITY) - (right.order ?? Number.POSITIVE_INFINITY);
+        return byOrder === 0 ? left.id.localeCompare(right.id) : byOrder;
+    });
+}
+/**
+ * Scan every root in precedence order.
+ * @param roots - roots in precedence order; an earlier root wins a duplicate id.
+ * @returns every discovered preset, first-root-wins per id.
+ */
+export async function discoverPresets(roots) {
+    const byId = new Map();
+    for (const root of roots) {
+        for (const preset of await scanRoot(root)) {
+            if (byId.has(preset.id))
+                continue;
+            byId.set(preset.id, preset);
+        }
+    }
+    return [...byId.values()];
+}
+//# sourceMappingURL=discovery.js.map

package/node_modules/@nomix-ai/nomix-agent-presets/lib/types/index.d.ts

@@ -0,0 +1,291 @@
+/**
+ * Agent presets: each session composes its model-facing plugin set from one
+ * preset `cordis.yml`, mounted ONCE per preset under a standing scope and
+ * joined by every agent that names it.
+ *
+ * The standing mount is what makes a preset one composition rather than one
+ * per session: its plugin instances, tool registrations, prompt sections, and
+ * projection units exist exactly once, keyed per session inside the plugins
+ * themselves (they predate presets and were written for a shared world). An
+ * agent joins by having its scope key parented to the mount's
+ * ({@link bindScopeParent}), which makes the mount's registrations visible to
+ * that agent's views and the mount's listeners receive that agent's events —
+ * and a host reader with no agent at all (a cold transcript read) resolves
+ * the same standing registrations by preset id.
+ *
+ * This package owns the preset vocabulary, filesystem discovery, and the
+ * guarded standing mount. It does not decide when an agent is created — the
+ * agent factory's `setup(agentCtx)` hook is the one supported call site,
+ * because only there is the join installed while the agent is still
+ * unpublished, so a rejected composition rolls the whole creation back.
+ * @module @nomix-ai/nomix-agent-presets
+ */
+import { Context, Service } from '@nomix-ai/cordis';
+import z from '@nomix-ai/schemastery';
+import { type ScopeKey } from '@nomix-ai/nomix-scope';
+import { type AgentPreset, type Config, type PresetRoot } from './preset.ts';
+/** Settings namespace carrying the user's chosen default preset. */
+export declare const SETTINGS_NAMESPACE = "agent-presets";
+/** The user-writable slice of this plugin's config. */
+export interface AgentPresetSettings {
+    /** Preset mounted when a session names none. */
+    default?: string;
+}
+/** Runtime schema for the user-writable slice. */
+export declare const AgentPresetSettingsSchema: z<AgentPresetSettings>;
+export { COMPOSITION_FILE, discoverPresets, scanRoot } from './discovery.ts';
+export { METADATA_FILE, readPresetMetadata, renderPresetMetadata, type PresetMetadata, } from './metadata.ts';
+export { inactiveRows, leakedServices, livePresetMounts, mountPreset, serviceForAgent, standingMountFor, type JoinedPresetMount, type PresetMount, } from './mount.ts';
+export { copyComposition, deleteComposition, InvalidPresetIdError, PresetExistsError, PresetNotWritableError, readComposition, writableRoot, } from './authoring.ts';
+export { resolveSessionPreset, type PresetBearingSession } from './session.ts';
+export { PresetMountError, UnknownPresetError } from './preset.ts';
+export type { AgentPreset, Config, PresetRoot, PresetTrust } from './preset.ts';
+declare module '@nomix-ai/cordis' {
+    interface Context {
+        agentPresets: AgentPresets;
+    }
+}
+/**
+ * Registry over the deployment's agent presets.
+ *
+ * Discovery is unmemoized: `list()` and `resolve()` re-read the roots on every
+ * call so a preset authored while the process runs is visible immediately,
+ * and a preset deleted underneath a picker disappears from the next read.
+ */
+export declare class AgentPresets extends Service {
+    config: Config;
+    static inject: string[];
+    /** Runtime schema for the preset roster. */
+    static Config: z<Config>;
+    /**
+     * The roots discovery and authoring actually scan: every configured root in
+     * order, then the harness-home user root unless `includeUserRoot` is false.
+     *
+     * Derived once, because a root set that changed between `list()` and the
+     * `copy()` acting on its answer would author into a directory the caller
+     * never saw. Appending rather than prepending keeps an earlier configured
+     * root winning a duplicate id, so a shipped preset still shadows a
+     * locally authored directory that claimed its name.
+     */
+    private readonly resolvedRoots;
+    /**
+     * The user layer over `config.default`, present only while a settings
+     * provider is composed. Held rather than snapshotted so a hot-reloaded
+     * document takes effect without a restart.
+     */
+    private settings;
+    /**
+     * The settings service behind {@link settings}, held for the one write this
+     * service makes: clearing a user default it has just deleted.
+     */
+    private settingsService;
+    /**
+     * The service's own untraced context. Methods invoked through the traceable
+     * proxy see `this.ctx` rebound to the CALLER's context, which carries a
+     * shadow; a subtree minted from it resolves every service through that
+     * shadow's fiber instead of each entry's own inject store, so preset rows
+     * would fail on the very services they declare. Standing mounts must hang
+     * off the untraced original (the `jobs-local` selfCtx precedent).
+     */
+    private readonly selfCtx;
+    constructor(ctx: Context, config: Config);
+    /**
+     * The preset id mounted when a caller names none.
+     *
+     * Read per call rather than cached: the settings document is hot-reloaded, so
+     * changing the default takes effect on the next session created and leaves
+     * every running session on the preset it was composed from.
+     */
+    get defaultId(): string;
+    /**
+     * Every preset the configured roots currently supply.
+     * @returns the presets, first-root-wins per id.
+     */
+    list(): Promise<AgentPreset[]>;
+    /**
+     * Resolve one preset by id.
+     *
+     * A broken preset resolves — deleting one, reading one, and reporting one
+     * all need the row — and the mounting paths refuse it AFTER resolution
+     * through {@link resolveMountable}.
+     * @param id - the preset id, or `undefined` for {@link defaultId}.
+     * @returns the resolved preset.
+     * @throws when no configured root supplies that id.
+     */
+    resolve(id?: string): Promise<AgentPreset>;
+    /**
+     * Resolve one preset that is about to compose an agent, refusing a broken
+     * one with its discovery-reported reason. Failing here rather than inside
+     * the loader keeps the answer the same for every unloadable shape — ghost
+     * directory, unparsable YAML, rowless list — and spends no mount attempt
+     * on a composition discovery already read as unusable.
+     * @param id - the preset id, or `undefined` for {@link defaultId}.
+     * @returns the resolved, mountable preset.
+     * @throws when the preset is unknown or discovery reports it broken.
+     */
+    private resolveMountable;
+    /**
+     * Standing mounts by preset id, single-flight so two agents racing the
+     * first use of one preset share one composition. A settled failure is
+     * removed so a later session retries a preset whose file has been fixed; a
+     * settled success serves until the composition FILE visibly changes — each
+     * generation records its file stamp, and a stale stamp starts the next
+     * generation for sessions created afterwards. Sessions already joined keep
+     * the generation they run on; a superseded one is never disposed while the
+     * process lives (reclaimed only by whole-tree teardown), so editing files
+     * is bounded by how often compositions change, not by session count.
+     */
+    private readonly standing;
+    /**
+     * Parent bindings of the agents this roster composed, keyed by the agent's
+     * scope key. The binding is nomix-scope's only re-link capability; holding it
+     * here makes this service the sole authority that can move an agent between
+     * standing compositions. WeakMap: entries die with their agents.
+     */
+    private readonly bindings;
+    /**
+     * Compose one agent from a preset: ensure the preset's standing mount, then
+     * parent the agent's scope key to it so the mount's registrations and
+     * listeners cover this agent.
+     *
+     * Call from the agent factory's `setup(agentCtx)`; a rejection there rolls
+     * the agent creation back, so a broken preset never yields a half-composed
+     * session.
+     * @param agentCtx - the agent's scope context.
+     * @param id - the preset id, or `undefined` for {@link defaultId}.
+     * @returns the preset that was composed, for the caller to record.
+     * @throws when the preset is unknown or its composition is unusable.
+     */
+    mount(agentCtx: Context, id?: string): Promise<AgentPreset>;
+    /**
+     * Join one agent to the SAME standing composition another already runs on.
+     *
+     * This is how a child agent inherits its parent's capabilities. It is a bind,
+     * not a mount: the parent's generation is already composed, so the child gets
+     * that exact instance — the same plugin objects, the same tool registrations,
+     * the same prompt sections. Re-resolving the parent's preset by id instead
+     * would re-read the roster, and a composition file edited since the parent
+     * started would hand the child a DIFFERENT generation than the one its
+     * parent's history was produced under (and a preset deleted since would fail
+     * the child outright while its parent keeps running).
+     *
+     * Synchronous, and with no composition failure mode of its own — it reads no
+     * roster, mounts nothing, and touches no file — which is what lets a child
+     * creation window use it: the two in-process subagent drivers compose their
+     * children inside a synchronous `setup`. It still rejects a caller error, as
+     * the `@throws` below record.
+     *
+     * A parent that joined no preset — a rosterless deployment — yields no join
+     * and no error: there, the model-facing rows sit in the host composition and
+     * the child already sees them through the global layer.
+     * @param agentCtx - the joining agent's scope context.
+     * @param parentCtx - the scope context of the agent whose composition to join.
+     * @returns the preset id joined, or undefined when the parent joined none.
+     * @throws when `agentCtx` carries no scope, or has already joined a preset.
+     */
+    composeFrom(agentCtx: Context, parentCtx: Context): string | undefined;
+    /**
+     * The preset one live agent runs on.
+     *
+     * Read from the live scope chain rather than from the session, so it answers
+     * for an agent whose session has not recorded a preset yet — a child agent
+     * whose durable header is being built from its parent's composition.
+     * @param agentCtx - the agent's scope context.
+     * @returns the preset id, or undefined when the agent joined none.
+     */
+    composedPreset(agentCtx: Context): string | undefined;
+    /**
+     * The roots this roster scans, which is not `config.roots`: it is every
+     * configured root in order, then the harness-home user root unless
+     * `includeUserRoot` is false. Read this — not the config field — to answer
+     * whether a roster is composed at all, so one derivation decides it.
+     */
+    get roots(): readonly PresetRoot[];
+    /** Whether this deployment has a root locally authored presets go to. */
+    get authorable(): boolean;
+    /**
+     * Read one preset's composition text.
+     * @param id - the preset id.
+     * @returns the composition exactly as stored.
+     * @throws when no configured root supplies that id.
+     */
+    read(id: string): Promise<string>;
+    /**
+     * Create a locally authored preset by copying an existing one whole.
+     *
+     * Copy is the only authoring write. Composition text never crosses this
+     * seam: the source is named by id and its directory is copied as it stands,
+     * so the copy is exactly as loadable as its source and authoring grants no
+     * capability the roster did not already carry. The copy is NOT mounted to
+     * validate — a source that mounts today yields a copy that mounts today.
+     * @param from - the preset the copy starts from; shipped presets are the
+     * primary source, so any trust is accepted.
+     * @param id - the new preset's id, which becomes its directory name.
+     * @param name - display name for the copy; absent falls back to the id.
+     * @throws when the source is unknown, the id is unusable or already taken,
+     * or the deployment configures no writable root.
+     */
+    copy(from: string, id: string, name?: string): Promise<void>;
+    /**
+     * Delete a locally authored preset.
+     * @param id - the preset id.
+     * @throws when the preset is unknown or ships with the deployment.
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * One agent's instance of a service its preset mounted.
+     *
+     * A preset publishes services behind `isolate` realms, which are invisible
+     * outside the group that declares them — including to the host. This is how a
+     * caller holding the agent reads one anyway: a request that is ABOUT a
+     * session but arrives from outside it, which is every browser RPC.
+     *
+     * Read addressing only. A host row that `inject`s a service cannot use this,
+     * because injection resolves before any session exists and has no agent to
+     * key by; such a service belongs on the host plane instead.
+     * @param agent - the agent whose composition to look inside.
+     * @param name - the service name as the preset's rows resolve it.
+     * @returns the agent's instance, or undefined when its preset mounts none.
+     */
+    serviceFor<K extends string & keyof Context>(agent: {
+        ctx: Context;
+    }, name: K): Context[K] | undefined;
+    /**
+     * Re-link one agent to a different preset's standing composition.
+     *
+     * Only valid while the agent has produced nothing: swapping tools mid
+     * conversation would leave logged tool calls the new composition cannot
+     * make. The CALLER owns that check — this method does not read session
+     * history.
+     *
+     * The swap is a parent re-link, not an unmount: standing mounts are shared
+     * and permanent, so the old composition stays for its other agents and the
+     * new one is ensured BEFORE the link moves. An unknown or unusable preset
+     * therefore throws with the agent exactly as it was — there is no torn-down
+     * state to restore. The re-link runs through the binding this roster kept
+     * from the agent's mount — nomix-scope's only re-link authority. An agent
+     * that never composed one has nothing to re-link: the switch is then the
+     * agent's first bind, exactly a mount.
+     * @param agentCtx - the agent's scope context.
+     * @param id - the preset to compose the agent from instead.
+     * @returns the preset now installed.
+     * @throws when the preset is unknown or its composition is unusable.
+     */
+    recompose(agentCtx: Context, id: string): Promise<AgentPreset>;
+    /**
+     * The standing scope key of one preset, for a host reader with no agent.
+     *
+     * A cold transcript read resolves tool presenters against the composition
+     * the session recorded, and the standing mount makes that possible without
+     * resuming anything: ensuring the mount composes plugins but starts no
+     * agent, no session, and no turn.
+     * @param id - the preset id, or `undefined` for {@link defaultId}.
+     * @returns the standing scope key readers pass as a registry view scope.
+     * @throws when the preset is unknown or its composition is unusable.
+     */
+    standingKeyFor(id?: string): Promise<ScopeKey>;
+    /** Resolve (or create, single-flight) the standing mount of one preset. */
+    private ensureStanding;
+}
+export default AgentPresets;
+//# sourceMappingURL=index.d.ts.map