@opengeni/api-router 2.11.0-canary.0 → 2.11.2-canary.0

package/src/routes/preference-registry.ts

@@ -1,8 +1,5 @@
 import {
-  ActivatePreferenceRegistryRevisionRequest,
   ChangePreferenceRegistryScopeRequest,
-  CorrectPreferenceRegistryRequest,
-  CreatePreferenceRegistryProposalRequest,
   DeactivatePreferenceRegistryRequest,
   PreferenceRegistryConflictResponse,
   PreferenceRegistryDetailResponse,
@@ -11,7 +8,6 @@ import {
   PreferenceRegistryListQuery,
   PreferenceRegistryListResponse,
   PreferenceRegistryMutationResponse,
-  PreferenceRegistryRecord,
   PreferenceRegistrySnapshot,
   RejectPreferenceRegistryProposalRequest,
   SupersedePreferenceRegistryRequest,
@@ -26,10 +22,7 @@ import {
   type ApiRouteDeps,
 } from "@opengeni/core";
 import {
-  activatePreferenceRegistryRevision,
   changePreferenceRegistryScope,
-  correctPreferenceRegistry,
-  createPreferenceRegistryProposal,
   deactivatePreferenceRegistry,
   getOrCreatePreferenceRegistrySnapshot,
   getPreferenceRegistryDetail,
@@ -214,34 +207,20 @@ export function registerPreferenceRegistryRoutes(app: Hono, deps: ApiRouteDeps):
     }
   });
 
-  app.post(`${base}/proposals`, async (context) => {
-    const workspaceId = context.req.param("workspaceId");
-    const access = await requireAccessGrantAuthorization(
-      context,
-      deps,
-      workspaceId,
-      "workspace:read",
-    );
-    const { grant } = access;
-    const request = await parseBody(context, CreatePreferenceRegistryProposalRequest);
-    authorizePreferenceRegistryScopeMutation(access, request.scope);
-    try {
+  // Retain an explicit migration response, not a second single-text writer.
+  for (const path of ["/proposals", "/:preferenceId/activate", "/:preferenceId/correct"]) {
+    app.post(`${base}${path}`, async (context) => {
+      await requireAccessGrant(context, deps, context.req.param("workspaceId"), "workspace:read");
       return context.json(
-        PreferenceRegistryRecord.parse(
-          await createPreferenceRegistryProposal(deps.db, {
-            ...request,
-            accountId: grant.accountId,
-            workspaceId,
-            actorSubjectId: grant.subjectId,
-            principalKind: grant.principalKind,
-          }),
-        ),
-        201,
+        {
+          code: "SKILL_FILE_LIFECYCLE_REQUIRED",
+          message:
+            "Use the Skill content save, approve, or restore API. Skill metadata comes from SKILL.md frontmatter; this legacy endpoint makes no change.",
+        },
+        410,
       );
-    } catch (error) {
-      return preferenceError(context, error);
-    }
-  });
+    });
+  }
 
   app.get(`${base}/summary`, async (context) => {
     const workspaceId = context.req.param("workspaceId");
@@ -300,66 +279,6 @@ export function registerPreferenceRegistryRoutes(app: Hono, deps: ApiRouteDeps):
     }
   });
 
-  app.post(`${base}/:preferenceId/activate`, async (context) => {
-    const workspaceId = context.req.param("workspaceId");
-    const access = await requireAccessGrantAuthorization(
-      context,
-      deps,
-      workspaceId,
-      "workspace:read",
-    );
-    const { grant } = access;
-    const id = preferenceId(context);
-    const request = await parseBody(context, ActivatePreferenceRegistryRevisionRequest);
-    try {
-      return context.json(
-        PreferenceRegistryMutationResponse.parse(
-          await activatePreferenceRegistryRevision(deps.db, {
-            accountId: grant.accountId,
-            workspaceId,
-            actorSubjectId: grant.subjectId,
-            principalKind: grant.principalKind,
-            preferenceId: id,
-            authorizeScope: (scope) => authorizePreferenceRegistryScopeMutation(access, scope),
-            ...request,
-          }),
-        ),
-      );
-    } catch (error) {
-      return preferenceError(context, error);
-    }
-  });
-
-  app.post(`${base}/:preferenceId/correct`, async (context) => {
-    const workspaceId = context.req.param("workspaceId");
-    const access = await requireAccessGrantAuthorization(
-      context,
-      deps,
-      workspaceId,
-      "workspace:read",
-    );
-    const { grant } = access;
-    const id = preferenceId(context);
-    const request = await parseBody(context, CorrectPreferenceRegistryRequest);
-    try {
-      return context.json(
-        PreferenceRegistryMutationResponse.parse(
-          await correctPreferenceRegistry(deps.db, {
-            ...request,
-            accountId: grant.accountId,
-            workspaceId,
-            actorSubjectId: grant.subjectId,
-            principalKind: grant.principalKind,
-            preferenceId: id,
-            authorizeScope: (scope) => authorizePreferenceRegistryScopeMutation(access, scope),
-          }),
-        ),
-      );
-    } catch (error) {
-      return preferenceError(context, error);
-    }
-  });
-
   app.post(`${base}/:preferenceId/scope`, async (context) => {
     const workspaceId = context.req.param("workspaceId");
     const access = await requireAccessGrantAuthorization(

package/src/routes/sessions.ts

@@ -1,3 +1,4 @@
+import { getRetainedProviderCommand } from "@opengeni/db/retained-provider-commands";
 import { scheduledSessionIds } from "@opengeni/db";
 import { withSiteSessionOrigin } from "@opengeni/core";
 import { resolveSiteSessionOrigin } from "../site-session-origin";
@@ -141,8 +142,7 @@ import {
   projectSessionForRelatedAccess,
   recordStreamAcknowledgment,
   requestSessionCompaction,
-  setSessionCodexPinInTransaction,
-  withSessionCodexCapacityMutation,
+  switchSessionCodexAccount,
   setSessionChannel,
   updateSessionVariableSets,
   ChannelNotFoundError,
@@ -181,6 +181,7 @@ import {
   SessionTenancyInvalidRequestError,
   SessionTenancyNotActivatedError,
   HumanInputResponseValidationError,
+  SkillHumanResponseError,
   latestWorkspaceCapture,
   sessionLatestWorkspaceCapture,
   renewSessionRealtimeInTransaction,
@@ -401,8 +402,18 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         message: "pty retained-process identity is stale; reopen the terminal",
       });
     }
+    const providerCommand = await getRetainedProviderCommand(db, {
+      accountId: ctx.accountId,
+      workspaceId: ctx.workspaceId,
+      sessionId: ctx.session.id,
+      processId: process.id,
+    });
     handle.routingSession.adoptRetainedProcess({
-      process: { id: process.id, providerSessionId: process.providerSessionId },
+      process: {
+        id: process.id,
+        providerSessionId: process.providerSessionId,
+        ...(providerCommand ? { providerCommand } : {}),
+      },
       backend: {
         sandboxId: null,
         leaseEpoch: process.leaseEpoch,
@@ -1898,8 +1909,8 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
 
   // Pin (or unpin) the session's Codex account. body { target: "auto" | "<id>" }:
   // "auto" clears the pin (the session follows the workspace active pointer); a
-  // uuid pins the session to that specific account. The pin applies to the NEXT
-  // turn (the worker reads it at turn start). 404 when the session or the target
+  // uuid pins the session to that specific account. Overrides a capacity-blocked
+  // turn; a running attempt keeps its account. 404 when the session or the target
   // account id isn't in the workspace.
   app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/codex-account", async (c) => {
     const workspaceId = c.req.param("workspaceId");
@@ -1924,15 +1935,13 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       }
     }
     const pinned = target === "auto" ? null : target;
-    const mutation = await withSessionCodexCapacityMutation(
-      db,
-      { workspaceId, reason: "codex_manual_session_pin_changed" },
-      async (tx) => {
-        const changed = await setSessionCodexPinInTransaction(tx, workspaceId, sessionId, pinned);
-        return { result: changed, changed };
-      },
-    );
-    const ok = mutation.result;
+    const mutation = await switchSessionCodexAccount(db, {
+      workspaceId,
+      sessionId,
+      credentialId: pinned,
+      subjectId: grant.subjectId,
+    });
+    const ok = mutation.result.changed;
     if (!ok) {
       throw new HTTPException(404, {
         message: "session or codex account not found",
@@ -1958,7 +1967,11 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
             }),
       ),
     );
-    return c.json({ pinned: target === "auto" ? "auto" : target });
+    await publishDurableSessionEvents(bus, workspaceId, sessionId, mutation.result.events);
+    return c.json({
+      pinned: target === "auto" ? "auto" : target,
+      appliedTo: mutation.result.appliedTo,
+    });
   });
 
   // Re-file the session into a workspace channel (rail organization only;
@@ -2740,14 +2753,16 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
       !compact && mode === "forensic" && payloadMode === "full" && dbPage.fullPayloadsExact;
     const page = boundSessionEventHttpPage(projected, {
       direction,
-      eventProjection: forensicExact ? "exact" : "bounded",
+      eventProjection: payloadMode === "full" ? "exact" : "bounded",
       ...(compactProjection
         ? { coveredThroughBySequence: compactProjection.coveredThroughBySequence }
         : {}),
     });
     const hasMore = dbPage.hasMore || page.truncated;
     c.header("X-OpenGeni-Page-Bytes", String(page.bytes));
-    c.header("X-OpenGeni-Page-Max-Bytes", String(1024 * 1024));
+    // One oversized exact event is admitted alone; never advertise a maximum
+    // smaller than the response we actually deliver.
+    c.header("X-OpenGeni-Page-Max-Bytes", String(Math.max(1024 * 1024, page.bytes)));
     c.header("X-OpenGeni-Page-Truncated", String(hasMore));
     c.header("X-OpenGeni-Has-More", String(hasMore));
     c.header("X-OpenGeni-Event-Mode", mode);
@@ -3187,14 +3202,31 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
           requestId: event.payload.requestId,
           response: event.payload.response,
           respondedBy: grant.subjectId,
+          canonicalHumanSession:
+            authorization.canonicalManagedHumanSession || authorization.canonicalLocalHumanSession,
           respondedByKind: childRequiresActionRespondedByKindForGrant(grant),
           clientEventId: event.clientEventId ?? null,
         });
       } catch (error) {
+        if (error instanceof SkillHumanResponseError) {
+          throw new HTTPException(
+            error.code === "conflict" ? 409 : error.code === "forbidden" ? 403 : 422,
+            {
+              message: error.message,
+            },
+          );
+        }
         if (error instanceof HumanInputResponseValidationError) {
-          throw new HTTPException(error.code === "SKIP_NOT_ALLOWED" ? 409 : 422, {
-            message: error.message,
-          });
+          throw new HTTPException(
+            error.code === "HUMAN_AUTH_REQUIRED"
+              ? 403
+              : error.code === "SKIP_NOT_ALLOWED"
+                ? 409
+                : 422,
+            {
+              message: error.message,
+            },
+          );
         }
         throw error;
       }

package/src/routes/skill-content.ts

@@ -0,0 +1,226 @@
+import { z } from "zod";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { SkillFile, type SkillWriteReceipt } from "@opengeni/contracts";
+import {
+  approveSkill,
+  listSkills,
+  readSkill,
+  requireAccessGrant,
+  requireAccessGrantAuthorization,
+  restoreSkill,
+  saveSkill,
+  validateSkillFiles,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import { applySkillFileChanges, buildPortableSkillArtifact } from "@opengeni/runtime/skill-library";
+import { authorizePreferenceRegistryScopeMutation } from "./preference-registry";
+
+const scopeSchema = z.enum(["workspace", "organization", "user"]);
+const saveRequest = z
+  .object({
+    operationId: z.uuid(),
+    skillId: z.uuid(),
+    expectedRevisionId: z.uuid().nullable(),
+    expectedScopeVersion: z.number().int().nonnegative(),
+    scope: scopeSchema.default("workspace"),
+    stableKey: z.string().min(1).max(96),
+    files: z.array(SkillFile).max(128),
+    deletions: z.array(z.string().min(1).max(512)).max(128).default([]),
+    reason: z.string().min(1).max(2000),
+  })
+  .strict();
+const revisionRequest = z
+  .object({
+    operationId: z.uuid(),
+    revisionId: z.uuid(),
+    expectedRevisionId: z.uuid().nullable(),
+    expectedScopeVersion: z.number().int().nonnegative(),
+    reason: z.string().min(1).max(2000),
+  })
+  .strict();
+
+async function parseSkillRequest<S extends z.ZodType>(c: Context, schema: S): Promise<z.infer<S>> {
+  const parsed = schema.safeParse(await c.req.json().catch(() => null));
+  if (!parsed.success) throw new HTTPException(422, { message: "Invalid Skill request" });
+  return parsed.data;
+}
+
+function skillIdentifier(value: string): string {
+  const parsed = z.uuid().safeParse(value);
+  if (!parsed.success)
+    throw new HTTPException(422, { message: "Invalid Skill revision or identity" });
+  return parsed.data;
+}
+
+/** Human folder editing and the legacy Skill admin share scope authorization. */
+export function registerSkillContentRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const base = "/v1/workspaces/:workspaceId/skills/content";
+  app.get(base, async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const query = z
+      .object({
+        limit: z.coerce.number().int().min(1).max(250).default(100),
+        cursor: z.string().max(2048).optional(),
+      })
+      .safeParse(c.req.query());
+    if (!query.success) throw new HTTPException(422, { message: "Invalid Skill list query" });
+    let after: { stableKey: string; id: string } | undefined;
+    if (query.data.cursor !== undefined) {
+      try {
+        after = z
+          .object({ stableKey: z.string().min(1).max(128), id: z.uuid() })
+          .strict()
+          .parse(JSON.parse(Buffer.from(query.data.cursor, "base64url").toString("utf8")));
+      } catch {
+        throw new HTTPException(422, { message: "Invalid Skill list cursor" });
+      }
+    }
+    const rows = await listSkills(
+      deps.db,
+      { accountId: grant.accountId, workspaceId, subjectId: grant.subjectId },
+      { limit: query.data.limit + 1, metadataOnly: true, ...(after ? { after } : {}) },
+    );
+    const page = rows.slice(0, query.data.limit);
+    const last = page.at(-1);
+    return c.json({
+      skills: page.map(({ files: _files, ...summary }) => summary),
+      nextCursor:
+        rows.length > query.data.limit && last
+          ? Buffer.from(JSON.stringify({ stableKey: last.stableKey, id: last.id })).toString(
+              "base64url",
+            )
+          : null,
+    });
+  });
+  app.get(`${base}/:skillId`, async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const skillId = skillIdentifier(c.req.param("skillId"));
+    const revision = c.req.query("revisionId");
+    const revisionId = revision === undefined ? undefined : skillIdentifier(revision);
+    const skill = await readSkill(
+      deps.db,
+      { accountId: grant.accountId, workspaceId, subjectId: grant.subjectId },
+      skillId,
+      revisionId,
+    );
+    if (!skill) throw new HTTPException(404, { message: "Skill not found" });
+    return c.json(skill);
+  });
+  app.post(`${base}/save`, async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "workspace:read");
+    const request = await parseSkillRequest(c, saveRequest);
+    authorizePreferenceRegistryScopeMutation(access, request.scope);
+    const context = {
+      accountId: access.grant.accountId,
+      workspaceId,
+      subjectId: access.grant.subjectId,
+    };
+    const skillId = request.skillId;
+    const current = await readSkill(
+      deps.db,
+      context,
+      skillId,
+      request.expectedRevisionId ?? undefined,
+    );
+    if (request.expectedRevisionId && !current)
+      throw new HTTPException(404, { message: "Skill not found" });
+    if (current) {
+      authorizePreferenceRegistryScopeMutation(access, current.scope);
+      if (current.scope !== request.scope)
+        throw new HTTPException(409, {
+          message: "Move Skill scope through the existing scope-management workflow.",
+        });
+    }
+    let files;
+    try {
+      files = validateSkillFiles(
+        applySkillFileChanges(
+          request.expectedRevisionId ? (current?.files ?? []) : [],
+          request.files,
+          request.deletions,
+        ),
+      );
+      buildPortableSkillArtifact(files);
+    } catch {
+      throw new HTTPException(400, {
+        message:
+          "Invalid Skill folder. SKILL.md requires valid YAML frontmatter with a name and description. Use unique relative text-file paths and respect the file and folder size limits.",
+      });
+    }
+    const receipt = await skillMutation(() =>
+      saveSkill(deps.db, {
+        accountId: context.accountId,
+        workspaceId,
+        actor: { kind: "human", principalKind: "human_session", subjectId: context.subjectId },
+        operationId: request.operationId,
+        skillId,
+        expectedRevisionId: request.expectedRevisionId,
+        expectedScopeVersion: request.expectedScopeVersion,
+        scope: request.scope,
+        stableKey: current?.stableKey ?? request.stableKey,
+        files,
+        reason: request.reason,
+      }),
+    );
+    return c.json(receipt);
+  });
+  for (const operation of ["approve", "restore"] as const) {
+    app.post(`${base}/:skillId/${operation}`, async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "workspace:read");
+      const skillId = skillIdentifier(c.req.param("skillId"));
+      const request = await parseSkillRequest(c, revisionRequest);
+      const current = await readSkill(
+        deps.db,
+        { accountId: access.grant.accountId, workspaceId, subjectId: access.grant.subjectId },
+        skillId,
+      );
+      if (!current) throw new HTTPException(404, { message: "Skill not found" });
+      authorizePreferenceRegistryScopeMutation(access, current.scope);
+      const apply = operation === "approve" ? approveSkill : restoreSkill;
+      return c.json(
+        await skillMutation(() =>
+          apply(deps.db, {
+            ...request,
+            skillId,
+            accountId: access.grant.accountId,
+            workspaceId,
+            actor: {
+              kind: "human",
+              principalKind: "human_session",
+              subjectId: access.grant.subjectId,
+            },
+          }),
+        ),
+      );
+    });
+  }
+}
+
+async function skillMutation(run: () => Promise<SkillWriteReceipt>): Promise<SkillWriteReceipt> {
+  try {
+    return await run();
+  } catch (error) {
+    let current: unknown = error;
+    for (let depth = 0; depth < 4 && current && typeof current === "object"; depth++) {
+      const candidate = current as { code?: unknown; cause?: unknown };
+      if (candidate.code === "23505" || candidate.code === "40001")
+        throw new HTTPException(409, {
+          message:
+            "Skill changed or this operation key was reused. Reload and reconcile the change.",
+        });
+      if (candidate.code === "42501")
+        throw new HTTPException(403, {
+          message: "Skill change is not permitted for this actor or scope.",
+        });
+      if (candidate.code === "22023" || candidate.code === "23514")
+        throw new HTTPException(400, { message: "Skill content or revision request is invalid." });
+      current = candidate.cause;
+    }
+    throw error;
+  }
+}

package/src/routes/skill-install-authority.ts

@@ -0,0 +1,64 @@
+import { SkillActor, type SkillActor as SkillActorType } from "@opengeni/contracts";
+import {
+  requireResolvedAccessGrantAuthorization,
+  type AccessGrantAuthorization,
+} from "@opengeni/core";
+import { HTTPException } from "hono/http-exception";
+
+/** Use authenticated request provenance, never a caller-supplied actor or subject alone. */
+export function skillInstallerActor(access: AccessGrantAuthorization): SkillActorType {
+  const grant = requireResolvedAccessGrantAuthorization(access, access.grant.workspaceId);
+  const metadata = grant.metadata ?? {};
+  const hasAttempt = ["sessionId", "turnId", "attemptId", "executionGeneration"].some(
+    (key) => metadata[key] !== undefined,
+  );
+  if (hasAttempt || grant.principalKind === "agent_attempt") {
+    const parsed = SkillActor.safeParse({
+      kind: "agent",
+      sessionId: metadata.sessionId,
+      turnId: metadata.turnId,
+      attemptId: metadata.attemptId,
+      executionGeneration: metadata.executionGeneration,
+    });
+    if (!parsed.success)
+      throw new HTTPException(403, {
+        message: "Skill installation requires complete signed attempt authority.",
+      });
+    return parsed.data;
+  }
+  if (
+    grant.principalKind === "human_session" &&
+    !grant.serviceInitiator &&
+    !grant.serviceInitiatorContext &&
+    !grant.subjectId.startsWith("api_key:")
+  ) {
+    return { kind: "human", principalKind: "human_session", subjectId: grant.subjectId };
+  }
+  if (
+    grant.principalKind === "service" ||
+    grant.principalKind === "api_key" ||
+    grant.principalKind === "configured_key"
+  ) {
+    return { kind: "service", principalKind: grant.principalKind, subjectId: grant.subjectId };
+  }
+  throw new HTTPException(403, {
+    message:
+      "Skill installation requires authenticated human, service, or complete live-attempt authority.",
+  });
+}
+
+/** Non-Skill component removals remain available to their existing callers. */
+export function skillRemovalActor(access: AccessGrantAuthorization): SkillActorType | undefined {
+  const grant = requireResolvedAccessGrantAuthorization(access, access.grant.workspaceId);
+  if (
+    grant.principalKind !== "human_session" ||
+    grant.serviceInitiator ||
+    grant.serviceInitiatorContext ||
+    grant.subjectId.startsWith("api_key:") ||
+    ["sessionId", "turnId", "attemptId", "executionGeneration"].some(
+      (key) => grant.metadata?.[key] !== undefined,
+    )
+  )
+    return undefined;
+  return skillInstallerActor(access);
+}