@qilin-agent/kylin-host-runner 0.0.0-stage → 3.1.3

package/lib/types/inspect-registry.d.ts

@@ -0,0 +1,78 @@
+/** Host registry for model-visible, read-only Cordis capability queries. */
+import { Service } from '@qilin-agent/kylin';
+import type { Context } from '@qilin-agent/kylin';
+import type { Agent } from '@qilin-agent/agent';
+import { type JsonValue } from '@qilin-agent/util-values';
+import type { CordisInspectPlatform, CordisInspectProviderManifest, CordisInspectProviderView, CordisInspectQueryResolution, CordisInspectRequestId, CordisInspectResolveAck } from './types.ts';
+/** Context supplied to a Host inspect query. */
+export interface HostCordisInspectQueryContext {
+    /** Tool-call cancellation. */
+    signal: AbortSignal;
+    /** Agent whose scoped runtime is being inspected. */
+    agent: Agent;
+}
+/** Local registration paired with its serializable manifest. */
+export interface HostCordisInspectProviderRegistration {
+    /** Provider and explicit method directory. */
+    manifest: CordisInspectProviderManifest;
+    /** Execute one declared method. */
+    query(method: string, input: JsonValue | undefined, context: HostCordisInspectQueryContext): Promise<JsonValue>;
+}
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        /** Host registry for Cordis inspect providers and Client manifest/query routing. */
+        cordisInspect: CordisInspectRegistryService;
+    }
+}
+/** Registry and cross-page router behind the two model-facing inspect tools. */
+export declare class CordisInspectRegistryService extends Service {
+    private readonly clientQueryTimeoutMs;
+    private readonly providers;
+    private readonly pending;
+    private clientManifest;
+    private nextRequest;
+    /**
+     * Register the process-global Host registry.
+     * @param ctx - owning Host context.
+     * @param clientQueryTimeoutMs - maximum wait for a valid Client response, in milliseconds.
+     */
+    constructor(ctx: Context, clientQueryTimeoutMs: number);
+    /**
+     * Register one Host provider.
+     * @param registration - manifest and local query handler.
+     * @returns idempotent disposer.
+     */
+    register(registration: HostCordisInspectProviderRegistration): () => void;
+    /**
+     * Replace the mirrored Client provider directory.
+     * @param providers - complete Client manifest snapshot.
+     */
+    syncClientManifest(providers: readonly CordisInspectProviderManifest[]): void;
+    /**
+     * Return the complete known Host and Client provider directory.
+     * @returns Host providers followed by the Client providers.
+     */
+    list(): CordisInspectProviderView[];
+    /**
+     * Execute one provider query on its owning platform.
+     * @param platform - Host or Client runtime.
+     * @param providerId - provider selected from {@link list}.
+     * @param methodName - declared method name.
+     * @param input - optional lossless JSON input.
+     * @param agent - requesting Agent and scope.
+     * @param signal - tool-call cancellation.
+     * @returns provider JSON data; Client queries fail fast when Gateway has no live Client
+     * and retain only the first observed failure diagnostic for timeout reporting.
+     */
+    query(platform: CordisInspectPlatform, providerId: string, methodName: string, input: JsonValue | undefined, agent: Agent, signal: AbortSignal): Promise<JsonValue>;
+    /**
+     * Accept the first valid Client response for a pending query.
+     * @param agent - Agent whose Session owns the query.
+     * @param requestId - Pending Client query identity.
+     * @param resolution - Client provider result or failure.
+     * @returns acknowledgement with accepted true only for a success that settles the query; only the first failure diagnostic is retained.
+     */
+    resolveClientQuery(agent: Agent, requestId: CordisInspectRequestId, resolution: CordisInspectQueryResolution): CordisInspectResolveAck;
+    private queryClient;
+}
+//# sourceMappingURL=inspect-registry.d.ts.map

package/lib/types/inspect-registry.js

@@ -0,0 +1,237 @@
+/** Host registry for model-visible, read-only Cordis capability queries. */
+import { Service } from '@qilin-agent/kylin';
+import { snapshotJsonValue } from '@qilin-agent/util-values';
+import { assertSupportedJsonSchema, validateJsonSchemaValue } from '@qilin-agent/tools';
+/** Registry and cross-page router behind the two model-facing inspect tools. */
+export class CordisInspectRegistryService extends Service {
+    clientQueryTimeoutMs;
+    providers = new Map();
+    pending = new Map();
+    clientManifest;
+    nextRequest = 1;
+    /**
+     * Register the process-global Host registry.
+     * @param ctx - owning Host context.
+     * @param clientQueryTimeoutMs - maximum wait for a valid Client response, in milliseconds.
+     */
+    constructor(ctx, clientQueryTimeoutMs) {
+        super(ctx, 'cordisInspect');
+        this.clientQueryTimeoutMs = clientQueryTimeoutMs;
+        ctx.effect(() => () => {
+            for (const pending of this.pending.values()) {
+                pending.settle({ ok: false, reason: 'cancelled', message: 'Client inspect registry was disposed' });
+            }
+        }, 'cordis-inspect: pending queries');
+    }
+    /**
+     * Register one Host provider.
+     * @param registration - manifest and local query handler.
+     * @returns idempotent disposer.
+     */
+    register(registration) {
+        const manifest = validateManifest(registration.manifest);
+        if (this.providers.has(manifest.id))
+            throw new Error(`Host Cordis inspect provider "${manifest.id}" is already registered`);
+        const stored = { ...registration, manifest };
+        this.providers.set(manifest.id, stored);
+        return () => {
+            if (this.providers.get(manifest.id) === stored)
+                this.providers.delete(manifest.id);
+        };
+    }
+    /**
+     * Replace the mirrored Client provider directory.
+     * @param providers - complete Client manifest snapshot.
+     */
+    syncClientManifest(providers) {
+        const ids = new Set();
+        const validated = providers.map((provider) => {
+            const manifest = validateManifest(provider);
+            if (ids.has(manifest.id))
+                throw new Error(`Client Cordis inspect manifest repeats provider "${manifest.id}"`);
+            ids.add(manifest.id);
+            return manifest;
+        });
+        this.clientManifest = Object.freeze(validated);
+    }
+    /**
+     * Return the complete known Host and Client provider directory.
+     * @returns Host providers followed by the Client providers.
+     */
+    list() {
+        return [
+            ...[...this.providers.values()].map(provider => view('host', provider.manifest)),
+            ...(this.clientManifest ?? []).map(provider => view('client', provider)),
+        ];
+    }
+    /**
+     * Execute one provider query on its owning platform.
+     * @param platform - Host or Client runtime.
+     * @param providerId - provider selected from {@link list}.
+     * @param methodName - declared method name.
+     * @param input - optional lossless JSON input.
+     * @param agent - requesting Agent and scope.
+     * @param signal - tool-call cancellation.
+     * @returns provider JSON data; Client queries fail fast when Gateway has no live Client
+     * and retain only the first observed failure diagnostic for timeout reporting.
+     */
+    async query(platform, providerId, methodName, input, agent, signal) {
+        if (platform === 'host') {
+            const registration = this.providers.get(providerId);
+            if (registration === undefined)
+                throw new Error(`Host Cordis inspect provider "${providerId}" is not registered`);
+            const method = findMethod(registration.manifest, methodName);
+            validateInput('Host', providerId, method, input);
+            signal.throwIfAborted();
+            const data = await registration.query(methodName, input, { agent, signal });
+            signal.throwIfAborted();
+            return validateOutput('Host', providerId, method, data);
+        }
+        return await this.queryClient(providerId, methodName, input, agent, signal);
+    }
+    /**
+     * Accept the first valid Client response for a pending query.
+     * @param agent - Agent whose Session owns the query.
+     * @param requestId - Pending Client query identity.
+     * @param resolution - Client provider result or failure.
+     * @returns acknowledgement with accepted true only for a success that settles the query; only the first failure diagnostic is retained.
+     */
+    resolveClientQuery(agent, requestId, resolution) {
+        const pending = this.pending.get(requestId);
+        if (pending === undefined || pending.request.agentId !== agent.id)
+            return { accepted: false };
+        // A failed page must not prevent another page from supplying a valid result.
+        if (!resolution.ok) {
+            pending.failure ??= `${resolution.reason}: ${resolution.message}`;
+            return { accepted: false };
+        }
+        try {
+            resolution = {
+                ok: true,
+                data: validateOutput('Client', pending.request.provider, pending.method, resolution.data),
+            };
+        }
+        catch (error) {
+            pending.failure ??= error instanceof Error ? error.message : String(error);
+            return { accepted: false };
+        }
+        pending.settle(resolution);
+        return { accepted: true };
+    }
+    async queryClient(providerId, methodName, input, agent, signal) {
+        const provider = this.clientManifest?.find(candidate => candidate.id === providerId);
+        if (provider === undefined)
+            throw new Error(`Client Cordis inspect provider "${providerId}" is not registered`);
+        const method = findMethod(provider, methodName);
+        validateInput('Client', providerId, method, input);
+        signal.throwIfAborted();
+        const gateway = this.ctx.get('typertGateway');
+        if (gateway !== undefined && !gateway.hasLiveClient()) {
+            throw new Error(`Client inspect query ${providerId}.${methodName} has no connected Harness page. Open or reconnect the Harness page, then retry.`);
+        }
+        const requestId = `inspect-${this.nextRequest++}`;
+        const request = {
+            requestId,
+            agentId: agent.id,
+            provider: providerId,
+            method: methodName,
+            ...input === undefined ? {} : { input },
+        };
+        const result = new Promise((resolve) => {
+            this.pending.set(requestId, {
+                request,
+                method,
+                settle: (resolution) => {
+                    this.pending.delete(requestId);
+                    resolve(resolution);
+                    try {
+                        this.ctx.emit('cordis/inspect-query-resolved', { requestId });
+                    }
+                    catch (error) {
+                        console.error('[kylin-host-runner] notifying Client inspect completion failed:', error);
+                    }
+                },
+            });
+        });
+        const onAbort = () => {
+            this.pending.get(requestId)?.settle({
+                ok: false,
+                reason: 'cancelled',
+                message: `Client inspect query ${providerId}.${methodName} was cancelled`,
+            });
+        };
+        const timer = setTimeout(() => {
+            const pending = this.pending.get(requestId);
+            if (pending === undefined)
+                return;
+            const detail = pending.failure === undefined
+                ? 'Open or reconnect the Harness page, then retry.'
+                : `Client failure: ${pending.failure}`;
+            pending.settle({
+                ok: false,
+                reason: 'provider-error',
+                message: `Client inspect query ${providerId}.${methodName} timed out after ${this.clientQueryTimeoutMs}ms. ${detail}`,
+            });
+        }, this.clientQueryTimeoutMs);
+        signal.addEventListener('abort', onAbort, { once: true });
+        try {
+            if (signal.aborted)
+                onAbort();
+            else
+                this.ctx.emit('cordis/inspect-query', request);
+            const resolution = await result;
+            if (!resolution.ok)
+                throw new Error(`${providerId}.${methodName}: ${resolution.message}`);
+            return resolution.data;
+        }
+        finally {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', onAbort);
+            this.pending.delete(requestId);
+        }
+    }
+}
+function view(platform, manifest) {
+    return { platform, ...manifest, methods: [...manifest.methods] };
+}
+function validateManifest(manifest) {
+    if (manifest.id.trim() === '')
+        throw new Error('Kylin inspect provider id must not be empty');
+    if (manifest.description.trim() === '')
+        throw new Error(`Cordis inspect provider "${manifest.id}" needs a description`);
+    const names = new Set();
+    const methods = manifest.methods.map((method) => {
+        if (method.name.trim() === '')
+            throw new Error(`Cordis inspect provider "${manifest.id}" has an empty method name`);
+        if (names.has(method.name))
+            throw new Error(`Cordis inspect provider "${manifest.id}" repeats method "${method.name}"`);
+        if (method.description.trim() === '')
+            throw new Error(`Cordis inspect method ${manifest.id}.${method.name} needs a description`);
+        assertSupportedJsonSchema(method.inputSchema);
+        assertSupportedJsonSchema(method.outputSchema);
+        names.add(method.name);
+        return Object.freeze({ ...method });
+    });
+    return Object.freeze({ ...manifest, methods: Object.freeze(methods) });
+}
+function findMethod(manifest, name) {
+    const method = manifest.methods.find(candidate => candidate.name === name);
+    if (method === undefined)
+        throw new Error(`Cordis inspect provider "${manifest.id}" has no method "${name}"`);
+    return method;
+}
+function validateInput(platform, provider, method, input) {
+    const violations = validateJsonSchemaValue(method.inputSchema, input ?? {}, 'input');
+    if (violations.length > 0)
+        throw new Error(`${platform} Cordis inspect ${provider}.${method.name} rejected input: ${violations.join('; ')}`);
+}
+function validateOutput(platform, provider, method, data) {
+    const snapshot = snapshotJsonValue(data);
+    if (snapshot === undefined)
+        throw new Error(`${platform} Cordis inspect ${provider}.${method.name} returned a non-JSON value`);
+    const violations = validateJsonSchemaValue(method.outputSchema, snapshot, 'output');
+    if (violations.length > 0)
+        throw new Error(`${platform} Cordis inspect ${provider}.${method.name} returned invalid output: ${violations.join('; ')}`);
+    return snapshot;
+}
+//# sourceMappingURL=inspect-registry.js.map

package/lib/types/lifecycle.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Host-half fiber lifecycle over the `cordis-dynamic` group: settle a
+ * sandbox-produced plugin as a child fiber (never leaving a failed fiber
+ * mounted), and report the services a settled-but-pending fiber still waits
+ * for. Stopping needs no helper — a host half unwinds through an ordinary
+ * awaited `fiber.dispose()`, because everything the plugin registered is an
+ * effect on its fiber.
+ * @module @qilin-agent/kylin-host-runner/lifecycle
+ */
+import type { Context, Fiber, Plugin } from '@qilin-agent/kylin';
+/**
+ * Await the group, start and settle one guarded child, and dispose it before rethrowing any
+ * startup failure so a failed run never lingers. A valid unresolved inject may remain pending.
+ * @param group - the `cordis-dynamic` group fiber every host half hangs under.
+ * @param plugin - the plugin the sandbox returned; wrapped with the registration guard before starting.
+ * @param reportGuardFailure - reports post-activation Host guard rejections to the owning Agent.
+ * @returns the settled child fiber (possibly pending on unsatisfied `inject`).
+ */
+export declare function startHostHalf(group: Fiber, plugin: Plugin, reportGuardFailure: (error: Error) => void): Promise<Fiber>;
+/**
+ * The services a fiber declared in `inject` that do not exist yet — a settled
+ * fiber that is not active is waiting on exactly these (legal cordis
+ * semantics: it activates when the service appears).
+ * @param ctx - the context to resolve service existence against.
+ * @param fiber - the host-half fiber whose `inject` declarations are checked.
+ * @returns the missing service names, in declaration order.
+ */
+export declare function missingServices(ctx: Context, fiber: Fiber): string[];
+//# sourceMappingURL=lifecycle.d.ts.map

package/lib/types/lifecycle.js

@@ -0,0 +1,49 @@
+/**
+ * Host-half fiber lifecycle over the `cordis-dynamic` group: settle a
+ * sandbox-produced plugin as a child fiber (never leaving a failed fiber
+ * mounted), and report the services a settled-but-pending fiber still waits
+ * for. Stopping needs no helper — a host half unwinds through an ordinary
+ * awaited `fiber.dispose()`, because everything the plugin registered is an
+ * effect on its fiber.
+ * @module @qilin-agent/kylin-host-runner/lifecycle
+ */
+import { guardedPlugin } from "./guard.js";
+/**
+ * Await the group, start and settle one guarded child, and dispose it before rethrowing any
+ * startup failure so a failed run never lingers. A valid unresolved inject may remain pending.
+ * @param group - the `cordis-dynamic` group fiber every host half hangs under.
+ * @param plugin - the plugin the sandbox returned; wrapped with the registration guard before starting.
+ * @param reportGuardFailure - reports post-activation Host guard rejections to the owning Agent.
+ * @returns the settled child fiber (possibly pending on unsatisfied `inject`).
+ */
+export async function startHostHalf(group, plugin, reportGuardFailure) {
+    await group.await();
+    const fiber = group.ctx.plugin(guardedPlugin(plugin, reportGuardFailure));
+    try {
+        await fiber.await();
+    }
+    catch (error) {
+        await fiber.dispose();
+        const message = error instanceof Error ? error.message : String(error);
+        // The commonest startup collision is running a NEW version of a package
+        // while the old run still holds the name — teach the replace recipe.
+        if (message.includes('already registered')) {
+            throw new Error(`${message} — to REPLACE something an earlier dynamic package registered, first stop that package through its runner or the Cordis panel `
+                + 'before running the new version.');
+        }
+        throw error instanceof Error ? error : new Error(message);
+    }
+    return fiber;
+}
+/**
+ * The services a fiber declared in `inject` that do not exist yet — a settled
+ * fiber that is not active is waiting on exactly these (legal cordis
+ * semantics: it activates when the service appears).
+ * @param ctx - the context to resolve service existence against.
+ * @param fiber - the host-half fiber whose `inject` declarations are checked.
+ * @returns the missing service names, in declaration order.
+ */
+export function missingServices(ctx, fiber) {
+    return Object.keys(fiber.inject).filter(service => ctx.get(service) === undefined);
+}
+//# sourceMappingURL=lifecycle.js.map

package/lib/types/registry.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Process-local dynamic Plugin registry and its opaque identity mints.
+ * @module @qilin-agent/kylin-host-runner/registry
+ */
+import type { Fiber } from '@qilin-agent/kylin';
+import type { SessionId } from '@qilin-agent/session/types';
+import type { ApprovalRequestId, CordisDynamicPackageId, CordisDynamicPluginId, CordisDynamicPluginRunId, CordisDynamicRunMode, DynamicCordisRenderFailure, DynamicCordisRunAttempt } from './types.ts';
+/** One Host method exposed to this package's Client half. */
+export type DynamicCordisHandler = (args: unknown) => Promise<unknown>;
+/** One live activation and everything its teardown owns. */
+export interface DynamicCordisRun {
+    /** Exact activation identity. */
+    pluginRunId: CordisDynamicPluginRunId;
+    /** Immutable package version being run. */
+    packageId: CordisDynamicPackageId;
+    /** Host-half Fiber, absent for Client-only packages. */
+    fiber?: Fiber;
+    /** Active Host methods. */
+    handlers: Map<string, DynamicCordisHandler>;
+    /** Method registration cleanup. */
+    handlerDisposers: (() => void)[];
+    /** Runtime failures already sent to the owning Agent during this activation. */
+    reportedRuntimeErrors: Set<string>;
+    /** Last render failure observed for this version's current run. */
+    renderFailure?: DynamicCordisRenderFailure;
+    /** Approval whose transition started this run, when model-driven. */
+    startedForRequest?: ApprovalRequestId;
+}
+/** One immutable package version. */
+export interface DynamicCordisDefinition {
+    /** Package identity. */
+    packageId: CordisDynamicPackageId;
+    /** Package label. */
+    name: string;
+    /** User-facing purpose. */
+    purpose: string;
+    /** Host source. */
+    hostCode?: string;
+    /** Client source. */
+    clientCode?: string;
+}
+/** Stable plugin instance containing immutable package versions. */
+export interface DynamicCordisPlugin {
+    /** Stable identity. */
+    pluginId: CordisDynamicPluginId;
+    /** Owning session. */
+    sessionId: SessionId;
+    /** Versions in define order. */
+    packages: Map<CordisDynamicPackageId, DynamicCordisDefinition>;
+    /** Client-bearing Packages individually authorized by the user. */
+    approvedClientPackages: Set<CordisDynamicPackageId>;
+    /** Whether one user decision authorized future Package versions of this Plugin. */
+    clientVersionUpdatesApproved: boolean;
+    /** Last successfully activated version. */
+    currentPackageId?: CordisDynamicPackageId;
+    /** Failed or in-progress target version. */
+    nextPackageId?: CordisDynamicPackageId;
+    /** Current activation. */
+    run?: DynamicCordisRun;
+    /** Latest activation attempt, including approval and asynchronous failure state. */
+    latestRun?: DynamicCordisRunAttempt;
+}
+/** One suspended model-driven activation. */
+export interface DynamicCordisPendingRequest {
+    /** Session whose model requested this activation. */
+    agentId: SessionId;
+    pluginId: CordisDynamicPluginId;
+    packageId: CordisDynamicPackageId;
+    pluginRunId: CordisDynamicPluginRunId;
+    mode: CordisDynamicRunMode;
+    /** Whether this request must wait for an explicit user decision. */
+    requiresApproval: boolean;
+}
+/** Request accepted by `define`; it never crosses the Remote transport. */
+export interface DynamicCordisDefineRequest {
+    /** Session that owns the plugin. */
+    sessionId: SessionId;
+    /** Create a plugin or append to an existing one. */
+    plugin: {
+        kind: 'new';
+        idPrefix: string;
+    } | {
+        kind: 'existing';
+        pluginId: CordisDynamicPluginId;
+    };
+    /** Package label. */
+    name: string;
+    /** User-facing purpose. */
+    purpose: string;
+    /** At least one source half. */
+    code: {
+        host?: string;
+        client?: string;
+    };
+}
+/** Successful `define` result. */
+export interface DynamicCordisDefineReceipt {
+    pluginId: CordisDynamicPluginId;
+    packageId: CordisDynamicPackageId;
+    name: string;
+    purpose: string;
+    hasHostHalf: boolean;
+    hasClientHalf: boolean;
+}
+/** Source-free modification context for an explicit `@pluginId` reference. */
+export interface DynamicCordisReference {
+    pluginId: CordisDynamicPluginId;
+    packageId: CordisDynamicPackageId;
+    name: string;
+    purpose: string;
+    currentPackageId?: CordisDynamicPackageId;
+    nextPackageId?: CordisDynamicPackageId;
+    activeRun?: {
+        pluginRunId: CordisDynamicPluginRunId;
+        packageId: CordisDynamicPackageId;
+    };
+    latestRun?: DynamicCordisRunAttempt;
+}
+/** Source-free Plugin summary returned by layered self inspection. */
+export interface DynamicCordisPluginInspection extends DynamicCordisReference {
+    /** Immutable Package summaries in define order. */
+    packages: Array<{
+        packageId: CordisDynamicPackageId;
+        name: string;
+        purpose: string;
+        hasHostHalf: boolean;
+        hasClientHalf: boolean;
+    }>;
+}
+/** Exact immutable Package metadata and source returned by explicit inspection. */
+export interface DynamicCordisPackageInspection extends DynamicCordisReference {
+    /** Host and Client function bodies stored for this Package. */
+    code: {
+        host?: string;
+        client?: string;
+    };
+}
+/** Registry, identity mints, and pending approval index. */
+export declare class DynamicCordisRegistry {
+    private readonly plugins;
+    private readonly pendingRequests;
+    private nextPlugin;
+    private nextPackage;
+    private nextRun;
+    private nextApproval;
+    /**
+     * Mint a semantic plugin ID without reusing a prior suffix.
+     * @param prefix - validated lowercase semantic prefix proposed by the model.
+     * @returns a process-unique Plugin ID.
+     */
+    mintPluginId(prefix: string): string;
+    /**
+     * Mint an immutable package ID.
+     * @returns a process-unique Package ID.
+     */
+    mintPackageId(): string;
+    /**
+     * Mint an activation ID.
+     * @returns a process-unique Plugin Run ID.
+     */
+    mintPluginRunId(): string;
+    /**
+     * Mint an approval ID.
+     * @returns a process-unique approval request ID.
+     */
+    mintApprovalRequestId(): string;
+    /**
+     * Add one stable plugin.
+     * @param plugin - Plugin record to retain under its stable ID.
+     */
+    add(plugin: DynamicCordisPlugin): void;
+    /**
+     * Read one plugin.
+     * @param id - stable Plugin ID.
+     * @returns the Plugin record, or `undefined` when absent.
+     */
+    get(id: CordisDynamicPluginId): DynamicCordisPlugin | undefined;
+    /**
+     * Delete one plugin and all package versions.
+     * @param id - stable Plugin ID to remove.
+     * @returns whether a Plugin record was removed.
+     */
+    delete(id: CordisDynamicPluginId): boolean;
+    /**
+     * Read all plugins in creation order.
+     * @returns a snapshot of every Plugin record.
+     */
+    all(): DynamicCordisPlugin[];
+    /**
+     * Read one session's plugins in creation order.
+     * @param sessionId - owning session to filter by.
+     * @returns a snapshot of matching Plugin records.
+     */
+    ofSession(sessionId: SessionId): DynamicCordisPlugin[];
+    /**
+     * Publish one pending approval.
+     * @param id - approval request ID.
+     * @param pending - resolver and Plugin metadata retained until settlement.
+     */
+    armRequest(id: ApprovalRequestId, pending: DynamicCordisPendingRequest): void;
+    /**
+     * Read one pending approval without claiming it.
+     * @param id - approval request ID.
+     * @returns the pending request, or `undefined` when absent.
+     */
+    peekRequest(id: ApprovalRequestId): DynamicCordisPendingRequest | undefined;
+    /**
+     * Claim one pending approval; first answer wins.
+     * @param id - approval request ID.
+     * @returns the claimed request, or `undefined` when already settled.
+     */
+    claimRequest(id: ApprovalRequestId): DynamicCordisPendingRequest | undefined;
+    /**
+     * Cancel one pending approval.
+     * @param id - approval request ID to remove.
+     */
+    disarmRequest(id: ApprovalRequestId): void;
+    /**
+     * Find a pending approval for one Plugin.
+     * @param pluginId - stable Plugin ID.
+     * @returns its approval request ID, or `undefined` when none is pending.
+     */
+    pendingRequestFor(pluginId: CordisDynamicPluginId): ApprovalRequestId | undefined;
+}
+//# sourceMappingURL=registry.d.ts.map