@hydraharness/harness-plugin-runtime 0.1.1-rc.5

package/lib/invariant.js

@@ -0,0 +1,13 @@
+//#region lib/types/invariant.js
+/** Package-owned invariant companion. @module @hydraharness/harness-plugin-runtime/invariant */
+const PACKAGE_NAME = "@hydraharness/harness-plugin-runtime";
+/** Cordis companion plugin name. */
+const name = "plugin-runtime-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/** No runtime invariant: runtime lifecycle observations are covered by the package's focused tests. */
+const install = () => {};
+/** Register the package ownership companion. */
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,310 @@
+/** Shared, immutable runtime for imported OpenAI/Codex and Claude plugin bundles. */
+import { Service, type Context } from '@hydraharness/cordis';
+import { type Config as McpClientConfig } from '@hydraharness/harness-mcp-client';
+import { type SkillDocument } from '@hydraharness/harness-skill';
+import type { ImportedPluginAgentMetadata, ImportedPluginEntry, ImportedPluginSnapshot, ImportedPluginSource, PluginImportSource, PluginManifest } from './types.ts';
+export type * from './types.ts';
+declare module '@hydraharness/cordis' {
+    interface Context {
+        importedPlugins: ImportedPluginRuntime;
+    }
+}
+/** Services required by the imported-plugin runtime. */
+export declare const inject: string[];
+/** Runtime configuration for the imported-plugin service. */
+export interface Config {
+    /** Override the resolved Hydra home directory. */
+    hydraHome?: string;
+}
+interface HookDefinition {
+    readonly label: string;
+    readonly raw: Record<string, unknown>;
+}
+interface McpDefinition {
+    readonly name: string;
+    readonly config: McpClientConfig;
+}
+interface LoadedPlugin {
+    readonly root: string;
+    readonly manifest: PluginManifest;
+    readonly skills: readonly LoadedSkill[];
+    readonly commands: readonly LoadedCommand[];
+    readonly mcp: readonly McpDefinition[];
+    readonly hooks: readonly HookDefinition[];
+    readonly hookDigest?: string;
+    readonly apps?: Readonly<Record<string, unknown>>;
+    readonly agentMetadata?: ImportedPluginAgentMetadata;
+}
+interface LoadedSkill {
+    readonly rawName: string;
+    readonly description: string;
+    readonly whenToUse?: string;
+    readonly invocation: SkillDocument['invocation'];
+    readonly path: string;
+    readonly directory: string;
+    readonly agentMetadata?: ImportedPluginAgentMetadata;
+    readonly openAiModelInvocable: boolean;
+}
+interface LoadedCommand {
+    readonly name: string;
+    readonly description: string;
+    readonly prompt: string;
+    readonly inputHint?: string;
+}
+interface StoredMcpState {
+    enabled: boolean;
+    defaultToolsApprovalMode: 'ask' | 'allow' | 'deny';
+    toolApproval: Record<string, 'ask' | 'allow' | 'deny'>;
+}
+interface StoredPlugin {
+    name: string;
+    source: ImportedPluginSource;
+    activeVersion: string;
+    versions: Record<string, {
+        installedAt: string;
+    }>;
+    enabled: boolean;
+    hookTrustDigest?: string;
+    mcp: Record<string, StoredMcpState>;
+}
+/** Plugin root resolver and manifest parser. It never executes plugin files. */
+export declare class PluginManifestLoader {
+    /**
+     * Validate and discover one bundle without executing it.
+     * @param root - Candidate plugin-root directory.
+     * @param identity - Source-qualified identity used to namespace MCP servers.
+     * @returns Parsed manifest and discovered component definitions.
+     */
+    load(root: string, identity?: string): Promise<LoadedPlugin>;
+}
+/** Durable registry and immutable bundle store beneath one Hydra home directory. */
+export declare class PluginStore {
+    readonly home: string;
+    /** Immutable versioned plugin-bundle root. */
+    readonly cacheRoot: string;
+    /** Persistent writable plugin-data root. */
+    readonly dataRoot: string;
+    /** Durable source-qualified plugin registry path. */
+    readonly registryPath: string;
+    private readonly manifests;
+    constructor(home?: string);
+    /**
+     * List every stored entry by source-qualified identity.
+     * @returns Every stored entry by source-qualified identity.
+     */
+    list(): Promise<ReadonlyMap<string, StoredPlugin>>;
+    /**
+     * Read one stored plugin entry.
+     * @param identity - Source-qualified plugin identity.
+     * @returns Stored entry, or undefined when absent.
+     */
+    get(identity: string): Promise<StoredPlugin | undefined>;
+    /**
+     * Validate, stage, and activate one imported source.
+     * @param source - Local, Git, or marketplace source.
+     * @returns Source-qualified identity of the activated plugin.
+     */
+    install(source: PluginImportSource): Promise<string>;
+    /**
+     * Mutate one durable entry while holding the registry lock.
+     * @param identity - Source-qualified plugin identity.
+     * @param mutation - In-place mutation applied before atomic persistence.
+     * @returns After the registry is persisted.
+     */
+    update(identity: string, mutation: (entry: StoredPlugin) => void): Promise<void>;
+    /**
+     * Remove one registry entry and its owned bundle and data directories.
+     * @param identity - Source-qualified plugin identity.
+     * @returns Removed entry, or undefined when absent.
+     */
+    remove(identity: string): Promise<StoredPlugin | undefined>;
+    /**
+     * Resolve the active immutable bundle path.
+     * @param entry - Stored plugin entry.
+     * @returns Active version directory.
+     */
+    bundlePath(entry: StoredPlugin): string;
+    /**
+     * Resolve the persistent writable data path.
+     * @param entry - Stored plugin entry.
+     * @returns Plugin data directory.
+     */
+    dataPath(entry: StoredPlugin): string;
+    /**
+     * Load one active stored bundle.
+     * @param entry - Stored plugin entry.
+     * @param identity - Source-qualified plugin identity.
+     * @returns Parsed active bundle.
+     */
+    load(entry: StoredPlugin, identity: string): Promise<LoadedPlugin>;
+    private readRegistry;
+    private writeRegistry;
+    private ensureRegistryDirectory;
+}
+/** Lightweight views over the durable records; the runtime owns live components. */
+export declare class PluginRegistry {
+    private readonly store;
+    constructor(store: PluginStore);
+    /**
+     * List every stored entry by source-qualified identity.
+     * @returns Every stored entry by source-qualified identity.
+     */
+    list(): Promise<ReadonlyMap<string, StoredPlugin>>;
+    /**
+     * Read one stored plugin entry.
+     * @param identity - Source-qualified plugin identity.
+     * @returns Stored entry, or undefined when absent.
+     */
+    get(identity: string): Promise<StoredPlugin | undefined>;
+}
+/** Explicit names for the runtime's independent trust and component registries. */
+export declare class PluginTrustStore {
+    private readonly store;
+    constructor(store: PluginStore);
+    /**
+     * Record trust for one exact hook definition digest.
+     * @param identity - Source-qualified plugin identity.
+     * @param definitionDigest - Current canonical hook-definition digest.
+     * @returns After trust persistence completes.
+     */
+    trust(identity: string, definitionDigest: string): Promise<void>;
+    /**
+     * Remove recorded hook trust.
+     * @param identity - Source-qualified plugin identity.
+     * @returns After trust removal persists.
+     */
+    untrust(identity: string): Promise<void>;
+}
+/** Public lifecycle facade over the shared imported-plugin runtime. */
+export declare class PluginLifecycleManager {
+    private readonly runtime;
+    constructor(runtime: ImportedPluginRuntime);
+    /**
+     * Enable and load one plugin.
+     * @param identity - Source-qualified plugin identity.
+     * @returns Refreshed installed-plugin projection.
+     */
+    enable(identity: string): Promise<ImportedPluginSnapshot>;
+    /**
+     * Disable and unload one plugin.
+     * @param identity - Source-qualified plugin identity.
+     * @returns Refreshed installed-plugin projection.
+     */
+    disable(identity: string): Promise<ImportedPluginSnapshot>;
+    /**
+     * Unload one plugin's live components.
+     * @param identity - Source-qualified plugin identity.
+     * @returns After owned components quiesce.
+     */
+    unload(identity: string): Promise<void>;
+}
+/** Shared `@hydraharness/harness-base` service for every imported bundle, not a Web-only facility. */
+export declare class ImportedPluginRuntime extends Service {
+    static inject: string[];
+    /** Component effects belong to the Host service, independent of a method caller's context. */
+    private readonly owner;
+    private readonly store;
+    /** Read-only facade over durable imported-plugin records. */
+    readonly registry: PluginRegistry;
+    /** Hook-definition trust record manager. */
+    readonly trust: PluginTrustStore;
+    /** Enablement and teardown facade. */
+    readonly lifecycle: PluginLifecycleManager;
+    private readonly live;
+    private readonly initialEnabled;
+    private readonly startup;
+    private mutationTail;
+    constructor(ctx: Context, config?: Config);
+    protected [Service.init](): Promise<void>;
+    /**
+     * Return every imported plugin's current source-qualified runtime view.
+     * @returns Current installed-plugin projection.
+     */
+    list(): Promise<ImportedPluginSnapshot>;
+    /**
+     * Return one installed plugin view.
+     * @param identityOrName - Source-qualified identity or an unambiguous plugin name.
+     * @returns Current installed-plugin projection.
+     */
+    info(identityOrName: string): Promise<ImportedPluginEntry>;
+    /**
+     * Stage one local, Git, or marketplace source.
+     * @param source - Source to import.
+     * @returns Refreshed installed-plugin projection.
+     */
+    import(source: PluginImportSource): Promise<ImportedPluginSnapshot>;
+    /**
+     * Enable and load one plugin.
+     * @param identityOrName - Plugin identity or unambiguous name.
+     * @returns Refreshed installed-plugin projection.
+     */
+    enable(identityOrName: string): Promise<ImportedPluginSnapshot>;
+    /**
+     * Disable and unload one plugin.
+     * @param identityOrName - Plugin identity or unambiguous name.
+     * @returns Refreshed installed-plugin projection.
+     */
+    disable(identityOrName: string): Promise<ImportedPluginSnapshot>;
+    /**
+     * Trust one plugin's current hook definition.
+     * @param identityOrName - Plugin identity or unambiguous name.
+     * @returns Refreshed installed-plugin projection.
+     */
+    trustHooks(identityOrName: string): Promise<ImportedPluginSnapshot>;
+    /**
+     * Revoke one plugin's hook trust.
+     * @param identityOrName - Plugin identity or unambiguous name.
+     * @returns Refreshed installed-plugin projection.
+     */
+    untrustHooks(identityOrName: string): Promise<ImportedPluginSnapshot>;
+    /**
+     * Unload and remove one plugin with its owned store paths.
+     * @param identityOrName - Plugin identity or unambiguous name.
+     * @returns Refreshed installed-plugin projection.
+     */
+    remove(identityOrName: string): Promise<ImportedPluginSnapshot>;
+    /**
+     * Set one plugin MCP server's lifecycle state.
+     * @param identityOrName - Owning plugin identity or unambiguous name.
+     * @param server - Manifest MCP server name.
+     * @param enabled - Desired server state.
+     * @returns Refreshed installed-plugin projection.
+     */
+    setMcpServerEnabled(identityOrName: string, server: string, enabled: boolean): Promise<ImportedPluginSnapshot>;
+    /**
+     * Set one MCP tool's approval mode.
+     * @param identityOrName - Owning plugin identity or unambiguous name.
+     * @param server - Manifest MCP server name.
+     * @param tool - Raw MCP tool name or host-qualified public tool name.
+     * @param approval - Independent per-tool approval mode.
+     * @returns Refreshed installed-plugin projection.
+     */
+    setMcpToolApproval(identityOrName: string, server: string, tool: string, approval: 'ask' | 'allow' | 'deny'): Promise<ImportedPluginSnapshot>;
+    /**
+     * Unload every live component owned by one plugin.
+     * @param identity - Installed plugin identity.
+     * @returns After skills, hooks, and MCP fibers quiesce.
+     */
+    unload(identity: string): Promise<void>;
+    private load;
+    private reload;
+    private registerSkills;
+    private registerCommands;
+    private startMcp;
+    private startHooks;
+    private view;
+    private resolve;
+    private require;
+    private enqueue;
+    private approveMcpTool;
+    private marketplaceInventory;
+    private requireMarketplaceInventory;
+    private resolveMarketplace;
+    private marketplaceCommand;
+    private installCommand;
+    private command;
+    private dispose;
+}
+export declare const name = "plugin-runtime";
+export default ImportedPluginRuntime;
+//# sourceMappingURL=index.d.ts.map