@opengeni/contracts 3.0.2-canary.0 → 3.0.2-canary.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/contracts",
-  "version": "3.0.2-canary.0",
+  "version": "3.0.2-canary.2",
   "description": "Shared zod schemas and wire-contract types for the OpenGeni API.",
   "license": "Apache-2.0",
   "repository": {
@@ -18,6 +18,10 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
+    "./plugin-discovery": {
+      "types": "./dist/plugin-discovery.d.ts",
+      "import": "./dist/plugin-discovery.js"
+    },
     "./host-mcp-bindings": {
       "types": "./dist/host-mcp-bindings.d.ts",
       "import": "./dist/host-mcp-bindings.js"

package/src/index.ts

@@ -11414,6 +11414,7 @@ export const SkillImportFileSummary = z.object({
 export type SkillImportFileSummary = z.infer<typeof SkillImportFileSummary>;
 
 export const SkillImportPreview = z.object({
+  markdown: z.string().max(262144).optional(),
   source: SkillImportSource,
   sourceUrl: z.string().url(),
   repositoryUrl: z.string().url(),
@@ -12147,6 +12148,7 @@ export const PluginInstallationSummary = z
     description: z.string().max(4000),
     category: z.string().min(1).max(100),
     tags: z.array(z.string().min(1).max(100)).max(64),
+    logoUrl: z.string().url().max(2048).nullable().optional(),
     sourceUrl: z.string().url().max(2048).nullable(),
     manifestDigest: z.string().regex(/^[0-9a-f]{64}$/),
     installationVersion: z.number().int().positive(),
@@ -12322,6 +12324,17 @@ export const Session = /* @__PURE__ */ defineSkillContractSchema(() =>
     workspaceId: z.string().uuid(),
     accountId: z.string().uuid(),
     status: SessionStatus,
+    /** Detail-only failure evidence through lastSequence; independent of timeline paging. */
+    failureDiagnostics: z
+      .object({
+        eventId: z.string().uuid(),
+        sequence: z.number().int().nonnegative(),
+        turnId: z.string().uuid().nullable(),
+        occurredAt: z.string(),
+        payload: z.unknown(),
+      })
+      .nullable()
+      .optional(),
     /** Additive list projection. Detail reads may omit it. */
     backgroundCommandActivity: SessionBackgroundCommandActivity.optional(),
     /** Current non-deleted schedules targeting this session, including paused schedules. */
@@ -16159,6 +16172,7 @@ export const MachineRuntimeCapabilities = z.object({
   browserBridge: z.boolean(),
   operationResourcePolicy: z.boolean(),
   operationCpuQuota: z.boolean(),
+  transactionalFsWrite: z.boolean().default(false),
 });
 export type MachineRuntimeCapabilities = z.infer<typeof MachineRuntimeCapabilities>;
 
@@ -17099,3 +17113,7 @@ export * from "./remember";
 export * from "./agent-authored-durable-text";
 
 export * from "./feedback";
+
+export type { PluginDiscoveryItem, PluginDiscoveryPage } from "./plugin-discovery";
+export { mcpEndpointIdentity } from "./mcp-endpoint";
+export { pluginMcpUnavailableReason } from "./mcp-endpoint";

package/src/mcp-endpoint.ts

@@ -0,0 +1,30 @@
+/** Exact endpoint identity: normalize URL syntax, preserve paths and query parameters. */
+export function mcpEndpointIdentity(value: string | null | undefined): string | null {
+  if (!value) return null;
+  try {
+    const url = new URL(value);
+    if (!["https:", "http:"].includes(url.protocol) || url.username || url.password) return null;
+    url.hash = "";
+    return url.href;
+  } catch {
+    return null;
+  }
+}
+
+export function pluginMcpUnavailableReason(server: {
+  endpoint: string | null;
+  transport?: string;
+  requiresConfiguration?: boolean;
+}): string | null {
+  if (server.transport === "stdio" || !server.endpoint) return "Requires a local runtime";
+  if (
+    server.transport &&
+    !["http", "streamable-http", "streamable_http"].includes(server.transport)
+  )
+    return "Unsupported transport: " + server.transport;
+  if (server.requiresConfiguration || server.endpoint.includes("{"))
+    return "Requires custom connection configuration";
+  const endpoint = mcpEndpointIdentity(server.endpoint);
+  if (!endpoint?.startsWith("https://")) return "Requires a valid HTTPS endpoint";
+  return null;
+}

package/src/plugin-discovery.ts

@@ -0,0 +1,33 @@
+/** Public discovery metadata; listing does not imply runtime compatibility. */
+export { pluginMcpUnavailableReason } from "./mcp-endpoint";
+
+export type PluginDiscoveryItem = {
+  id: string;
+  name: string;
+  displayName: string;
+  description: string;
+  longDescription: string;
+  provider: string;
+  category: string | null;
+  logoUrl: string | null;
+  darkLogoUrl: string | null;
+  sourceUrl: string | null;
+  author: { name?: string } | null;
+  version: string | null;
+  skills?: { name: string; sourceUrl: string }[] | null;
+  mcpServers?:
+    | {
+        name: string;
+        transport: string;
+        requiresConfiguration?: boolean;
+        endpoint: string | null;
+      }[]
+    | null;
+  components: string[] | null;
+  installation: string;
+};
+export type PluginDiscoveryPage = {
+  items: PluginDiscoveryItem[];
+  total: number;
+  nextOffset: number | null;
+};

package/src/skill-metadata.ts

@@ -14,8 +14,12 @@ export function parseSkillFrontmatter(markdown: string): {
     uniqueKeys: true,
     prettyErrors: false,
   });
-  if (document.errors.length || document.warnings.length)
-    throw new Error("Skill artifact SKILL.md has invalid YAML frontmatter");
+  if (document.errors.length || document.warnings.length) {
+    const issue = document.errors[0] ?? document.warnings[0]!;
+    throw new Error(
+      `This skill's SKILL.md header contains invalid YAML: ${issue.message}. The source file needs correcting.`,
+    );
+  }
   const metadata: unknown = document.toJS({ maxAliasCount: 20 });
   if (!metadata || typeof metadata !== "object" || Array.isArray(metadata))
     throw new Error("Skill artifact SKILL.md frontmatter must be a mapping");