@elinpf/dsh-ops-access 0.1.0

package/lib/index.js

@@ -0,0 +1,1008 @@
+/**
+ * Ops access capability seam.
+ *
+ * Owns the YAML credential registry file (default `~/.dsh-ops/access.yaml`)
+ * and exposes `ctx.opsAccess`: a generic `resolve(kind, name)` / `list()`
+ * entry plus a `register(provider)` surface for provider plugins. Providers
+ * (one per credential kind) supply the zod schema for their entry shape and
+ * an optional `process` step (e.g. `~` expansion); secret material never
+ * leaves the filesystem — profiles carry only paths and connection params.
+ *
+ * The registry file is re-read, re-parsed, and re-validated on every call —
+ * edits take effect immediately, nothing is cached.
+ *
+ * Also registers the `register_access` tool: the agent's self-service path
+ * for writing the ro tier of a profile (rw tiers stay human-managed via the
+ * admin HTTP routes below).
+ *
+ * Registry format:
+ *
+ * ```yaml
+ * version: 1
+ * k8s:
+ *   prod:
+ *     description: 生产集群
+ *     environment: prod
+ *     ro:
+ *       kubeconfig: ~/.dsh-ops/credentials/k8s/prod/ro/kubeconfig
+ *     rw:
+ *       kubeconfig: ~/.dsh-ops/credentials/k8s/prod/rw/kubeconfig
+ * ```
+ *
+ * Every top-level section besides `version` is a kind; keys inside a section
+ * are profile names. `description` and `environment` are envelope fields
+ * on the entry; `ro` and `rw` are tier sub-objects holding the
+ * provider-specific fields for that tier.
+ *
+ * @module @elinpf/dsh-ops-access
+ */
+import { readFile, writeFile, mkdir, rm, rmdir } from 'node:fs/promises';
+import os from 'node:os';
+import z from '@deepseek-ai/schemastery';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { z as zod } from 'zod';
+import { createUserMessage, freezeMessage } from '@deepseek-ai/dsh-llm';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { formatAccessMention, parseAccessReferenceText } from './mention.js';
+// ── Plugin identity ───────────────────────────────────────────────────────────
+export const name = 'ops-access';
+export const inject = ['tools'];
+export const Config = z.object({
+    registryFile: z.string().default('~/.dsh-ops/access.yaml'),
+    credentialsDir: z.string().default('~/.dsh-ops/credentials'),
+});
+/** Read a persisted probe result off a raw tier object (durable boundary — sanitize). */
+function probeOf(tierRaw) {
+    if (!isPlainObject(tierRaw))
+        return undefined;
+    const p = tierRaw.probe;
+    if (!isPlainObject(p))
+        return undefined;
+    const probe = p;
+    if (probe.status !== 'verified' && probe.status !== 'mismatch' && probe.status !== 'unverifiable')
+        return undefined;
+    if (typeof probe.probedAt !== 'string')
+        return undefined;
+    const out = { status: probe.status, probedAt: probe.probedAt };
+    if (typeof probe.detail === 'string')
+        out.detail = probe.detail;
+    return out;
+}
+// ── Provider registration helper ─────────────────────────────────────────────
+/**
+ * Register a provider into the seam from a provider plugin's `apply()`. The
+ * preset mounts sibling rows concurrently, so a static inject on 'opsAccess'
+ * can deadlock the loader against the definition row — this defers through
+ * `ctx.inject` and ties the registration to the plugin's effect lifecycle.
+ * Provider packages should call this and nothing else.
+ */
+export function registerAccessProvider(ctx, provider) {
+    ctx.inject(['opsAccess'], (pctx) => {
+        pctx.effect(() => pctx.opsAccess.register(provider));
+    });
+}
+/**
+ * Register an access broker (the gate) from the gate plugin's `apply()`. Same
+ * deferred-mount discipline as {@link registerAccessProvider}: the preset
+ * mounts sibling rows concurrently, so a static inject on 'opsAccess' can
+ * deadlock the loader against the definition row — this defers through
+ * `ctx.inject` and ties the registration to the plugin's effect lifecycle.
+ */
+export function registerAccessBroker(ctx, broker) {
+    ctx.inject(['opsAccess'], (pctx) => {
+        pctx.effect(() => pctx.opsAccess.registerBroker(broker));
+    });
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+/** Expand a leading `~` (or `~/`) to the user's home directory. */
+export function expandHome(p) {
+    const home = process.env.HOME ?? os.homedir();
+    if (p === '~')
+        return home;
+    if (p.startsWith('~/'))
+        return home + p.slice(1);
+    return p;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Read and parse the registry file. Returns null when the file does not
+ * exist so callers can pick their own discipline (list → empty, resolve →
+ * error). Never includes raw file text in errors.
+ */
+async function loadRegistry(file) {
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return null;
+        throw new Error(`ops-access: failed to read registry file ${file}: ${err?.message ?? err}`);
+    }
+    let doc;
+    try {
+        doc = parseYaml(text);
+    }
+    catch (err) {
+        // First line only — the yaml library appends a source snippet to its
+        // messages, and raw registry text must not leak into errors.
+        const summary = String(err?.message ?? err).split('\n')[0];
+        throw new Error(`ops-access: failed to parse registry file ${file}: ${summary}`);
+    }
+    // An empty file parses to null — treat it as an empty registry.
+    if (doc == null)
+        return {};
+    if (!isPlainObject(doc)) {
+        throw new Error(`ops-access: registry file ${file} must contain a top-level mapping`);
+    }
+    const registry = {};
+    for (const [kind, section] of Object.entries(doc)) {
+        if (kind === 'version')
+            continue;
+        if (!isPlainObject(section)) {
+            throw new Error(`ops-access: section "${kind}" in registry file ${file} must be a mapping of profile names`);
+        }
+        registry[kind] = section;
+    }
+    return registry;
+}
+/**
+ * Validate one tier sub-object against the provider schema and build the
+ * profile. `raw` carries only the provider fields; the envelope
+ * (description/environment) lives on the parent entry and is passed separately.
+ */
+function buildProfile(provider, kind, profileName, tier, raw, file, parentEntry) {
+    if (!isPlainObject(raw)) {
+        throw new Error(`ops-access: entry ${kind}.${profileName} in registry file ${file} must be a mapping`);
+    }
+    const result = provider.schema.safeParse(raw);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+            .join('; ');
+        throw new Error(`ops-access: invalid entry ${kind}.${profileName} in registry file ${file}: ${issues}`);
+    }
+    const fields = provider.process
+        ? provider.process(result.data, profileName)
+        : result.data;
+    const profile = { kind, name: profileName, tier, fields };
+    const env = parentEntry ?? {};
+    if (typeof env.name === 'string')
+        profile.displayName = env.name;
+    if (typeof env.description === 'string')
+        profile.description = env.description;
+    if (typeof env.environment === 'string')
+        profile.environment = env.environment;
+    return profile;
+}
+/** Serialize a registry back to its YAML file with the version header. */
+async function saveRegistry(file, registry) {
+    const doc = { version: 1 };
+    for (const [kind, section] of Object.entries(registry)) {
+        doc[kind] = section;
+    }
+    await writeFile(file, stringifyYaml(doc), 'utf8');
+}
+/** Read the full HTTP request body as a string. */
+function readRequestBody(req) {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        req.on('data', (chunk) => { if (chunk !== undefined)
+            data += chunk; });
+        req.on('end', () => resolve(data));
+        req.on('error', reject);
+    });
+}
+/** Send a JSON error response — message from buildProfile carries zod paths, never field values. */
+function sendJsonError(res, status, err) {
+    res.writeHead(status, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ ok: false, error: String(err?.message ?? err) }));
+}
+/** Build an EntryEnvelope from raw entry data, taking each envelope field from the first source that has it. */
+function buildEnvelope(sources) {
+    const envelope = {};
+    for (const source of sources) {
+        if (!isPlainObject(source))
+            continue;
+        if (envelope.name === undefined && typeof source.name === 'string')
+            envelope.name = source.name;
+        if (envelope.description === undefined && typeof source.description === 'string')
+            envelope.description = source.description;
+        if (envelope.environment === undefined && typeof source.environment === 'string')
+            envelope.environment = source.environment;
+    }
+    return envelope;
+}
+/** Split "kind/name" on the FIRST slash — profile names may contain '@' etc. */
+function parseProfile(raw) {
+    if (typeof raw !== 'string')
+        return undefined;
+    const slash = raw.indexOf('/');
+    if (slash <= 0 || slash === raw.length - 1)
+        return undefined;
+    return { kind: raw.slice(0, slash), profileName: raw.slice(slash + 1) };
+}
+/**
+ * Write credential CONTENT to managed files under
+ * `<credentialsDir>/<kind>/<name>/<tier>/<field>` and record the resulting
+ * paths in entryFields. Shared by the admin POST route (the human writer)
+ * and the register_access tool (the agent writer). Only fields the provider
+ * declared in fileFields may be content-written, and field names are
+ * charset-guarded against path escape. Files are written 0600 — they carry
+ * secret material.
+ */
+/**
+ * The profile name is the entry's stable id: it lands in credential file
+ * paths (credentials/<kind>/<name>/<tier>/<field>) and in mention syntax
+ * (@[kind/name]), so reject anything path- or syntax-hostile. Writer paths
+ * call this BEFORE any file IO — a bad name must not leave orphan files.
+ */
+function assertValidProfileName(profileName) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._@-]*$/.test(profileName)) {
+        throw new Error(`ops-access: invalid profile name "${profileName}" — must start with a letter or digit and contain only letters, digits, '.', '_', '-', '@'`);
+    }
+}
+async function writeContentFiles(credentialsDir, kind, profileName, tier, fileFields, contentFiles, entryFields, provider) {
+    const allowed = new Set(fileFields);
+    const written = [];
+    for (const [fieldName, content] of Object.entries(contentFiles)) {
+        // Empty content means "untouched" (the edit form leaves saved file
+        // fields blank) — never clobber a stored credential with it.
+        if (typeof content !== 'string' || content.trim() === '')
+            continue;
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(fieldName)) {
+            throw new Error(`ops-access: invalid file field name "${fieldName}"`);
+        }
+        if (!allowed.has(fieldName)) {
+            throw new Error(`ops-access: "${fieldName}" is not a declared file field for kind "${kind}" (declared: ${fileFields.join(', ') || '(none)'})`);
+        }
+        // Provider-declared write-time normalization runs FIRST — validator
+        // and disk both see the normalized bytes.
+        const normalized = provider?.normalizeTrailingNewline ? content.replace(/[\r\n]+$/, '') + '\n' : content;
+        // Save-time content validation (provider hook, possibly async — ssh
+        // runs ssh-keygen): reject corrupt pastes BEFORE anything lands on disk.
+        const problem = await provider?.validateContent?.(fieldName, normalized);
+        if (problem) {
+            throw new Error(`ops-access: invalid content for ${kind}/${profileName} ${tier} ${fieldName}: ${problem}`);
+        }
+        const dir = credentialsDir + '/' + kind + '/' + profileName + '/' + tier;
+        await mkdir(dir, { recursive: true });
+        const filePath = dir + '/' + fieldName;
+        await writeFile(filePath, normalized, { encoding: 'utf8', mode: 0o600 });
+        written.push(filePath);
+        entryFields[fieldName] = filePath;
+    }
+    return written;
+}
+/**
+ * Roll back files writeContentFiles just wrote when the accompanying
+ * writeEntry fails — a rejected registration must not leave orphan
+ * credential files on disk. Also removes the directories this write created
+ * (rmdir refuses non-empty ones, so pre-existing content is never touched).
+ */
+async function rollbackContentFiles(credentialsDir, kind, profileName, tier, written) {
+    for (const filePath of written)
+        await rm(filePath, { force: true });
+    for (const dir of [
+        credentialsDir + '/' + kind + '/' + profileName + '/' + tier,
+        credentialsDir + '/' + kind + '/' + profileName,
+        credentialsDir + '/' + kind,
+    ]) {
+        try {
+            await rmdir(dir);
+        }
+        catch { /* non-empty or already gone — leave it */ }
+    }
+}
+// ── Mention injection (agent/pre-step) ──────────────────────────────────────
+/**
+ * Render the envelope context for referenced profiles. Envelope fields only —
+ * fields (paths, connection params) never cross into model context, keeping
+ * the structural secrecy discipline. Unknown profiles degrade to a note, not
+ * an error: a stale mention must not block the step.
+ *
+ * Reads through `listAll()`, not `resolve()`: mention rendering is metadata
+ * display, not credential issuance — it must never consult the broker, or an
+ * approval-required profile (ssh) would render as "not found" simply because
+ * the session holds no grant. listAll (not list) so rw-only entries render
+ * too — they exist in the registry, the agent just cannot read them yet.
+ */
+async function renderAccessReferences(handle, references) {
+    // A listAll failure (unreadable/corrupt registry file) degrades the mention
+    // render to name-only lines — the registry being temporarily unreadable must
+    // not break prompt assembly for the whole turn.
+    const entries = await handle.listAll().catch(() => []);
+    const seen = new Set();
+    const lines = [];
+    for (const ref of references) {
+        const key = `${ref.kind}/${ref.name}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const entry = entries.find((e) => e.kind === ref.kind && e.name === ref.name);
+        if (!entry) {
+            lines.push(`- ${key} — (not found in the access registry; run list_access to see available profiles)`);
+            continue;
+        }
+        const env = entry.envelope.environment ? ` [${entry.envelope.environment}]` : '';
+        const label = entry.envelope.name ? ` (${entry.envelope.name})` : '';
+        const desc = entry.envelope.description ? ` — ${entry.envelope.description}` : '';
+        const tierNote = !entry.tiers.ro.ok && entry.tiers.rw.ok
+            ? ' (no ro tier registered yet — derivable from rw via the register_access tool)'
+            : '';
+        lines.push(`- ${key}${label}${env}${desc}${tierNote}`);
+    }
+    return `<referenced-access>\nThe user explicitly referenced these access profiles (use them with the matching tools):\n${lines.join('\n')}\n</referenced-access>`;
+}
+// ── Plugin apply ─────────────────────────────────────────────────────────────
+export function apply(ctx, config) {
+    const registryFile = expandHome(config.registryFile);
+    const credentialsDir = expandHome(config.credentialsDir);
+    const providers = new Map();
+    // At most one broker is active; a later registration replaces an earlier one.
+    // The replaced broker's disposer is folded into the replacement's, so each
+    // registration's effect cleanup runs exactly once even under replacement or
+    // HMR unload — honoring the cordis effect-lifecycle discipline.
+    let broker;
+    let clearBroker = () => { };
+    const handle = {
+        register(provider) {
+            if (providers.has(provider.kind)) {
+                throw new Error(`ops-access: provider for kind "${provider.kind}" is already registered`);
+            }
+            providers.set(provider.kind, provider);
+            return () => { providers.delete(provider.kind); };
+        },
+        registerBroker(next) {
+            // Replace the active broker: fold the previous disposer into this one so
+            // the prior registration's cleanup still runs (once) under replacement
+            // or HMR unload, and the guard prevents a stale disposer clobbering a
+            // later broker.
+            const prev = clearBroker;
+            broker = next;
+            let active = true;
+            const dispose = () => {
+                if (!active)
+                    return;
+                active = false;
+                if (broker === next) {
+                    broker = undefined;
+                    clearBroker = () => { };
+                }
+                prev();
+            };
+            clearBroker = dispose;
+            return dispose;
+        },
+        async canResolve(kind, profileName, tier) {
+            const provider = providers.get(kind);
+            if (!provider)
+                return { ok: false };
+            // Load + locate the entry in its own try/catch: a missing or unparseable
+            // file is a structural "not resolvable" with no validation reason — the
+            // admin does not need a zod message to fix a file that isn't there.
+            let raw;
+            let parentEntry;
+            try {
+                const registry = await loadRegistry(registryFile);
+                if (registry === null)
+                    return { ok: false };
+                const entry = registry[kind]?.[profileName];
+                if (!isPlainObject(entry))
+                    return { ok: false };
+                parentEntry = entry;
+                raw = parentEntry[tier];
+            }
+            catch {
+                return { ok: false };
+            }
+            if (!isPlainObject(raw))
+                return { ok: false };
+            // Run the same buildProfile validation resolve would run — a precheck
+            // shallower than the real issuance approves grants that cannot be
+            // fulfilled. The profile itself is discarded: existence, not fields.
+            // A validation failure surfaces the reason (zod issue paths + messages,
+            // never raw field values) so the admin UI can show it.
+            try {
+                buildProfile(provider, kind, profileName, tier, raw, registryFile, parentEntry);
+                return { ok: true };
+            }
+            catch (err) {
+                return { ok: false, error: String(err?.message ?? err) };
+            }
+        },
+        async resolve(kind, profileName, agent) {
+            const provider = providers.get(kind);
+            if (!provider) {
+                const registered = [...providers.keys()].sort();
+                throw new Error(`ops-access: unknown kind "${kind}" (no provider registered; registered kinds: ${registered.join(', ') || '(none)'})`);
+            }
+            // Once a broker is registered it is consulted on EVERY resolve —
+            // including calls without an agent. The no-agent ruling (fail closed to
+            // ro, or deny outright) is policy, and policy lives in the broker, not
+            // here. Without a broker, rw is never issued at all.
+            let tier = 'ro';
+            if (broker) {
+                const decision = broker(kind, profileName, agent);
+                if (typeof decision === 'object') {
+                    throw new Error(`ops-access: access denied for ${kind}/${profileName}: ${decision.deny}`);
+                }
+                if (decision === 'rw')
+                    tier = 'rw';
+            }
+            const registry = await loadRegistry(registryFile);
+            if (registry === null) {
+                throw new Error(`ops-access: registry file not found: ${registryFile}`);
+            }
+            const section = registry[kind];
+            const entry = section?.[profileName];
+            if (!isPlainObject(entry)) {
+                const available = Object.keys(section ?? {}).sort();
+                const hint = tier === 'rw' ? ' — a grant was approved but no rw credential is registered; ask the operator to add it via the admin UI' : '';
+                throw new Error(`ops-access: no profile "${profileName}" for kind "${kind}" in registry file ${registryFile} (available: ${available.join(', ') || '(none)'})${hint}`);
+            }
+            const tierData = entry[tier];
+            if (!isPlainObject(tierData)) {
+                // On the rw tier the grant was already approved — say so, so the agent
+                // reports "no rw credential registered" to the operator instead of
+                // re-requesting a grant that can never be fulfilled. On the ro tier
+                // with rw present, point at the self-service derivation path.
+                const hint = tier === 'rw'
+                    ? ' — a grant was approved but no rw credential is registered; ask the operator to add it via the admin UI'
+                    : isPlainObject(entry.rw)
+                        ? ' — the rw tier is registered; derive a read-only credential from it (list_access help: true has the recipe) and register it via the register_access tool'
+                        : '';
+                throw new Error(`ops-access: no ${tier} tier for profile "${profileName}" (kind "${kind}") in registry file ${registryFile}${hint}`);
+            }
+            return buildProfile(provider, kind, profileName, tier, tierData, registryFile, entry);
+        },
+        async list() {
+            const registry = await loadRegistry(registryFile);
+            if (registry === null)
+                return [];
+            const profiles = [];
+            for (const [kind, section] of Object.entries(registry)) {
+                // Sections whose kind has no registered provider are skipped —
+                // an unrecognized kind must not fail the whole listing.
+                const provider = providers.get(kind);
+                if (!provider)
+                    continue;
+                for (const [profileName, entry] of Object.entries(section)) {
+                    // list() surfaces the agent-readable ro tier only.
+                    if (!isPlainObject(entry))
+                        continue;
+                    const roData = entry.ro;
+                    if (!isPlainObject(roData))
+                        continue;
+                    profiles.push(buildProfile(provider, kind, profileName, 'ro', roData, registryFile, entry));
+                }
+            }
+            return profiles;
+        },
+        help() {
+            const lines = [
+                'Ops access registry — how to manage credentials',
+                '',
+                `File: ${registryFile}`,
+                'Re-read, re-parsed, and re-validated on EVERY call — edit it with the fs tools and the change takes effect immediately, no restart.',
+                '',
+                'Format:',
+                '  version: 1',
+                '  <kind>:',
+                '    <profile-id>:                            # stable id: letters/digits plus . _ - @; used in paths, mentions, grants',
+                '      name: display label, freely editable   # optional, UI-facing only',
+                '      description: what this profile is for   # optional, shown by list_access',
+                '      environment: prod | staging | ...        # optional; the future audit gate reads this',
+                '      ro:                                      # ro tier fields (agent-readable default)',
+                '        <kind-specific fields, see below>',
+                '      rw:                                      # rw tier fields (grant-gated)',
+                '        probe: {...}                            # auto-managed capability check (ticket 10): status/detail/probedAt, written at save time — do not edit',
+                '',
+                'Registered kinds and their entry fields:',
+            ];
+            const kinds = [...providers.values()].sort((a, b) => a.kind.localeCompare(b.kind));
+            if (kinds.length === 0) {
+                lines.push('- (none registered)');
+            }
+            for (const p of kinds) {
+                lines.push(`- ${p.kind}: ${p.fieldsDoc ?? '(no field docs provided by this provider)'}`);
+                if (p.derivationDoc)
+                    lines.push(`  derive ro: ${p.derivationDoc}`);
+            }
+            lines.push('');
+            lines.push('Agents register ro tiers with the register_access tool — rw tiers stay human-managed via the admin UI.');
+            lines.push('Secrets never go inline — fields carry file paths and connection params only, so logs and model context never contain secret material.');
+            return lines.join('\n');
+        },
+        async writeEntry(kind, profileName, tier, fields, envelope) {
+            const provider = providers.get(kind);
+            if (!provider) {
+                const registered = [...providers.keys()].sort();
+                throw new Error(`ops-access: unknown kind "${kind}" (no provider registered; registered kinds: ${registered.join(', ') || '(none)'})`);
+            }
+            assertValidProfileName(profileName);
+            // The tier sub-object carries only provider fields; the envelope
+            // (name/description/environment) lives on the parent entry.
+            const tierData = { ...fields };
+            // Read → merge → validate → write back. A missing file starts from an
+            // empty registry; an unparseable file throws (we will not overwrite a
+            // file we cannot read).
+            let registry = {};
+            const loaded = await loadRegistry(registryFile);
+            if (loaded !== null)
+                registry = loaded;
+            if (!registry[kind])
+                registry[kind] = {};
+            if (!isPlainObject(registry[kind][profileName]))
+                registry[kind][profileName] = {};
+            const entry = registry[kind][profileName];
+            entry[tier] = tierData;
+            // Envelope discipline: omitted = preserve, empty string = delete, else set.
+            // The admin UI always sends all three so the operator can clear them.
+            if (envelope?.name !== undefined) {
+                if (envelope.name === '')
+                    delete entry.name;
+                else
+                    entry.name = envelope.name;
+            }
+            if (envelope?.description !== undefined) {
+                if (envelope.description === '')
+                    delete entry.description;
+                else
+                    entry.description = envelope.description;
+            }
+            if (envelope?.environment !== undefined) {
+                if (envelope.environment === '')
+                    delete entry.environment;
+                else
+                    entry.environment = envelope.environment;
+            }
+            // Validate via buildProfile BEFORE writing — a schema failure must not
+            // touch the file. buildProfile throws with zod issue paths + messages,
+            // never raw field values. (The in-memory merged entry is what we
+            // validate, matching the spec's read→merge→validate→write sequence.)
+            const writtenProfile = buildProfile(provider, kind, profileName, tier, tierData, registryFile, entry);
+            // Capability probe (ticket 10): verify claims against reality at save
+            // time — the credential files are already on disk (the caller writes
+            // them first). A probe failure degrades to 'unverifiable', never a
+            // write rejection.
+            if (provider.probe) {
+                const probed = await provider.probe(writtenProfile.fields, tier)
+                    .catch((err) => ({
+                    status: 'unverifiable',
+                    detail: err instanceof Error ? err.message.split('\n')[0] : String(err),
+                }));
+                tierData.probe = { ...probed, probedAt: new Date().toISOString() };
+            }
+            await saveRegistry(registryFile, registry);
+        },
+        async deleteEntry(kind, profileName, tier) {
+            const registry = await loadRegistry(registryFile);
+            if (registry === null)
+                return false;
+            const section = registry[kind];
+            if (!section || !(profileName in section))
+                return false;
+            const entry = section[profileName];
+            if (!isPlainObject(entry))
+                return false;
+            // Remove the tier sub-object and its managed credential files.
+            delete entry[tier];
+            const provider = providers.get(kind);
+            if (provider?.fileFields && provider.fileFields.length > 0) {
+                await rm(credentialsDir + '/' + kind + '/' + profileName + '/' + tier, { recursive: true, force: true });
+            }
+            // If neither tier remains, remove the whole entry, its credential
+            // directory, and drop empty sections.
+            const remaining = ['ro', 'rw'].filter((t) => entry[t] !== undefined);
+            if (remaining.length === 0) {
+                delete section[profileName];
+                if (Object.keys(section).length === 0)
+                    delete registry[kind];
+                if (provider?.fileFields && provider.fileFields.length > 0) {
+                    await rm(credentialsDir + '/' + kind + '/' + profileName, { recursive: true, force: true });
+                }
+            }
+            await saveRegistry(registryFile, registry);
+            return true;
+        },
+        async listAll() {
+            // Load the single registry for enumeration. A parse error degrades to
+            // an empty list — canResolve reports the failure per tier.
+            let registry = {};
+            try {
+                const r = await loadRegistry(registryFile);
+                if (r)
+                    registry = r;
+            }
+            catch { /* canResolve reports the failure */ }
+            const result = [];
+            for (const kind of Object.keys(registry).sort()) {
+                if (!providers.has(kind))
+                    continue;
+                const section = registry[kind];
+                if (!section)
+                    continue;
+                for (const name of Object.keys(section).sort()) {
+                    const entry = section[name];
+                    if (!isPlainObject(entry))
+                        continue;
+                    const envelope = buildEnvelope([entry]);
+                    const roStatus = await handle.canResolve(kind, name, 'ro');
+                    const rwStatus = await handle.canResolve(kind, name, 'rw');
+                    const rawEntry = entry;
+                    const roProbe = probeOf(rawEntry.ro);
+                    if (roProbe !== undefined)
+                        roStatus.probe = roProbe;
+                    const rwProbe = probeOf(rawEntry.rw);
+                    if (rwProbe !== undefined)
+                        rwStatus.probe = rwProbe;
+                    result.push({ kind, name, envelope, tiers: { ro: roStatus, rw: rwStatus } });
+                }
+            }
+            return result;
+        },
+        listKinds() {
+            return [...providers.values()]
+                .sort((a, b) => a.kind.localeCompare(b.kind))
+                .map((p) => {
+                const descriptor = { kind: p.kind, jsonSchema: zod.toJSONSchema(p.schema), ...(p.fileFields ? { fileFields: p.fileFields } : {}) };
+                if (p.fieldsDoc !== undefined)
+                    descriptor.fieldsDoc = p.fieldsDoc;
+                return descriptor;
+            });
+        },
+        async getEntry(kind, profileName, tier) {
+            const provider = providers.get(kind);
+            if (!provider)
+                return null;
+            let registry;
+            try {
+                registry = await loadRegistry(registryFile);
+            }
+            catch {
+                // Registry file unreadable/corrupt → the entry is unknowable; getEntry
+                // reports null (not found) rather than failing the caller's whole flow.
+                return null;
+            }
+            if (registry === null)
+                return null;
+            const entry = registry[kind]?.[profileName];
+            if (!isPlainObject(entry))
+                return null;
+            const parent = entry;
+            const raw = parent[tier];
+            if (!isPlainObject(raw))
+                return null;
+            // Return the tier's NON-file fields plus the parent's envelope. File
+            // fields (credential content) are write-only after save: content is
+            // never read back — not even the managed path — only the set status
+            // rides along so the UI can render "已保存，粘贴新内容以覆盖". This
+            // keeps stored credentials unreachable for anyone (or anything) that
+            // can merely reach the admin routes.
+            const { name: displayName, description, environment } = parent;
+            const fields = { ...raw };
+            const fileFields = {};
+            for (const ff of provider.fileFields ?? []) {
+                const stored = fields[ff];
+                fileFields[ff] = typeof stored === 'string' && stored.length > 0;
+                delete fields[ff];
+            }
+            const result = { fields, fileFields };
+            if (typeof displayName === 'string')
+                result.displayName = displayName;
+            if (typeof description === 'string')
+                result.description = description;
+            if (typeof environment === 'string')
+                result.environment = environment;
+            return result;
+        },
+    };
+    ctx.provide('opsAccess', handle);
+    // ── register_access tool (agent-facing ro-tier writer) ────────────────────
+    // The agent's self-service registration path: it derives a read-only
+    // credential from the rw one (per-kind recipe in the provider's
+    // derivationDoc, surfaced by help()) and writes the ro tier here.
+    // Deliberately ungated — the ro tier is the agent's default operating
+    // level and the operator can overwrite it from the admin UI at any time;
+    // the rw tier stays human-only (no tool writes it). Tool calls sit in the
+    // session event log, so every registration is reconstructable.
+    ctx.effect(() => ctx.tools.register(defineTool({
+        name: 'register_access',
+        description: 'Register or overwrite the read-only (ro) credential tier of an access profile — typically a credential you derived from the rw tier (a read-only ServiceAccount token, a read-only cephx keyring, a dedicated SSH key). The rw tier is human-managed via the admin UI; this tool writes ro only. File fields (kubeconfig, conf, keyring, key) take full file CONTENT, stored to a managed path automatically; other fields are inline values. Run list_access with help: true for per-kind field docs and derivation recipes.',
+        parameters: {
+            profile: { type: 'string', required: true, description: '"kind/id", e.g. "k8s/prod". The entry is created when it does not exist yet.' },
+            fields: { type: 'object', additionalProperties: true, required: true, description: 'The ro tier field values for this kind. File fields take full content, not paths.' },
+            description: { type: 'string', description: 'Optional envelope description (empty string clears it).' },
+            environment: { type: 'string', description: 'Optional envelope environment label (empty string clears it).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    ok: { type: 'boolean', required: true },
+                    message: { type: 'string', required: true },
+                },
+            },
+            // Pure function of (args, value): same inputs, same text, no state touched.
+            render: (_args, value) => [{ type: 'text', text: value.message }],
+        },
+        async execute(args) {
+            const parsed = parseProfile(args.profile);
+            if (!parsed) {
+                return { ok: false, message: 'profile must be "kind/id", e.g. "k8s/prod"' };
+            }
+            const { kind, profileName } = parsed;
+            const kinds = handle.listKinds();
+            const descriptor = kinds.find((k) => k.kind === kind);
+            if (!descriptor) {
+                const registered = kinds.map((k) => k.kind).sort();
+                return { ok: false, message: `unknown kind "${kind}" (registered kinds: ${registered.join(', ') || '(none)'})` };
+            }
+            if (!isPlainObject(args.fields)) {
+                return { ok: false, message: 'fields must be an object of ro tier field values' };
+            }
+            // File fields take CONTENT from the agent; everything else is inline.
+            const entryFields = {};
+            const contentFiles = {};
+            const fileFieldSet = new Set(descriptor.fileFields ?? []);
+            for (const [fieldName, value] of Object.entries(args.fields)) {
+                if (fileFieldSet.has(fieldName) && typeof value === 'string')
+                    contentFiles[fieldName] = value;
+                else
+                    entryFields[fieldName] = value;
+            }
+            const envelope = {};
+            if (typeof args.description === 'string')
+                envelope.description = args.description;
+            if (typeof args.environment === 'string')
+                envelope.environment = args.environment;
+            // Reject a bad id BEFORE any file IO, and roll back written files when
+            // writeEntry fails — a rejected registration must not leave orphan
+            // credential files on disk.
+            try {
+                assertValidProfileName(profileName);
+            }
+            catch (err) {
+                return { ok: false, message: String(err?.message ?? err) };
+            }
+            let written = [];
+            try {
+                if (Object.keys(contentFiles).length > 0) {
+                    written = await writeContentFiles(credentialsDir, kind, profileName, 'ro', descriptor.fileFields ?? [], contentFiles, entryFields, providers.get(kind));
+                }
+                // writeEntry validates against the provider schema BEFORE touching
+                // the registry; its errors carry zod issue paths + messages, never
+                // raw field values.
+                await handle.writeEntry(kind, profileName, 'ro', entryFields, Object.keys(envelope).length > 0 ? envelope : undefined);
+            }
+            catch (err) {
+                await rollbackContentFiles(credentialsDir, kind, profileName, 'ro', written);
+                return { ok: false, message: `registration failed: ${String(err?.message ?? err)}` };
+            }
+            return { ok: true, message: `Registered the ro tier of ${kind}/${profileName}. Verify it with a read command before relying on it.` };
+        },
+    })));
+    // ── Mention candidate route (GET /ops-access/list) ────────────────────────
+    // The browser's @ menu reads this. Preset-plane registration of a host
+    // webServer route: reaching the preset-realm opsAccess FROM the host plane
+    // would need stateful dsh internals (serviceForAgent), which dual-instance
+    // under an external package's node_modules — so the route lives here, next
+    // to the data. Envelope fields + ready-made mentions only; fields never
+    // cross. Mounted once per process with the standing preset mount.
+    ctx.inject(['webServer'], (wctx) => {
+        wctx.effect(() => wctx.webServer.register({
+            kind: 'exact',
+            path: '/ops-access/list',
+            handler: async (req, res) => {
+                const url = new URL(req.url, 'http://localhost');
+                const query = url.searchParams.get('query') ?? '';
+                const needle = query.toLocaleLowerCase();
+                // listAll, not list: the picker must also show entries that carry
+                // only an rw tier (operator-registered, ro not yet derived) — hiding
+                // them would make the rw→ro derivation flow unreachable from the UI.
+                // Tier readiness flags ride along so the picker can badge them;
+                // fields never cross (listAll is envelope + status only).
+                const entries = await handle.listAll();
+                // Probe verdicts ride along for ok tiers (ticket 10 review fix: the
+                // @ menu is one of the three display surfaces the ticket names).
+                const probeOf2 = (tiers) => {
+                    const out = {};
+                    if (tiers.ro.ok && tiers.ro.probe !== undefined)
+                        out.ro = tiers.ro.probe.status;
+                    if (tiers.rw.ok && tiers.rw.probe !== undefined)
+                        out.rw = tiers.rw.probe.status;
+                    return Object.keys(out).length > 0 ? out : undefined;
+                };
+                const candidates = entries
+                    .filter((e) => needle === ''
+                    || `${e.kind}/${e.name}`.toLocaleLowerCase().includes(needle)
+                    || e.envelope.name?.toLocaleLowerCase().includes(needle) === true
+                    || e.envelope.description?.toLocaleLowerCase().includes(needle) === true)
+                    .map((e) => ({
+                    kind: e.kind,
+                    name: e.name,
+                    ...e.envelope.name === undefined ? {} : { displayName: e.envelope.name },
+                    ...e.envelope.description === undefined ? {} : { description: e.envelope.description },
+                    ...e.envelope.environment === undefined ? {} : { environment: e.envelope.environment },
+                    ro: e.tiers.ro.ok,
+                    rw: e.tiers.rw.ok,
+                    ...(() => { const p = probeOf2(e.tiers); return p === undefined ? {} : { probe: p }; })(),
+                    mention: formatAccessMention({ kind: e.kind, name: e.name }),
+                }));
+                res.writeHead(200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify(candidates));
+            },
+        }));
+        // ── Admin routes (GET /admin/list, GET /admin/kinds, POST+DELETE /admin/entry) ─
+        // The webServer matches by path only (no HTTP method), so the entry route
+        // dispatches on req.method. All responses and errors exclude field values
+        // — buildProfile errors carry zod issue paths + messages, never raw values.
+        wctx.effect(() => wctx.webServer.register({
+            kind: 'exact',
+            path: '/ops-access/admin/list',
+            handler: async (_req, res) => {
+                try {
+                    const entries = await handle.listAll();
+                    res.writeHead(200, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify(entries));
+                }
+                catch (err) {
+                    sendJsonError(res, 500, err);
+                }
+            },
+        }));
+        wctx.effect(() => wctx.webServer.register({
+            kind: 'exact',
+            path: '/ops-access/admin/kinds',
+            handler: async (_req, res) => {
+                try {
+                    const kinds = handle.listKinds();
+                    res.writeHead(200, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify(kinds));
+                }
+                catch (err) {
+                    sendJsonError(res, 500, err);
+                }
+            },
+        }));
+        wctx.effect(() => wctx.webServer.register({
+            kind: 'exact',
+            path: '/ops-access/admin/entry',
+            handler: async (req, res) => {
+                try {
+                    if (req.method === 'POST') {
+                        const body = await readRequestBody(req);
+                        let parsed;
+                        try {
+                            parsed = JSON.parse(body);
+                        }
+                        catch {
+                            sendJsonError(res, 400, new Error('request body must be valid JSON'));
+                            return;
+                        }
+                        const { kind, name, tier, fields, displayName, description, environment, contentFiles } = parsed;
+                        if (typeof kind !== 'string' || typeof name !== 'string' || (tier !== 'ro' && tier !== 'rw')) {
+                            sendJsonError(res, 400, new Error('kind (string), name (string), and tier ("ro"|"rw") are required'));
+                            return;
+                        }
+                        const entryFields = isPlainObject(fields) ? fields : {};
+                        // Content files: the UI sends credential file CONTENT (e.g. the full
+                        // kubeconfig YAML) instead of a path. Write each to a managed file
+                        // and store the path in entryFields. The id is validated BEFORE any
+                        // file IO, and written files are rolled back when writeEntry fails —
+                        // a rejected write must not leave orphan credential files on disk.
+                        const provider = providers.get(kind);
+                        assertValidProfileName(name);
+                        let writtenFiles = [];
+                        if (isPlainObject(contentFiles)) {
+                            writtenFiles = await writeContentFiles(credentialsDir, kind, name, tier, provider?.fileFields ?? [], contentFiles, entryFields, provider);
+                        }
+                        // Write-only-after-save preserve: file fields never come back
+                        // from the UI (getEntry withholds them), so an edit request
+                        // cannot carry them. Carry over the stored path for any declared
+                        // file field the request omits — otherwise the tier-replace
+                        // write would silently drop the credential.
+                        if (provider?.fileFields?.length) {
+                            const existing = await loadRegistry(registryFile);
+                            const existingEntry = existing?.[kind]?.[name];
+                            const existingTier = isPlainObject(existingEntry) ? existingEntry[tier] : undefined;
+                            if (isPlainObject(existingTier)) {
+                                for (const ff of provider.fileFields) {
+                                    if (entryFields[ff] === undefined && typeof existingTier[ff] === 'string') {
+                                        entryFields[ff] = existingTier[ff];
+                                    }
+                                }
+                            }
+                        }
+                        const envelope = buildEnvelope([{ name: displayName, description, environment }]);
+                        try {
+                            await handle.writeEntry(kind, name, tier, entryFields, Object.keys(envelope).length > 0 ? envelope : undefined);
+                        }
+                        catch (err) {
+                            await rollbackContentFiles(credentialsDir, kind, name, tier, writtenFiles);
+                            throw err;
+                        }
+                        res.writeHead(200, { 'content-type': 'application/json' });
+                        res.end(JSON.stringify({ ok: true }));
+                    }
+                    else if (req.method === 'GET') {
+                        const url = new URL(req.url, 'http://localhost');
+                        const kind = url.searchParams.get('kind');
+                        const name = url.searchParams.get('name');
+                        const tier = url.searchParams.get('tier');
+                        if (!kind || !name || (tier !== 'ro' && tier !== 'rw')) {
+                            sendJsonError(res, 400, new Error('kind, name, and tier ("ro"|"rw") query parameters are required'));
+                            return;
+                        }
+                        const entry = await handle.getEntry(kind, name, tier);
+                        if (entry === null) {
+                            res.writeHead(200, { 'content-type': 'application/json' });
+                            res.end(JSON.stringify(null));
+                        }
+                        else {
+                            res.writeHead(200, { 'content-type': 'application/json' });
+                            res.end(JSON.stringify(entry));
+                        }
+                    }
+                    else if (req.method === 'DELETE') {
+                        const url = new URL(req.url, 'http://localhost');
+                        const kind = url.searchParams.get('kind');
+                        const name = url.searchParams.get('name');
+                        const tier = url.searchParams.get('tier');
+                        if (!kind || !name || (tier !== 'ro' && tier !== 'rw')) {
+                            sendJsonError(res, 400, new Error('kind, name, and tier ("ro"|"rw") query parameters are required'));
+                            return;
+                        }
+                        const deleted = await handle.deleteEntry(kind, name, tier);
+                        res.writeHead(200, { 'content-type': 'application/json' });
+                        res.end(JSON.stringify(deleted ? { ok: true } : { ok: false, error: 'entry not found' }));
+                    }
+                    else {
+                        sendJsonError(res, 405, new Error('method not allowed'));
+                    }
+                }
+                catch (err) {
+                    // buildProfile errors carry zod issue paths + messages, never field values.
+                    sendJsonError(res, 400, err);
+                }
+            },
+        }));
+    });
+    ctx.on('agent/pre-step', async (payload, next) => {
+        const decision = await next();
+        if (decision.kind === 'reject')
+            return decision;
+        const messages = decision.messages;
+        const out = [];
+        let changed = false;
+        for (const message of messages) {
+            if (message.source?.kind !== 'user') {
+                out.push(message);
+                continue;
+            }
+            const references = [];
+            const content = message.content.map((block) => {
+                if (block.type !== 'text')
+                    return block;
+                const parsed = parseAccessReferenceText(block.text);
+                references.push(...parsed.references);
+                return parsed.references.length === 0 ? block : { ...block, text: parsed.text };
+            });
+            if (references.length === 0) {
+                out.push(message);
+                continue;
+            }
+            changed = true;
+            out.push(freezeMessage({ ...message, content }));
+            out.push(createUserMessage({
+                source: { kind: 'plugin', plugin: name, form: 'recall' },
+                content: [{ type: 'text', text: await renderAccessReferences(handle, references) }],
+            }));
+        }
+        return changed ? { kind: 'enter', messages: out } : decision;
+    }, { prepend: true });
+}