@mcp-com-ai/plugin-capability-graph 0.0.0-stage → 1.2.0

package/dist/executor.d.ts

@@ -0,0 +1,21 @@
+import type { CapabilityExecutionLimitsV1, CapabilityExecutionRequestV1, CapabilityExecutionResultV1, CapabilityExecutionRuntimeBindingsV1, CapabilityExecutionTargetDescriptorV1, CapabilityExecutorFactoryV1, CapabilityExecutorV1, CapabilityGraphV1 } from "@mcp-com-ai/core";
+import type { CapabilityExecutionConfirmationPolicy } from "./execution-envelope";
+export declare const CAPABILITY_EXECUTION_SAFETY_CEILINGS: CapabilityExecutionLimitsV1;
+export declare const DEFAULT_CAPABILITY_EXECUTION_LIMITS: CapabilityExecutionLimitsV1;
+export interface GuardedCapabilityExecutorOptions {
+    readonly graph: CapabilityGraphV1;
+    readonly descriptors: ReadonlyMap<string, CapabilityExecutionTargetDescriptorV1>;
+    readonly bindings: CapabilityExecutionRuntimeBindingsV1;
+    readonly confirmation?: CapabilityExecutionConfirmationPolicy;
+}
+export declare class GuardedCapabilityExecutor implements CapabilityExecutorV1 {
+    private readonly options;
+    readonly id = "guarded-capability-executor-v1";
+    constructor(options: GuardedCapabilityExecutorOptions);
+    execute(originalRequest: CapabilityExecutionRequestV1): Promise<CapabilityExecutionResultV1>;
+    private executeStep;
+    private preflight;
+    private invokeAttempt;
+    private handleInvocation;
+}
+export declare function createGuardedCapabilityExecutorFactory(graph: CapabilityGraphV1, confirmation?: CapabilityExecutionConfirmationPolicy): CapabilityExecutorFactoryV1;

package/dist/extensions.d.ts

@@ -0,0 +1,100 @@
+import type { CapabilityGraphDiagnostic, CapabilityGraphEffects, PlanningFactV1 } from "@mcp-com-ai/core";
+export declare const HAPI_PLANNING_EXTENSION_KEY = "x-hapi-planning";
+export interface ParsedPlanningExtensionV1 {
+    readonly requires: readonly PlanningFactV1[];
+    readonly produces: readonly PlanningFactV1[];
+    readonly removes: readonly PlanningFactV1[];
+    readonly cost: number;
+}
+/** Documentation schema mirrored by the strict parser below. */
+export declare const HAPI_PLANNING_EXTENSION_SCHEMA_V1: Readonly<{
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["produces"];
+    readonly properties: {
+        readonly requires: {
+            readonly type: "array";
+            readonly items: {
+                readonly $ref: "#/$defs/fact";
+            };
+        };
+        readonly produces: {
+            readonly type: "array";
+            readonly minItems: 1;
+            readonly items: {
+                readonly $ref: "#/$defs/fact";
+            };
+        };
+        readonly removes: {
+            readonly type: "array";
+            readonly items: {
+                readonly $ref: "#/$defs/fact";
+            };
+        };
+        readonly cost: {
+            readonly type: "number";
+            readonly minimum: 0;
+        };
+    };
+    readonly $defs: {
+        readonly fact: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["predicate"];
+            readonly properties: {
+                readonly predicate: {
+                    readonly type: "string";
+                    readonly pattern: "^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$";
+                };
+                readonly value: {};
+            };
+        };
+    };
+}>;
+export interface ParsedCapabilityExtensions {
+    readonly capabilities?: readonly string[];
+    readonly intent?: {
+        readonly useWhen: readonly string[];
+        readonly avoidWhen: readonly string[];
+    };
+    readonly effects?: CapabilityGraphEffects;
+    readonly prerequisites?: readonly string[];
+    readonly planning?: ParsedPlanningExtensionV1;
+}
+export declare function parseCapabilityExtensions(operation: Record<string, unknown>, pointer: string, operationId: string, diagnostics: CapabilityGraphDiagnostic[]): ParsedCapabilityExtensions;
+/**
+ * Validate and canonicalize planning metadata without attaching it to the
+ * compiled graph. Group 2 owns compilation and provenance integration.
+ */
+export declare function parsePlanningExtensionV1(operation: Record<string, unknown>, pointer: string, operationId: string, diagnostics: CapabilityGraphDiagnostic[]): ParsedPlanningExtensionV1 | undefined;
+export declare const HAPI_OUTCOME_EXTENSION_KEY = "x-hapi-outcome";
+export interface ParsedOutcomeExtensionV1 {
+    readonly produces: readonly PlanningFactV1[];
+    readonly removes: readonly PlanningFactV1[];
+}
+/** True for `2xx` status keys, which `x-hapi-planning` already models. */
+export declare function isSuccessStatusKey(status: string): boolean;
+/**
+ * Validate a response-level `x-hapi-outcome`: optional canonical `produces`
+ * and `removes`, at least one non-empty, never overlapping, and never on a
+ * success status.
+ */
+export declare function parseOutcomeExtensionV1(value: unknown, pointer: string, status: string, operationId: string, diagnostics: CapabilityGraphDiagnostic[]): ParsedOutcomeExtensionV1 | undefined;
+export declare const HAPI_CLIENT_FACTS_EXTENSION_KEY = "x-hapi-client-facts";
+export interface ParsedClientFactV1 {
+    readonly fact: PlanningFactV1;
+    readonly description?: string;
+    readonly pointer: string;
+}
+/**
+ * Validate root-level `x-hapi-client-facts`: an array of canonical facts with
+ * an optional non-empty description, no duplicates and no other keys.
+ */
+export declare function parseClientFactsExtensionV1(value: unknown, diagnostics: CapabilityGraphDiagnostic[]): readonly ParsedClientFactV1[] | undefined;
+export declare const HAPI_EVENT_EXTENSION_KEY = "x-hapi-event";
+/**
+ * Validate `x-hapi-event` on a webhook or callback operation: an object with a
+ * non-empty canonical `produces` fact array and no other keys.
+ */
+export declare function parseEventExtensionV1(value: unknown, pointer: string, triggerId: string, diagnostics: CapabilityGraphDiagnostic[]): readonly PlanningFactV1[] | undefined;
+export declare function defaultEffectsForMethod(method: string): CapabilityGraphEffects;

package/dist/fact-audit.d.ts

@@ -0,0 +1,34 @@
+import type { CapabilityGraphPlanningBoundsV1, CapabilityGraphPlanningOutcome, CapabilityGraphV1, PlanningFactV1 } from "@mcp-com-ai/core";
+import { type CapabilityGraphFactClosureV1 } from "./fact-closure";
+export interface CapabilityGraphReachabilityResultV1 {
+    readonly goal: PlanningFactV1;
+    readonly label: string;
+    readonly outcome: CapabilityGraphPlanningOutcome;
+    readonly reachable: boolean;
+    readonly diagnostics: readonly string[];
+}
+/**
+ * A topology check: every transition target is eligible and every
+ * non-authorization gate is treated as satisfied. It never grants real
+ * authorization or confirmation.
+ */
+export interface CapabilityGraphReachabilitySweepV1 {
+    readonly kind: "topology-check";
+    readonly initialFacts: readonly PlanningFactV1[];
+    readonly satisfiedGates: readonly string[];
+    readonly results: readonly CapabilityGraphReachabilityResultV1[];
+}
+export interface CapabilityGraphFactAuditReportV1 extends CapabilityGraphFactClosureV1 {
+    readonly graphFingerprint: string;
+    readonly reachability?: CapabilityGraphReachabilitySweepV1;
+    readonly clean: boolean;
+}
+export interface CapabilityGraphFactAuditOptions {
+    readonly clientVerifiedFacts?: readonly PlanningFactV1[];
+    /** Goals to sweep; defaults to the closure's outcomes. */
+    readonly goalFacts?: readonly PlanningFactV1[];
+    readonly reachability?: boolean;
+    readonly bounds?: CapabilityGraphPlanningBoundsV1;
+}
+export declare function auditCapabilityGraphFacts(graph: CapabilityGraphV1, options?: CapabilityGraphFactAuditOptions): Promise<CapabilityGraphFactAuditReportV1>;
+export declare function renderFactAuditSummary(report: CapabilityGraphFactAuditReportV1): string;

package/dist/fact-closure.d.ts

@@ -0,0 +1,41 @@
+import type { CapabilityGraphV1, PlanningFactV1 } from "@mcp-com-ai/core";
+/** One business fact and the transition targets it relates to. */
+export type CapabilityGraphClientFactOrigin = "contract" | "option";
+export interface CapabilityGraphFactFindingV1 {
+    readonly fact: PlanningFactV1;
+    readonly label: string;
+    readonly operations: readonly string[];
+    /** Client-verified findings only: where the declaration came from. */
+    readonly origins?: readonly CapabilityGraphClientFactOrigin[];
+}
+/**
+ * Static fact-closure findings for a compiled graph. Pure analysis: no planner
+ * run, no API call, and compiler-generated technical facts are excluded.
+ */
+export interface CapabilityGraphFactClosureV1 {
+    readonly schemaVersion: "1";
+    /** Required somewhere, produced nowhere, and not declared client-verified. */
+    readonly orphanRequirements: readonly CapabilityGraphFactFindingV1[];
+    /** Declared client-verified facts that some transition requires. */
+    readonly clientVerifiedFacts: readonly CapabilityGraphFactFindingV1[];
+    /** Produced and never required: candidate goals. */
+    readonly outcomes: readonly CapabilityGraphFactFindingV1[];
+    /**
+     * Facts produced by declared response outcomes, with `<operation> <status>`
+     * sources. They are established by an observed response, never planned.
+     */
+    readonly responseFacts: readonly CapabilityGraphFactFindingV1[];
+    /** Facts signalled by declared webhook or callback triggers, by trigger id. */
+    readonly eventFacts: readonly CapabilityGraphFactFindingV1[];
+    /** Operations that no planning transition targets. */
+    readonly discoveryOnlyOperations: readonly string[];
+}
+export declare function analyzeFactClosure(graph: CapabilityGraphV1, clientVerifiedFacts?: readonly PlanningFactV1[]): CapabilityGraphFactClosureV1;
+/**
+ * Client-verified facts from the contract's `x-hapi-client-facts` and from
+ * explicit options, keyed by canonical fact, with each fact's origins.
+ */
+export declare function clientFactOrigins(graph: CapabilityGraphV1, optionFacts?: readonly PlanningFactV1[]): Map<string, Set<CapabilityGraphClientFactOrigin>>;
+/** The union of contract-declared and option client facts, canonically sorted. */
+export declare function effectiveClientFacts(graph: CapabilityGraphV1, optionFacts?: readonly PlanningFactV1[]): PlanningFactV1[];
+export declare function factLabel(fact: PlanningFactV1): string;

package/dist/graphml.d.ts

@@ -0,0 +1,2 @@
+import type { CapabilityGraphV1 } from '@mcp-com-ai/core';
+export declare function serializeCapabilityGraphMl(graph: CapabilityGraphV1): string;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { type HapiCliPlugin } from "@mcp-com-ai/plugin-sdk";
+declare const plugin: HapiCliPlugin;
+export default plugin;
+export { plugin };
+export * from "./runtime";
+export { graphRootCommand } from "./commands";