@opengeni/core 2.9.3 → 2.9.4-canary.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "2.9.3",
+  "version": "2.9.4-canary.1",
   "description": "OpenGeni framework-agnostic core: the domain, access, and billing layers (neutral access, off-HTTP V2 surface). Behavior-preserving extraction from apps/api — keeps Hono's HTTPException for error throwing (typed-errors cleanup deferred).",
   "license": "Apache-2.0",
   "repository": {
@@ -58,17 +58,17 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/capabilities": "^0.3.3",
-    "@opengeni/codex": "^0.2.22",
-    "@opengeni/config": "^1.1.1",
-    "@opengeni/contracts": "^3.0.1",
-    "@opengeni/db": "^4.3.2",
-    "@opengeni/documents": "^0.8.26",
-    "@opengeni/events": "^0.4.24",
-    "@opengeni/network": "^0.3.1",
-    "@opengeni/observability": "^0.8.25",
-    "@opengeni/runtime": "^2.5.2",
-    "@opengeni/storage": "^0.2.126",
+    "@opengeni/capabilities": "^0.3.3-canary.9",
+    "@opengeni/codex": "^0.2.22-canary.9",
+    "@opengeni/config": "^1.1.2-canary.1",
+    "@opengeni/contracts": "^3.0.2-canary.1",
+    "@opengeni/db": "^4.3.3-canary.1",
+    "@opengeni/documents": "^0.8.27-canary.1",
+    "@opengeni/events": "^0.4.25-canary.1",
+    "@opengeni/network": "^0.3.1-canary.9",
+    "@opengeni/observability": "^0.8.26-canary.1",
+    "@opengeni/runtime": "^2.5.3-canary.1",
+    "@opengeni/storage": "^0.2.127-canary.1",
     "hono": "^4.12.18",
     "zod": "^4.2.1"
   },

package/src/domain/capabilities.ts

@@ -123,7 +123,7 @@ export async function buildCapabilityCatalog(input: {
     ...configuredMcpCatalogItems(input.settings),
     ...providerIntegrationCatalogItems(socialConnections),
     fikenCatalogItem(workspaceConnections.filter(isFikenConnection)),
-    ...curatedLibrarySkills,
+    ...curatedLibrarySkills.filter((item) => installedSkillById.has(item.id)),
     ...installedSkills
       .filter(
         (skill) =>
@@ -980,9 +980,6 @@ export async function discoverMcpRegistryCapabilities(input: {
       if (!item || seen.has(item.id)) {
         continue;
       }
-      if (query && !catalogSearchText(item).includes(query)) {
-        continue;
-      }
       seen.add(item.id);
       items.push(item);
       if (items.length >= limit) {
@@ -990,7 +987,9 @@ export async function discoverMcpRegistryCapabilities(input: {
       }
     }
     cursor = typeof page.metadata?.nextCursor === "string" ? page.metadata.nextCursor : undefined;
-    if (!cursor) {
+    // Return usable results promptly rather than fetching more pages merely
+    // to fill the requested limit. The registry already applies the search.
+    if (items.length > 0 || !cursor) {
       break;
     }
   }
@@ -1996,22 +1995,6 @@ function validUrl(value: string | undefined): string | null {
   }
 }
 
-function catalogSearchText(item: CapabilityCatalogItem): string {
-  return [
-    item.name,
-    item.description,
-    item.category,
-    ...item.tags,
-    item.endpointUrl,
-    item.homepageUrl,
-    item.installUrl,
-    JSON.stringify(item.metadata),
-  ]
-    .filter(Boolean)
-    .join(" ")
-    .toLowerCase();
-}
-
 function capabilityInstallationRuntimeReady(
   item: CapabilityCatalogItem,
   installation: CapabilityInstallation | undefined,

package/src/domain/github-skill-source.ts

@@ -1,6 +1,12 @@
 import type { Settings } from "@opengeni/config";
+import { HTTPException } from "hono/http-exception";
 import type { GitHubSkillSourceClient, GitHubSkillTreeEntry } from "./skill-imports";
 import { pinnedFetch, readResponseJsonBounded, readResponseTextBounded } from "@opengeni/network";
+import {
+  PORTABLE_SKILL_MAX_FILES,
+  PORTABLE_SKILL_MAX_TOTAL_BYTES,
+  type SkillLibraryFile,
+} from "@opengeni/runtime/skill-library";
 
 const githubApiBase = "https://api.github.com";
 const githubRequestTimeoutMs = 15_000;
@@ -14,7 +20,32 @@ export function createGitHubSkillSourceClient(
   requestJson: GitHubJsonRequest = (path, maxBytes, label) =>
     githubJson(settings, path, maxBytes, label),
 ): GitHubSkillSourceClient {
+  const readJson = requestJson;
+  const cache = new Map<string, { expires: number; payload: unknown }>();
+  const pending = new Map<string, Promise<unknown>>();
+  requestJson = async (path, maxBytes, label) => {
+    const cached = cache.get(path);
+    if (cached && cached.expires > Date.now()) return cached.payload;
+    const existing = pending.get(path);
+    if (existing) return existing;
+    const task = readJson(path, maxBytes, label).then((payload) => {
+      if (cache.size >= 128) cache.delete(cache.keys().next().value!);
+      cache.set(path, {
+        payload,
+        expires: Date.now() + (path.includes("/commits/") ? 60_000 : 3_600_000),
+      });
+      return payload;
+    });
+    pending.set(path, task);
+    try {
+      return await task;
+    } finally {
+      pending.delete(path);
+    }
+  };
   return {
+    downloadSnapshot: (owner, repository, slug) =>
+      downloadSkillSnapshot(settings, owner, repository, slug),
     resolveCommit: async (owner, repository, ref) => {
       const payload = recordValue(
         await requestJson(
@@ -91,6 +122,61 @@ export function createGitHubSkillSourceClient(
   };
 }
 
+async function downloadSkillSnapshot(
+  settings: Settings,
+  owner: string,
+  repository: string,
+  slug: string,
+): Promise<readonly SkillLibraryFile[]> {
+  const signal = AbortSignal.timeout(githubRequestTimeoutMs);
+  const response = await pinnedFetch(
+    `https://skills.sh/api/download/${[owner, repository, slug].map(encodeURIComponent).join("/")}`,
+    { headers: { accept: "application/json" }, credentials: "omit", redirect: "manual", signal },
+    settings,
+    { label: "Skill download", requireHttpsOutsideLocalTest: true },
+  );
+  if (!response.ok) {
+    await response.body?.cancel();
+    throw new HTTPException(response.status === 429 ? 429 : 422, {
+      message:
+        response.status === 429
+          ? "skills.sh is busy. Try again shortly."
+          : response.status === 404
+            ? "This skill has no downloadable snapshot. Import its GitHub folder URL instead."
+            : "Could not download this skill from skills.sh. Try again shortly.",
+    });
+  }
+  // JSON escaping may expand the text payload. Artifact validation below applies
+  // the stricter limits to decoded files, paths, and total content size.
+  const payload = recordValue(
+    await readResponseJsonBounded(
+      response,
+      PORTABLE_SKILL_MAX_TOTAL_BYTES * 6 + 128_000,
+      "Skill download",
+      { signal },
+    ),
+    "Skill download",
+  );
+  if (
+    !Array.isArray(payload.files) ||
+    payload.files.length === 0 ||
+    payload.files.length > PORTABLE_SKILL_MAX_FILES
+  ) {
+    throw new HTTPException(422, { message: "The downloaded skill has an invalid file list" });
+  }
+  return payload.files.map((file) => {
+    if (
+      !file ||
+      typeof file !== "object" ||
+      typeof file.path !== "string" ||
+      typeof file.contents !== "string"
+    ) {
+      throw new HTTPException(422, { message: "The downloaded skill contains an invalid file" });
+    }
+    return { path: file.path, content: file.contents };
+  });
+}
+
 async function githubJson(
   settings: Settings,
   path: string,
@@ -118,7 +204,10 @@ async function githubJson(
       await readResponseTextBounded(response, 8_192, `${label} error`).catch(() => undefined);
       if (response.status === 404) throw new Error(`${label} was not found or is not public`);
       if (response.status === 403 || response.status === 429) {
-        throw new Error(`${label} is temporarily unavailable because GitHub limited the request`);
+        throw new HTTPException(429, {
+          message:
+            "GitHub's public request limit has been reached. Skill search is still available; try previewing again after the limit resets.",
+        });
       }
       throw new Error(`${label} failed with HTTP ${response.status}`);
     }

package/src/domain/product-integration-skill.gen.ts

@@ -43,7 +43,7 @@ export const productIntegrationSkillFiles = [
   },
   {
     "path": "references/product-shapes-and-ui.md",
-    "content": "# Product shapes and UI\n\n## Choose the smallest suitable surface\n\nOpenGeni supports several product shapes. Select from the product experience and host stack rather than assuming every integration needs a custom chat:\n\n| Need | Likely surface | Product owns |\n| --- | --- | --- |\n| The complete OpenGeni experience is acceptable | Link or deep-link to stock OpenGeni | Entry point and product navigation |\n| Custom UI in any framework, mobile app, CLI, or automation | OpenGeni SDK or public API behind product backend | All user-facing presentation |\n| React product wants canonical session state without packaged visuals | Headless React session hooks and projections | Components, layout, and styling |\n| React product wants packaged chat/session controls | Focused styled React subpaths | Shell, domain UI, and theming |\n| Product exposes files, changes, terminal, or desktop compute | Optional workbench surfaces | Product shell and selected tabs |\n\nStart with the narrowest surface that preserves the desired experience. Do not mount the full workbench for an ordinary analytics chat. Do not rebuild session streaming, replay, queueing, approval, or timeline projection when a compatible package already supplies the needed behavior.\n\n## Evaluate reuse before writing chat UI\n\nFor React hosts, inspect the installed OpenGeni React package before creating replacement components. Its subpaths are composable, and the styled surfaces use scoped compiled CSS plus runtime theme and density tokens. Compare:\n\n- packaged components with customer theme tokens;\n- headless hooks with customer-native components; and\n- a fully custom SDK-driven UI.\n\nChoose based on UX requirements and dependency compatibility, then record why. Styling differences alone are not a reason to skip reusable components if their structure fits. Conversely, do not force a packaged component when the product needs a materially different interaction model.\n\nFor Svelte, SvelteKit, Vue, native mobile, or another non-React frontend, use the product's native component system. Keep the privileged OpenGeni client on a compatible backend boundary. A SvelteKit server route may use the TypeScript SDK directly; a non-JavaScript backend may use the public HTTP contract or a small compatible adapter. The browser still speaks to authenticated product routes.\n\n## Browser/backend split\n\nThe product browser normally sends product-shaped requests to its own same-origin backend. The backend authenticates, resolves the allowed mapping, and calls OpenGeni. Never bundle an organization key into frontend code.\n\nFor live sessions, preserve event sequence, reconnect, replay, and duplicate suppression. The SDK's stream and proxy helpers are preferred where compatible. Treat unknown additive event types as forward-compatible data rather than crashing the UI.\n\nUploads may send bytes directly to a short-lived signed storage URL returned by the trusted flow. That URL is narrow transfer authority, not the OpenGeni API key. Verify storage CORS for every intended browser origin.\n\n## Decide what the user sees\n\nOpenGeni's durable event stream can support different product projections:\n\n- final answer only;\n- assistant messages plus progress and status;\n- selected tool-call summaries;\n- approvals and structured human-input cards; or\n- a detailed operational timeline.\n\nThe customer frontend chooses which event types and fields to render. Hiding an event from the chat view does not remove it from OpenGeni's durable history or from authorized audit readers. Do not promise data erasure or secrecy from presentation filtering.\n\nEven a final-answer-only UI should surface states the user must act on: failure, cancellation, credit or policy denial, approval requests, human-input requests, reconnect status, and a way to retry safely. Avoid presenting tool failures as ordinary assistant prose when product state can represent them more clearly.\n\n## Fit the host product\n\nFollow existing navigation, accessibility, responsive, loading, error, observability, localization, and design-system conventions. Keep OpenGeni IDs behind product-native identifiers. Make the smallest dependency addition that improves correctness.\n\nThe integration should feel native to the customer product while retaining OpenGeni's session semantics. Framework adaptation is expected; protocol reimplementation is not a goal.\n"
+    "content": "# Opening host-owned workbench tabs\n\nUse `SandboxWorkspace.openTabRequest={{ tab, requestId }}` to open a built-in or\nhost-injected tab from the host's UI. Increment `requestId` for each intentional\nopen, including repeated clicks on the same item. Keep artifact selection and\ninternal-link recognition in the host; the workbench only selects an available\ntab and expands the dock. Preserve modified clicks and external navigation.\nWhen handing off to a full-page artifact route, retain an explicit originating\nsession return path rather than relying on browser history.\n\n# Product shapes and UI\n\n## Choose the smallest suitable surface\n\nOpenGeni supports several product shapes. Select from the product experience and host stack rather than assuming every integration needs a custom chat:\n\n| Need | Likely surface | Product owns |\n| --- | --- | --- |\n| The complete OpenGeni experience is acceptable | Link or deep-link to stock OpenGeni | Entry point and product navigation |\n| Custom UI in any framework, mobile app, CLI, or automation | OpenGeni SDK or public API behind product backend | All user-facing presentation |\n| React product wants canonical session state without packaged visuals | Headless React session hooks and projections | Components, layout, and styling |\n| React product wants packaged chat/session controls | Focused styled React subpaths | Shell, domain UI, and theming |\n| Product exposes files, changes, terminal, or desktop compute | Optional workbench surfaces | Product shell and selected tabs |\n\nStart with the narrowest surface that preserves the desired experience. Do not mount the full workbench for an ordinary analytics chat. Do not rebuild session streaming, replay, queueing, approval, or timeline projection when a compatible package already supplies the needed behavior.\n\n## Evaluate reuse before writing chat UI\n\nFor React hosts, inspect the installed OpenGeni React package before creating replacement components. Its subpaths are composable, and the styled surfaces use scoped compiled CSS plus runtime theme and density tokens. Compare:\n\n- packaged components with customer theme tokens;\n- headless hooks with customer-native components; and\n- a fully custom SDK-driven UI.\n\nChoose based on UX requirements and dependency compatibility, then record why. Styling differences alone are not a reason to skip reusable components if their structure fits. Conversely, do not force a packaged component when the product needs a materially different interaction model.\n\nFor Svelte, SvelteKit, Vue, native mobile, or another non-React frontend, use the product's native component system. Keep the privileged OpenGeni client on a compatible backend boundary. A SvelteKit server route may use the TypeScript SDK directly; a non-JavaScript backend may use the public HTTP contract or a small compatible adapter. The browser still speaks to authenticated product routes.\n\n## Browser/backend split\n\nThe product browser normally sends product-shaped requests to its own same-origin backend. The backend authenticates, resolves the allowed mapping, and calls OpenGeni. Never bundle an organization key into frontend code.\n\nFor live sessions, preserve event sequence, reconnect, replay, and duplicate suppression. The SDK's stream and proxy helpers are preferred where compatible. Treat unknown additive event types as forward-compatible data rather than crashing the UI.\n\nUploads may send bytes directly to a short-lived signed storage URL returned by the trusted flow. That URL is narrow transfer authority, not the OpenGeni API key. Verify storage CORS for every intended browser origin.\n\n## Decide what the user sees\n\nOpenGeni's durable event stream can support different product projections:\n\n- final answer only;\n- assistant messages plus progress and status;\n- selected tool-call summaries;\n- approvals and structured human-input cards; or\n- a detailed operational timeline.\n\nThe customer frontend chooses which event types and fields to render. Hiding an event from the chat view does not remove it from OpenGeni's durable history or from authorized audit readers. Do not promise data erasure or secrecy from presentation filtering.\n\nEven a final-answer-only UI should surface states the user must act on: failure, cancellation, credit or policy denial, approval requests, human-input requests, reconnect status, and a way to retry safely. Avoid presenting tool failures as ordinary assistant prose when product state can represent them more clearly.\n\n## Fit the host product\n\nFollow existing navigation, accessibility, responsive, loading, error, observability, localization, and design-system conventions. Keep OpenGeni IDs behind product-native identifiers. Make the smallest dependency addition that improves correctness.\n\nThe integration should feel native to the customer product while retaining OpenGeni's session semantics. Framework adaptation is expected; protocol reimplementation is not a goal.\n"
   },
   {
     "path": "references/runtime-profile-and-verification.md",

package/src/domain/skill-imports.ts

@@ -19,6 +19,11 @@ export type GitHubSkillTreeEntry = Readonly<{
 }>;
 
 export type GitHubSkillSourceClient = Readonly<{
+  downloadSnapshot?(
+    owner: string,
+    repository: string,
+    slug: string,
+  ): Promise<readonly SkillLibraryFile[]>;
   resolveCommit(owner: string, repository: string, ref: string): Promise<string>;
   listTree(
     owner: string,
@@ -52,6 +57,10 @@ export async function resolveSkillImport(
   client: GitHubSkillSourceClient,
 ): Promise<ResolvedSkillImport> {
   const parsed = parseSkillSource(rawUrl);
+  if (parsed.source === "skills_sh" && client.downloadSnapshot) {
+    const files = await client.downloadSnapshot(parsed.owner, parsed.repository, parsed.skillSlug!);
+    return buildResolvedImport(parsed, files, parsed.skillSlug!, null);
+  }
   const sourceCommit = await client.resolveCommit(parsed.owner, parsed.repository, parsed.ref);
   if (!gitCommit.test(sourceCommit)) {
     throw new HTTPException(422, { message: "GitHub returned an invalid source commit" });
@@ -94,6 +103,15 @@ export async function resolveSkillImport(
     }
     return { path: relativeSkillPath(entry.path, sourcePath), content };
   });
+  return buildResolvedImport(parsed, files, sourcePath, sourceCommit);
+}
+
+function buildResolvedImport(
+  parsed: ParsedSkillSource,
+  files: readonly SkillLibraryFile[],
+  sourcePath: string,
+  commit: string | null,
+): ResolvedSkillImport {
   let artifact;
   try {
     artifact = buildPortableSkillArtifact(files);
@@ -103,8 +121,25 @@ export async function resolveSkillImport(
     });
   }
   const repositoryUrl = `https://github.com/${parsed.owner}/${parsed.repository}`;
-  const sourceUrl =
-    sourcePath === "."
+  // The existing revision field holds our content digest for registry snapshots;
+  // snapshots do not provide a Git commit or a repository-relative folder path.
+  const sourceCommit = commit ?? artifact.contentSha256;
+  if (
+    !commit &&
+    artifact.name
+      .toLowerCase()
+      .replace(/[\s_]+/g, "-")
+      .replace(/[^a-z0-9-]/g, "")
+      .replace(/-+/g, "-")
+      .replace(/^-|-$/g, "") !== parsed.skillSlug!.toLowerCase()
+  ) {
+    throw new HTTPException(422, {
+      message: "The downloaded skill does not match the requested name",
+    });
+  }
+  const sourceUrl = !commit
+    ? `https://skills.sh/${parsed.owner}/${parsed.repository}/${parsed.skillSlug}`
+    : sourcePath === "."
       ? `${repositoryUrl}/tree/${sourceCommit}`
       : `${repositoryUrl}/tree/${sourceCommit}/${encodeGitHubPath(sourcePath)}`;
   const warnings: string[] = [];
@@ -119,6 +154,7 @@ export async function resolveSkillImport(
   }
   return {
     preview: {
+      markdown: artifact.files.find((file) => file.path === "SKILL.md")?.content,
       source: parsed.source,
       sourceUrl,
       repositoryUrl,

package/src/domain/skill-search.ts

@@ -173,6 +173,9 @@ function normalizeResponse(
     if (!isRecord(skill) || typeof skill.id !== "string" || typeof skill.source !== "string")
       throw invalid();
     const parts = skill.id.split("/");
+    // Website-hosted skills cannot use our GitHub import flow. Their presence
+    // must not discard the supported results in the same response.
+    if (parts.length === 2 && skill.source === parts[0]) continue;
     if (
       parts.length !== 3 ||
       !ownerPattern.test(parts[0]!) ||