@opengeni/contracts 3.0.1 → 3.0.2-canary.1

package/dist/plugin-discovery.d.ts

@@ -0,0 +1,35 @@
+/** Public discovery metadata; listing does not imply runtime compatibility. */
+export { pluginMcpUnavailableReason } from "./mcp-endpoint.js";
+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/dist/plugin-discovery.js

@@ -0,0 +1,7 @@
+import {
+  pluginMcpUnavailableReason
+} from "./chunk-WBYTNVIW.js";
+export {
+  pluginMcpUnavailableReason
+};
+//# sourceMappingURL=plugin-discovery.js.map

package/dist/plugin-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/sandbox-snapshots.d.ts

@@ -50,13 +50,31 @@ export type WorkspaceArchiveObjectRef = {
     bytes: number;
     backend: string;
 };
+export type WorkspaceArchiveObjectKey = {
+    accountId: string;
+    workspaceId: string;
+    sandboxGroupId: string;
+    revision: string;
+    uploadId: string | null;
+};
+export declare function parseWorkspaceArchiveObjectKey(value: unknown): WorkspaceArchiveObjectKey | null;
 export declare function parseWorkspaceArchiveObjectRef(value: unknown): WorkspaceArchiveObjectRef | null;
 export declare function workspaceArchiveObjectKey(input: {
     accountId: string;
     workspaceId: string;
     sandboxGroupId: string;
     revision: string;
+    /** New upload invocations supply a fresh randomUUID; omission is legacy-only. */
+    uploadId?: string;
 }): string;
+/** Bind a stored locator to its publication/restore scope and verified tar
+ * descriptor. A logical revision never substitutes for the exact physical key. */
+export declare function validateWorkspaceArchiveObjectRef(value: unknown, input: {
+    accountId: string;
+    workspaceId: string;
+    sandboxGroupId: string;
+    descriptor: WorkspaceArchiveDescriptor;
+}): WorkspaceArchiveObjectRef | null;
 export declare function workspaceArchivePayloadPresent(sessionState: Record<string, unknown> | null | undefined): boolean;
 /** Restore may inline object bytes in memory for hydrate. That copy must never
  *  be published onto a lease when a durable object-storage ref exists. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/contracts",
-  "version": "3.0.1",
+  "version": "3.0.2-canary.1",
   "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

@@ -180,7 +180,9 @@ export {
   encodeNativeSnapshotRef,
   omitInlineWorkspaceArchiveWhenObjectRefPresent,
   parseWorkspaceArchiveDescriptor,
+  parseWorkspaceArchiveObjectKey,
   parseWorkspaceArchiveObjectRef,
+  validateWorkspaceArchiveObjectRef,
   workspaceArchiveObjectKey,
   workspaceArchivePayloadPresent,
   type NativeSnapshotDescriptor,
@@ -189,6 +191,7 @@ export {
   type TarWorkspaceArchiveDescriptor,
   type WorkspaceArchiveDescriptor,
   type WorkspaceArchiveObjectRef,
+  type WorkspaceArchiveObjectKey,
   type WorkspaceTreeFingerprint,
 } from "./sandbox-snapshots";
 
@@ -11411,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(),
@@ -12144,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(),
@@ -12319,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. */
@@ -16156,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>;
 
@@ -17096,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/sandbox-snapshots.ts

@@ -64,8 +64,35 @@ export type WorkspaceArchiveObjectRef = {
   backend: string;
 };
 
+// Keep legacy scope/key spelling readable. New physical upload identities must
+// be a complete RFC UUID (including version and variant), never arbitrary text.
+const UPLOAD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const OBJECT_KEY =
-  /^sandbox-archives\/v1\/[0-9a-f-]{36}\/[0-9a-f-]{36}\/[0-9a-f-]{36}\/wa1:[0-9]{13}:[0-9a-f]{64}\.tar$/i;
+  /^sandbox-archives\/v1\/([0-9a-f-]{36})\/([0-9a-f-]{36})\/([0-9a-f-]{36})\/(wa1:[0-9]{13}:[0-9a-f]{64})(?:\.([0-9a-f-]+))?\.tar$/i;
+
+export type WorkspaceArchiveObjectKey = {
+  accountId: string;
+  workspaceId: string;
+  sandboxGroupId: string;
+  revision: string;
+  uploadId: string | null;
+};
+
+export function parseWorkspaceArchiveObjectKey(value: unknown): WorkspaceArchiveObjectKey | null {
+  if (typeof value !== "string") return null;
+  const match = OBJECT_KEY.exec(value);
+  // JS $ may match before a final newline; a locator must match in full.
+  if (!match || match[0] !== value || (match[5] !== undefined && !UPLOAD_ID.test(match[5]))) {
+    return null;
+  }
+  return {
+    accountId: match[1]!,
+    workspaceId: match[2]!,
+    sandboxGroupId: match[3]!,
+    revision: match[4]!,
+    uploadId: match[5] ?? null,
+  };
+}
 
 export function parseWorkspaceArchiveObjectRef(value: unknown): WorkspaceArchiveObjectRef | null {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
@@ -73,7 +100,7 @@ export function parseWorkspaceArchiveObjectRef(value: unknown): WorkspaceArchive
   if (
     candidate.schema !== WORKSPACE_ARCHIVE_OBJECT_REF_SCHEMA ||
     typeof candidate.key !== "string" ||
-    !OBJECT_KEY.test(candidate.key) ||
+    !parseWorkspaceArchiveObjectKey(candidate.key) ||
     typeof candidate.sha256 !== "string" ||
     !SHA256.test(candidate.sha256) ||
     !nonnegativeInteger(candidate.bytes) ||
@@ -98,8 +125,45 @@ export function workspaceArchiveObjectKey(input: {
   workspaceId: string;
   sandboxGroupId: string;
   revision: string;
+  /** New upload invocations supply a fresh randomUUID; omission is legacy-only. */
+  uploadId?: string;
 }): string {
-  return `sandbox-archives/v1/${input.accountId}/${input.workspaceId}/${input.sandboxGroupId}/${input.revision}.tar`;
+  if (
+    input.uploadId !== undefined &&
+    (!UPLOAD_ID.test(input.uploadId) || input.uploadId.length !== 36)
+  ) {
+    throw new Error("Invalid workspace archive upload UUID");
+  }
+  return `sandbox-archives/v1/${input.accountId}/${input.workspaceId}/${input.sandboxGroupId}/${input.revision}${input.uploadId === undefined ? "" : `.${input.uploadId}`}.tar`;
+}
+
+/** Bind a stored locator to its publication/restore scope and verified tar
+ * descriptor. A logical revision never substitutes for the exact physical key. */
+export function validateWorkspaceArchiveObjectRef(
+  value: unknown,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    sandboxGroupId: string;
+    descriptor: WorkspaceArchiveDescriptor;
+  },
+): WorkspaceArchiveObjectRef | null {
+  const ref = parseWorkspaceArchiveObjectRef(value);
+  const key = ref && parseWorkspaceArchiveObjectKey(ref.key);
+  const descriptor = parseWorkspaceArchiveDescriptor(input.descriptor);
+  if (
+    !ref ||
+    !key ||
+    descriptor?.version !== 1 ||
+    key.accountId.toLowerCase() !== input.accountId.toLowerCase() ||
+    key.workspaceId.toLowerCase() !== input.workspaceId.toLowerCase() ||
+    key.sandboxGroupId.toLowerCase() !== input.sandboxGroupId.toLowerCase() ||
+    key.revision !== descriptor.revision ||
+    ref.sha256 !== descriptor.archiveSha256 ||
+    ref.bytes !== descriptor.archiveBytes
+  )
+    return null;
+  return ref;
 }
 
 export function workspaceArchivePayloadPresent(

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");