@opengeni/core 2.8.0-canary.1 → 2.8.2-canary.1

package/src/domain/skill-search.ts

@@ -0,0 +1,218 @@
+import type { Settings } from "@opengeni/config";
+import { pinnedFetch, readResponseJsonBounded } from "@opengeni/network";
+
+export type PublicSkillSearchInput = Readonly<{
+  query: string;
+  limit?: number;
+  owner?: string;
+}>;
+
+export type PublicSkillSearchResult = Readonly<{
+  provider: "skills_sh";
+  query: string;
+  items: readonly Readonly<{
+    id: string;
+    name: string;
+    source: string;
+    skillId: string;
+    url: string;
+    installs: number;
+  }>[];
+  nextCursor: null;
+}>;
+
+export type PublicSkillSearchClient = Readonly<{
+  search(input: PublicSkillSearchInput): Promise<PublicSkillSearchResult>;
+}>;
+
+export type PublicSkillSearchErrorCode =
+  | "invalid_query"
+  | "rate_limited"
+  | "timeout"
+  | "unavailable"
+  | "invalid_response";
+
+export class PublicSkillSearchError extends Error {
+  constructor(
+    readonly code: PublicSkillSearchErrorCode,
+    message: string,
+    readonly retryAfterSeconds: number | null = null,
+  ) {
+    super(message);
+    this.name = "PublicSkillSearchError";
+  }
+}
+
+// Undocumented, unauthenticated compatibility endpoint used by the official CLI.
+// Verified 2026-09-08 against vercel-labs/skills commit
+// 1682051d48c34f5eb135e6475c1a965dce05e820, src/find.ts. This is NOT the documented
+// /api/v1/skills/search API (which requires Vercel OIDC). Keep this contract behind
+// this adapter: no promised pagination/quota, no CLI dependency or credentials.
+const endpoint = "https://skills.sh/api/search";
+const timeoutMs = 10_000;
+const maxResponseBytes = 256 * 1024;
+const maxResults = 20;
+const ownerPattern = /^[a-z0-9](?:[a-z0-9-]{0,38})$/iu;
+const segmentPattern = /^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$/iu;
+
+export function createPublicSkillSearchClient(
+  settings: Settings,
+  fetcher: typeof pinnedFetch = pinnedFetch,
+): PublicSkillSearchClient {
+  return {
+    async search(input) {
+      const query = input.query.trim();
+      const limit = input.limit ?? maxResults;
+      const owner = input.owner?.trim().toLowerCase();
+      if (
+        query.length < 2 ||
+        query.length > 200 ||
+        /[\u0000-\u001f\u007f]/u.test(query) ||
+        !Number.isSafeInteger(limit) ||
+        limit < 1 ||
+        limit > maxResults ||
+        (owner !== undefined && !ownerPattern.test(owner))
+      ) {
+        throw new PublicSkillSearchError("invalid_query", "Invalid public Skill search parameters");
+      }
+      const url = new URL(endpoint);
+      url.searchParams.set("q", query);
+      url.searchParams.set("limit", String(limit));
+      if (owner) url.searchParams.set("owner", owner);
+      const controller = new AbortController();
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const deadline = new Promise<never>((_, reject) => {
+        timer = setTimeout(() => {
+          controller.abort();
+          reject(new PublicSkillSearchError("timeout", "Public Skill search timed out"));
+        }, timeoutMs);
+      });
+      try {
+        return await Promise.race([
+          deadline,
+          (async () => {
+            const response = await fetcher(
+              url,
+              {
+                method: "GET",
+                headers: { accept: "application/json" },
+                credentials: "omit",
+                redirect: "manual",
+                signal: controller.signal,
+              },
+              settings,
+              { label: "Public Skill search", requireHttpsOutsideLocalTest: true },
+            );
+            if (controller.signal.aborted || !response.ok) {
+              void response.body?.cancel().catch(() => undefined);
+              if (controller.signal.aborted) {
+                throw new PublicSkillSearchError("timeout", "Public Skill search timed out");
+              }
+              if (response.status === 429) {
+                throw new PublicSkillSearchError(
+                  "rate_limited",
+                  "Public Skill search is rate limited",
+                  parseRetryAfter(response.headers.get("retry-after")),
+                );
+              }
+              throw new PublicSkillSearchError("unavailable", "Public Skill search is unavailable");
+            }
+            let payload: unknown;
+            try {
+              payload = await readResponseJsonBounded(
+                response,
+                maxResponseBytes,
+                "Public Skill search",
+                {
+                  signal: controller.signal,
+                },
+              );
+            } catch {
+              throw new PublicSkillSearchError(
+                controller.signal.aborted ? "timeout" : "invalid_response",
+                controller.signal.aborted
+                  ? "Public Skill search timed out"
+                  : "Public Skill search returned an invalid response",
+              );
+            }
+            return normalizeResponse(payload, query, limit, owner);
+          })(),
+        ]);
+      } catch (error) {
+        if (error instanceof PublicSkillSearchError) throw error;
+        throw new PublicSkillSearchError(
+          controller.signal.aborted ? "timeout" : "unavailable",
+          controller.signal.aborted
+            ? "Public Skill search timed out"
+            : "Public Skill search is unavailable",
+        );
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+  };
+}
+
+function normalizeResponse(
+  payload: unknown,
+  query: string,
+  limit: number,
+  owner: string | undefined,
+): PublicSkillSearchResult {
+  const invalid = () =>
+    new PublicSkillSearchError(
+      "invalid_response",
+      "Public Skill search returned an invalid response",
+    );
+  if (!isRecord(payload) || !Array.isArray(payload.skills) || payload.skills.length > maxResults) {
+    throw invalid();
+  }
+  const seen = new Set<string>();
+  const items: PublicSkillSearchResult["items"][number][] = [];
+  for (const skill of payload.skills) {
+    if (!isRecord(skill) || typeof skill.id !== "string" || typeof skill.source !== "string")
+      throw invalid();
+    const parts = skill.id.split("/");
+    if (
+      parts.length !== 3 ||
+      !ownerPattern.test(parts[0]!) ||
+      !parts.every((part) => segmentPattern.test(part)) ||
+      skill.source !== parts.slice(0, 2).join("/") ||
+      (skill.skillId !== undefined && skill.skillId !== parts[2]) ||
+      typeof skill.name !== "string" ||
+      !skill.name.trim() ||
+      skill.name.length > 200 ||
+      /[\u0000-\u001f\u007f]/u.test(skill.name) ||
+      typeof skill.installs !== "number" ||
+      !Number.isSafeInteger(skill.installs) ||
+      skill.installs < 0 ||
+      (owner !== undefined && parts[0]!.toLowerCase() !== owner)
+    )
+      throw invalid();
+    if (seen.has(skill.id)) continue;
+    seen.add(skill.id);
+    items.push({
+      id: skill.id,
+      name: skill.name.trim(),
+      source: skill.source,
+      skillId: parts[2]!,
+      url: `https://skills.sh/${parts.map(encodeURIComponent).join("/")}`,
+      installs: skill.installs,
+    });
+  }
+  return { provider: "skills_sh", query, items: items.slice(0, limit), nextCursor: null };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseRetryAfter(value: string | null): number | null {
+  if (value === null) return null;
+  if (/^\d+$/u.test(value)) {
+    const seconds = Number(value);
+    return Number.isSafeInteger(seconds) ? seconds : null;
+  }
+  const date = Date.parse(value);
+  return Number.isFinite(date) ? Math.max(0, Math.ceil((date - Date.now()) / 1000)) : null;
+}

package/src/domain/skills.ts

@@ -0,0 +1,87 @@
+import type {
+  SkillFile,
+  SkillInstallInput,
+  SkillRevisionInput,
+  SkillSaveInput,
+} from "@opengeni/contracts";
+import { validateSkillTextFiles } from "@opengeni/contracts";
+import { buildPortableSkillArtifact } from "@opengeni/runtime/skill-library";
+import {
+  applySkillLifecycle,
+  listSkillRecords,
+  skillFilesContentHash,
+  type Database,
+  type SkillReadContext,
+} from "@opengeni/db";
+export { replayPortableSkillInstall } from "@opengeni/db";
+
+/** Canonical text-only folder; rejects invalid Unicode before PostgreSQL conversion. */
+export function validateSkillFiles(files: readonly SkillFile[]): SkillFile[] {
+  validateSkillTextFiles(files);
+  const result = files.map(({ path, content }) => ({ path, content }));
+  if (!result.some((file) => file.path === "SKILL.md" && file.content.trim()))
+    throw new Error("Skill requires nonempty SKILL.md");
+  return result.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+
+/** Separate from the historical SKILL.md hash, which must never be rewritten. */
+export function skillBundleHash(files: readonly SkillFile[]): string {
+  return skillFilesContentHash(validateSkillFiles(files));
+}
+
+export const listSkills = listSkillRecords;
+export async function readSkill(
+  db: Database,
+  context: SkillReadContext,
+  skillId: string,
+  revisionId?: string,
+) {
+  return (
+    (
+      await listSkillRecords(db, context, {
+        skillId,
+        ...(revisionId ? { revisionId } : {}),
+        limit: 1,
+      })
+    )[0] ?? null
+  );
+}
+export async function saveSkill(db: Database, input: SkillSaveInput) {
+  const { accountId, workspaceId, actor, ...request } = input;
+  const artifact = buildPortableSkillArtifact(validateSkillFiles(input.files));
+  return applySkillLifecycle(
+    db,
+    { accountId, workspaceId, actor },
+    {
+      ...request,
+      operation: "save",
+      files: artifact.files,
+      title: artifact.name,
+      description: artifact.description,
+    },
+  );
+}
+export async function installSkill(db: Database, input: SkillInstallInput) {
+  const { accountId, workspaceId, actor, ...request } = input;
+  return applySkillLifecycle(
+    db,
+    { accountId, workspaceId, actor },
+    { ...request, operation: "install" },
+  );
+}
+export async function approveSkill(db: Database, input: SkillRevisionInput) {
+  const { accountId, workspaceId, actor, ...request } = input;
+  return applySkillLifecycle(
+    db,
+    { accountId, workspaceId, actor },
+    { ...request, operation: "approve" },
+  );
+}
+export async function restoreSkill(db: Database, input: SkillRevisionInput) {
+  const { accountId, workspaceId, actor, ...request } = input;
+  return applySkillLifecycle(
+    db,
+    { accountId, workspaceId, actor },
+    { ...request, operation: "restore" },
+  );
+}

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from "./domain/skills";
 // @opengeni/core — the framework-agnostic OpenGeni core.
 //
 // WHAT THIS PACKAGE IS: the OpenGeni domain, access, and billing layers carved
@@ -71,6 +72,8 @@ export * from "./billing/limits";
 export * from "./domain/capabilities";
 export * from "./domain/host-mcp-authority-source-admission";
 export * from "./domain/skill-imports";
+export * from "./domain/skill-search";
+export * from "./domain/github-skill-source";
 export * from "./domain/environments";
 export * from "./rigs";
 export * from "./domain/packs";

package/src/sandbox/routing.ts

@@ -12,6 +12,11 @@
 // over the events bus) lives here, not in the leaf (which stays db-free).
 
 import { sandboxLifecycleTransitionWaitMs, type Settings } from "@opengeni/config";
+import { appendSessionCommandOutput } from "@opengeni/db/session-command-output";
+import {
+  createProviderCommandRetainer,
+  retainedProviderCommandPersistence,
+} from "@opengeni/db/retained-provider-commands";
 import {
   advanceWorkspaceGenerationForDirectRequest,
   advanceWorkspaceGenerationForRetainedProcess,
@@ -21,6 +26,7 @@ import {
   markWarmLeaseInstanceLost,
   readActiveSandbox,
   retainWorkspaceMutationProcess,
+  SandboxRetainedProcessPromotionFencedError,
   retainedProcessSettlementIdentity,
   settleRetainedProcess,
   verifyDirectWorkspaceMutationSettlement,
@@ -58,6 +64,11 @@ type PersistableMutationAdmission = {
   > | null;
 };
 
+const retainWorkspaceProviderCommand = createProviderCommandRetainer(
+  retainWorkspaceMutationProcess,
+  (error) => (error instanceof SandboxRetainedProcessPromotionFencedError ? error.process : null),
+);
+
 type DirectRetainedProcessRoute = {
   providerSessionId: number;
   providerBackend: string;
@@ -310,12 +321,15 @@ export function wrapChannelABoxWithRouting(
           throw new Error("API-direct workspace mutation settlement lacked its bound admission");
         }
         if (outcome === "resolved" && retainedProcess) {
-          await retainWorkspaceMutationProcess(db, {
+          await retainWorkspaceProviderCommand(db, {
             accountId: ids.accountId,
             workspaceId: ids.workspaceId,
             sessionId: ids.sessionId,
             processId: retainedProcess.id,
             providerSessionId: retainedProcess.providerSessionId,
+            ...(retainedProcess.providerCommand
+              ? { providerCommand: retainedProcess.providerCommand }
+              : {}),
             admissionId: exactAdmission.id,
             admittedWorkspaceGeneration: exactAdmission.workspaceGeneration,
             operation: op,
@@ -516,6 +530,31 @@ export function wrapChannelABoxWithRouting(
   });
 
   const proxy = new RoutingSandboxSession({
+    providerCommandHandle: (value) =>
+      value && typeof value === "object"
+        ? (value as PersistableMutationAdmission).admission?.workspaceGeneration
+        : undefined,
+    providerCommandPersistence: (process) =>
+      retainedProviderCommandPersistence(db, {
+        accountId: ids.accountId,
+        workspaceId: ids.workspaceId,
+        sessionId: ids.sessionId,
+        processId: process.id,
+      }),
+    captureProcessOutput: async ({ process, chunkId, chunk, stream, streamFidelity }) => {
+      const events = await appendSessionCommandOutput(db, {
+        accountId: ids.accountId,
+        workspaceId: ids.workspaceId,
+        sessionId: ids.sessionId,
+        commandId: process.id,
+        chunkId,
+        chunk,
+        stream,
+        streamFidelity,
+      });
+      if (events.length && bus)
+        await bus.publish(ids.workspaceId, ids.sessionId, events).catch(() => undefined);
+    },
     bindActiveRouteOnFirstResolve: true,
     defaultResolved: {
       session: established.session as RoutableBackendSession,

package/src/sandbox/runtime-settings.ts

@@ -1,6 +1,7 @@
 import type { Settings } from "@opengeni/config";
 import {
   CapabilityPack,
+  StoredCapabilityPack,
   type RigVersion,
   type Session,
   type SandboxBackend,
@@ -72,8 +73,14 @@ export async function resolveWorkspaceLegacyRuntimePacks(
       continue;
     }
     const registration = await getWorkspacePack(db, workspaceId, installation.packId);
-    const parsed = CapabilityPack.safeParse(registration?.pack);
-    if (parsed.success) packs.push(parsed.data);
+    if (!registration)
+      throw new Error(`Enabled Pack ${installation.packId} has no registered manifest`);
+    const parsed = StoredCapabilityPack.safeParse(registration.pack);
+    if (!parsed.success)
+      throw new Error(
+        `Enabled Pack ${installation.packId} requires repair: ${parsed.error.message}`,
+      );
+    packs.push(parsed.data);
   }
   return packs;
 }

package/src/transcription.ts

@@ -31,6 +31,9 @@ export type TranscriptionRequest = {
   providerDeadlineAt?: Date | undefined;
   /** Exact provider selected before a resumable segment is first sent upstream. */
   providerId?: string | undefined;
+  preferredProvider?: string | null | undefined;
+  fallbackEnabled?: boolean | undefined;
+  excludedProviders?: readonly string[] | undefined;
 };
 
 export type TranscriptionResult = TranscribeAudioResponse & {
@@ -44,18 +47,22 @@ export class TranscriptionServiceError extends Error {
   readonly code: VoiceInputErrorCode;
   readonly status: number;
   readonly retryable: boolean;
+  /** Explicit rejection before any transcription result; safe to try another provider. */
+  readonly fallbackSafe: boolean;
 
   constructor(input: {
     code: VoiceInputErrorCode;
     message: string;
     status?: number;
     retryable?: boolean;
+    fallbackSafe?: boolean;
   }) {
     super(input.message);
     this.name = "TranscriptionServiceError";
     this.code = input.code;
     this.status = input.status ?? statusForVoiceInputError(input.code);
     this.retryable = input.retryable ?? false;
+    this.fallbackSafe = input.fallbackSafe ?? false;
   }
 }
 
@@ -88,6 +95,10 @@ export function statusForVoiceInputError(code: VoiceInputErrorCode): number {
 
 /** Optional workspace scope for readiness checks during provider selection. */
 export type TranscriptionAvailabilityContext = {
+  afterProvider?: string | undefined;
+  preferredProvider?: string | null | undefined;
+  fallbackEnabled?: boolean | undefined;
+  excludedProviders?: readonly string[] | undefined;
   workspaceId?: string | undefined;
   subjectId?: string | undefined;
 };
@@ -95,7 +106,8 @@ export type TranscriptionAvailabilityContext = {
 /**
  * Extensible transcription provider port. Implementations own credentials and
  * upstream request shape. Selection happens before audio is sent; providers must
- * not fall back to another vendor after an upstream request may have started.
+ * only fall back after an explicit rejection and before any successful or
+ * uncertain provider attempt. Recording persistence owns that eligibility.
  */
 export type TranscriptionProvider = {
   readonly id: string;