@opengeni/api-router 2.13.0-canary.2 → 3.0.0-canary.0

package/dist/index.js

@@ -7,7 +7,7 @@ import {
   createOpenGeniSlackBotInteractionClient,
   startSlackInteractionPump,
   startTemporalScheduleCleanupPump
-} from "./chunk-K2NU4KRK.js";
+} from "./chunk-7IAWEYBH.js";
 
 // src/index.ts
 import { scheduledTaskKnowledgeSource } from "@opengeni/contracts";

package/dist/routes/artifact-catalog.d.ts

@@ -0,0 +1,6 @@
+import { type ApiRouteDeps } from "@opengeni/core";
+import type { Hono } from "hono";
+import { type EditableArtifactRouteDependencies } from "./editable-artifacts.js";
+type Dependencies = ApiRouteDeps & EditableArtifactRouteDependencies;
+export declare function registerArtifactCatalogRoutes(app: Hono, deps: Dependencies): void;
+export {};

package/dist/routes/editable-artifacts.d.ts

@@ -42,3 +42,5 @@ export declare class EditableArtifactApplicationError extends Error {
 }
 export declare function registerEditableArtifactRoutes(app: Hono, deps: EditableArtifactRouteDependencies): void;
 export declare function editableArtifactActorForGrant(grant: AccessGrant, rawReplicaId: string): EditableArtifactRouteActor;
+export declare function isInvisibleListCandidate(error: unknown): boolean;
+export declare function editableArtifactHttpError(error: unknown): unknown;

package/dist/sandbox-file-artifacts.d.ts

@@ -1,5 +1,6 @@
 import { SandboxFileArtifactReceipt, type AccessGrant, type Session } from "@opengeni/contracts";
 import { type ApiRouteDeps, type AccessGrantAuthorization } from "@opengeni/core";
+import { getFile } from "@opengeni/db";
 /** Original bytes inherit the already-authorized source session's ownership. */
 export declare function publishSandboxFileArtifact(deps: ApiRouteDeps, input: Parameters<typeof publishSandboxFileArtifactInScope>[1]): Promise<SandboxFileArtifactReceipt>;
 declare function publishSandboxFileArtifactInScope(deps: ApiRouteDeps, input: {
@@ -12,4 +13,22 @@ declare function publishSandboxFileArtifactInScope(deps: ApiRouteDeps, input: {
 export declare function sandboxArtifactRelativePath(value: string): string;
 export declare function sandboxArtifactSafeFilename(filename: string): string;
 export declare function sandboxFileContentType(filename: string): string;
+export declare function sandboxArtifactIdentity(input: {
+    workspaceId: string;
+    sessionId: string;
+    path: string;
+    sha256: string;
+}): {
+    fileId: string;
+    uploadId: string;
+};
+export declare function assertSandboxArtifactFile(file: NonNullable<Awaited<ReturnType<typeof getFile>>>, expected: {
+    filename: string;
+    safeFilename: string;
+    contentType: string;
+    sizeBytes: number;
+    sha256: string;
+    bucket: string;
+    objectKey: string;
+}): void;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/api-router",
-  "version": "2.13.0-canary.2",
+  "version": "3.0.0-canary.0",
   "description": "OpenGeni HTTP surface: the Hono adapter/router (createApp), routes, MCP HTTP transport, and HTTP access adapters over @opengeni/core. An engine-distribution surface — its runtime closure includes engine-internal packages.",
   "license": "Apache-2.0",
   "repository": {
@@ -43,24 +43,24 @@
     "@hono/zod-validator": "^0.7.6",
     "@llamaindex/liteparse": "2.14.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/agent-proto": "^0.6.0-canary.2",
-    "@opengeni/artifact-tool": "^0.3.27-canary.2",
-    "@opengeni/capabilities": "^0.3.3-canary.14",
-    "@opengeni/codemode": "^0.5.7-canary.2",
-    "@opengeni/codex": "^0.2.22-canary.14",
-    "@opengeni/config": "^1.2.0-canary.2",
-    "@opengeni/contracts": "^3.1.0-canary.2",
-    "@opengeni/core": "^2.10.0-canary.2",
-    "@opengeni/db": "^4.4.0-canary.2",
-    "@opengeni/documents": "^0.8.28-canary.2",
-    "@opengeni/events": "^0.4.26-canary.2",
-    "@opengeni/github": "^0.7.11-canary.2",
-    "@opengeni/network": "^0.3.1-canary.14",
-    "@opengeni/observability": "^0.8.27-canary.2",
-    "@opengeni/runtime": "^2.6.0-canary.2",
-    "@opengeni/storage": "^0.2.128-canary.2",
-    "@opengeni/tool-gateway": "^0.1.8-canary.2",
-    "@opengeni/xai-subscription": "^0.1.4-canary.14",
+    "@opengeni/agent-proto": "^0.6.0-canary.3",
+    "@opengeni/artifact-tool": "^0.3.28-canary.0",
+    "@opengeni/capabilities": "^0.3.3-canary.15",
+    "@opengeni/codemode": "^0.5.8-canary.0",
+    "@opengeni/codex": "^0.2.23-canary.0",
+    "@opengeni/config": "^1.2.1-canary.0",
+    "@opengeni/contracts": "^4.0.0-canary.0",
+    "@opengeni/core": "^3.0.0-canary.0",
+    "@opengeni/db": "^5.0.0-canary.0",
+    "@opengeni/documents": "^0.8.29-canary.0",
+    "@opengeni/events": "^0.4.27-canary.0",
+    "@opengeni/github": "^0.7.12-canary.0",
+    "@opengeni/network": "^0.3.1-canary.15",
+    "@opengeni/observability": "^0.8.28-canary.0",
+    "@opengeni/runtime": "^3.0.0-canary.0",
+    "@opengeni/storage": "^0.2.129-canary.0",
+    "@opengeni/tool-gateway": "^0.1.9-canary.0",
+    "@opengeni/xai-subscription": "^0.1.4-canary.15",
     "@temporalio/client": "^1.17.0",
     "better-auth": "^1.6.14",
     "hono": "^4.12.18",

package/src/app.ts

@@ -195,6 +195,7 @@ import { registerCompanyBrainRoutes } from "./routes/company-brain";
 import { registerSlackTaskPolicyRoutes } from "./routes/slack-task-policy";
 import { registerWorkspaceStateRoutes } from "./routes/workspace-state";
 import { registerWorkspaceArtifactRoutes } from "./routes/workspace-artifacts";
+import { registerArtifactCatalogRoutes } from "./routes/artifact-catalog";
 import { registerPreferenceRegistryRoutes } from "./routes/preference-registry";
 import { registerInsightsRoutes } from "./routes/insights";
 import { registerTranscriptionRoutes } from "./routes/transcriptions";
@@ -1248,6 +1249,7 @@ export function createAppComposition(deps: AppDependencies): {
   registerWorkspaceStateRoutes(app, routeDeps);
   registerMemorySlackPublicationRoutes(app, routeDeps);
   registerWorkspaceArtifactRoutes(app, routeDeps);
+  registerArtifactCatalogRoutes(app, routeDeps);
   registerPreferenceRegistryRoutes(app, routeDeps);
   registerSocialRoutes(app, routeDeps);
   registerPersonalGitHubRoutes(app, routeDeps);

package/src/artifact-catalog-cursor.ts

@@ -0,0 +1,60 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { ArtifactCatalogKind } from "@opengeni/contracts";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+
+const Cursor = z
+  .object({
+    version: z.literal(1),
+    snapshotAt: z.string().datetime(),
+    expiresAt: z.number().int().positive(),
+    after: z
+      .object({
+        key: z.string().max(4096),
+        kind: ArtifactCatalogKind,
+        id: z.string().min(1).max(128),
+      })
+      .strict(),
+  })
+  .strict();
+export type ArtifactCatalogCursor = z.infer<typeof Cursor>;
+
+/** Encrypted as well as authenticated: a scan frontier may name a denied row.
+ * Binding includes principal, workspace, owner context, permissions and filters.
+ */
+export function artifactCatalogCursorCodec(secret: string, binding: string) {
+  const key = createHash("sha256").update("opengeni:artifact-catalog:v1\0").update(secret).digest();
+  const aad = createHash("sha256").update(binding).digest();
+  return {
+    encode(value: ArtifactCatalogCursor): string {
+      const iv = randomBytes(12);
+      const cipher = createCipheriv("aes-256-gcm", key, iv);
+      cipher.setAAD(aad);
+      const bytes = Buffer.concat([
+        cipher.update(JSON.stringify(Cursor.parse(value)), "utf8"),
+        cipher.final(),
+      ]);
+      return Buffer.concat([iv, cipher.getAuthTag(), bytes]).toString("base64url");
+    },
+    decode(value: string): ArtifactCatalogCursor {
+      try {
+        if (value.length > 8192 || !/^[A-Za-z0-9_-]+$/.test(value)) throw new Error();
+        const bytes = Buffer.from(value, "base64url");
+        if (bytes.length < 29 || bytes.toString("base64url") !== value) throw new Error();
+        const decipher = createDecipheriv("aes-256-gcm", key, bytes.subarray(0, 12));
+        decipher.setAAD(aad);
+        decipher.setAuthTag(bytes.subarray(12, 28));
+        const parsed = Cursor.parse(
+          JSON.parse(
+            Buffer.concat([decipher.update(bytes.subarray(28)), decipher.final()]).toString("utf8"),
+          ),
+        );
+        if (parsed.expiresAt <= Date.now() || Date.parse(parsed.snapshotAt) > Date.now() + 60_000)
+          throw new Error();
+        return parsed;
+      } catch {
+        throw new HTTPException(422, { message: "Invalid or expired artifact catalog cursor" });
+      }
+    },
+  };
+}

package/src/integrations/api-integrations.ts

@@ -10,6 +10,7 @@ import {
   googleDiscoveryToOpenApi,
   integrationDefinitionById,
   parseOpenApiDocument,
+  MAX_CURATED_INTEGRATION_SPEC_BYTES,
   type IntegrationCredentialResolver,
   type IntegrationInvocationAuthority,
   type IntegrationTransport,
@@ -22,8 +23,6 @@ import {
 } from "@opengeni/contracts";
 import type { StoredApiIntegrationRevision } from "@opengeni/db";
 
-const MAX_CURATED_DEFINITION_SOURCE_BYTES = 64 * 1024 * 1024;
-
 export type ApiIntegrationConnectionDescriptor = {
   id: string;
   kind: "oauth2" | "api_key" | "app_install" | "delegated";
@@ -86,13 +85,18 @@ async function resolveDefinition(
   const bytes = await fetchIntegrationSourceDocument(
     input.transport,
     definition.source.url,
-    MAX_CURATED_DEFINITION_SOURCE_BYTES,
+    MAX_CURATED_INTEGRATION_SPEC_BYTES,
   );
   let document: Record<string, unknown>;
   if (definition.source.kind === "google_discovery") {
     document = googleDiscoveryToOpenApi(JSON.parse(new TextDecoder().decode(bytes)));
   } else {
-    document = filterOpenApiDocumentForDefinition(parseOpenApiDocument(bytes), definition);
+    document = filterOpenApiDocumentForDefinition(
+      parseOpenApiDocument(bytes, {
+        maxBytes: MAX_CURATED_INTEGRATION_SPEC_BYTES,
+      }),
+      definition,
+    );
   }
   const identity = integrationInstallationIdentity("openapi", definition.id, definition.source.url);
   const revision = compileOpenApiRevision(document, {
@@ -100,6 +104,9 @@ async function resolveDefinition(
     sourceUrl: definition.source.url,
     baseUrl: definition.baseUrl,
     provider: definition.provider.id,
+    ...(definition.source.kind === "openapi" && definition.source.schemaMode
+      ? { schemaMode: definition.source.schemaMode }
+      : {}),
   });
   const baseUrl = firstOpenApiServerUrl(revision);
   const providerDomain = definition.provider.domain;
@@ -229,6 +236,12 @@ function resolvedPreview(input: {
   requiredScopes: string[];
   authScheme: Record<string, unknown>;
 }): ResolvedApiIntegrationPreview {
+  // Include whitespace headroom for PostgreSQL jsonb::text when estimating size.
+  // The database constraint remains authoritative. Refuse during preview,
+  // before the execute-once installation claims an operation it cannot persist.
+  if (Buffer.byteLength(JSON.stringify(input.revision, null, 2), "utf8") > 4 * 1024 * 1024) {
+    throw new Error("Compiled integration exceeds the supported 4 MiB storage limit");
+  }
   const deprecated = input.revision.tools.filter((tool) => tool.deprecated).length;
   const warnings = [
     ...(deprecated > 0

package/src/mcp/knowledge-entries.ts

@@ -74,7 +74,7 @@ export function registerKnowledgeEntryTools(
               : state === "42501"
                 ? "The instruction change is unavailable in this task's scope or Agent learning policy. Off disables authoring, not the task. Do not ask for approval to continue."
                 : state === "22023" || state === "23514"
-                  ? "Invalid instruction change. Read the current instruction, use append for a new rule, edit with one exact oldText match to update or remove text, and replace only when the user explicitly wants the complete instruction replaced. The resulting instruction must stay within 600 characters."
+                  ? "Invalid instruction change. Read the current instruction, use append for a new rule, or edit with one localized exact oldText match to update or remove text. Agents cannot replace the complete instruction. The resulting instruction must stay within 600 characters."
                   : "Workspace instructions are temporarily unavailable. Retry the same operation ID only if the prior change may have succeeded."
           : state === "40001"
             ? "This entry changed. Read its current revision and retry your correction with the current version."
@@ -259,7 +259,7 @@ export function registerKnowledgeEntryTools(
     "instruction_policy_save",
     {
       description:
-        "Change a concise standing workspace instruction through this task's Agent learning policy. Read the current policy first and submit its exact baseline. Use editMode=append by default for a new rule; it preserves the current content and adds one blank-line separator. Use edit with oldText that occurs exactly once and newText to update or remove existing text. Use replace only when the user explicitly asks to replace the complete instruction; never reconstruct or summarize unrelated rules. Each supplied text and the resulting instruction are limited to 600 characters. Facts and incidents belong in knowledge_save and reusable procedures in skill_save. Review first saves an inactive revision and returns pending; continue the task without an approval question.",
+        "Change a concise standing workspace instruction through this task's Agent learning policy. Read the current policy first and submit its exact baseline. Use editMode=append by default for a new rule; it preserves the current content and adds one blank-line separator. Use edit with a localized oldText that occurs exactly once and newText to update or remove only that passage. Agents cannot replace the complete instruction; direct the user to the manual workspace-instruction editor for a whole-policy rewrite. Each supplied text and the resulting instruction are limited to 600 characters. Facts and incidents belong in knowledge_save and reusable procedures in skill_save. Review first saves an inactive revision and returns pending; continue the task without an approval question.",
       inputSchema: AgentInstructionSaveRequest.shape,
     },
     (input) => run((context) => saveAgentInstruction(deps.db, context, input), "instruction"),

package/src/routes/artifact-catalog.ts

@@ -0,0 +1,279 @@
+import { resolveFirstPartyDelegationSecret } from "@opengeni/config";
+import {
+  ArtifactCatalogItem,
+  ArtifactCatalogKind,
+  ArtifactCatalogListQuery,
+  ArtifactCatalogListResponse,
+  retainedArtifactReferenceFromFile,
+  retainedGeneratedImageReferenceFromFile,
+  type AccessGrant,
+} from "@opengeni/contracts";
+import {
+  editableArtifactId,
+  editableArtifactScope,
+  fileOwnerContextForAccess,
+  grantHasAgentAttemptAuthority,
+  hasPermission,
+  requireAccessGrantAuthorization,
+  requireLiveAgentAttemptAuthorization,
+  requireSessionAuthorization,
+  SessionAuthorizationDeniedError,
+  SessionAuthorizationUnavailableError,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import {
+  getFilesForSubject,
+  getGeneratedImageArtifact,
+  getSessionAuthorityProjection,
+  listArtifactCatalogCandidates,
+  withSessionRlsActorContext,
+  type ArtifactCatalogCandidate,
+  type ArtifactCatalogPosition,
+  type SessionRlsActorContext,
+} from "@opengeni/db";
+import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { artifactCatalogCursorCodec } from "../artifact-catalog-cursor";
+import {
+  editableArtifactActorForGrant,
+  editableArtifactHttpError,
+  isInvisibleListCandidate,
+  type EditableArtifactRouteDependencies,
+} from "./editable-artifacts";
+import { fileAuthoritySubjectIdForGrant } from "./files";
+
+type Dependencies = ApiRouteDeps & EditableArtifactRouteDependencies;
+const editableKinds = new Set(["document", "spreadsheet", "presentation"]);
+const CANDIDATE_BATCH = 200;
+const MAX_BATCHES = 10;
+const iso = (value: Date | string) => new Date(value).toISOString();
+const position = (row: ArtifactCatalogCandidate): ArtifactCatalogPosition => ({
+  key: row.sort_key,
+  kind: row.kind,
+  id: row.id,
+});
+
+export function registerArtifactCatalogRoutes(app: Hono, deps: Dependencies): void {
+  app.get("/v1/workspaces/:workspaceId/artifact-catalog", async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(context, deps, workspaceId);
+    const grant = authorization.grant;
+    const parsed = ArtifactCatalogListQuery.safeParse(context.req.query());
+    if (!parsed.success)
+      throw new HTTPException(422, { message: "Invalid artifact catalog query" });
+    const query = parsed.data;
+    const artifactsAllowed = hasPermission(grant.permissions, "artifacts:read");
+    const filesAllowed = hasPermission(grant.permissions, "files:read");
+    if (!artifactsAllowed && !filesAllowed)
+      throw new HTTPException(403, { message: "Artifact catalog read access required" });
+    let kinds = ArtifactCatalogKind.options.filter(
+      (kind) =>
+        (kind === "image" || kind === "file" ? filesAllowed : artifactsAllowed) &&
+        (!query.kind || kind === query.kind),
+    );
+    if (!deps.editableArtifacts) {
+      if (query.kind && editableKinds.has(query.kind) && artifactsAllowed)
+        throw new HTTPException(503, { message: "Editable artifacts are unavailable" });
+      kinds = kinds.filter((kind) => !editableKinds.has(kind));
+    }
+    const includesFiles = kinds.includes("file") || kinds.includes("image");
+    const actor: SessionRlsActorContext = includesFiles
+      ? await fileOwnerContextForAccess(deps, authorization, "files:read")
+      : { subjectId: grant.subjectId, privateFileOwnerSubjectId: null };
+    // Session visibility follows the frozen live initiator independently of
+    // which artifact domains were selected. Never infer it from token labels
+    // or require file ownership merely to discover Sites/editable artifacts.
+    if (grantHasAgentAttemptAuthority(grant) && actor.initiatingHumanSubjectId === undefined) {
+      const callerSessionId = grant.metadata?.["sessionId"];
+      try {
+        if (typeof callerSessionId !== "string")
+          throw new SessionAuthorizationDeniedError("caller_stale");
+        const attempt = await requireLiveAgentAttemptAuthorization(deps.db, grant, callerSessionId);
+        actor.initiatingHumanSubjectId = attempt.initiatingHumanSubjectId;
+      } catch (error) {
+        if (error instanceof SessionAuthorizationDeniedError)
+          throw new HTTPException(404, { message: "Session not found", cause: error });
+        throw error;
+      }
+    }
+    const sourceDecisions = new Map<string, boolean>();
+    const canReadSession = async (sessionId: string): Promise<boolean> => {
+      if (!hasPermission(grant.permissions, "sessions:read")) return false;
+      if (sourceDecisions.has(sessionId)) return sourceDecisions.get(sessionId)!;
+      try {
+        await requireSessionAuthorization(deps, grant, {
+          sessionId,
+          operation: "session.read",
+          surface: "http",
+        });
+        // The optional-host seam can return null for both a shared standalone
+        // session and an RLS-hidden/missing row. Prove visibility independently
+        // AFTER it, so a permissive null is never itself provenance authority.
+        if (!(await getSessionAuthorityProjection(deps.db, workspaceId, sessionId))) {
+          sourceDecisions.set(sessionId, false);
+          return false;
+        }
+        sourceDecisions.set(sessionId, true);
+        return true;
+      } catch (error) {
+        if (error instanceof SessionAuthorizationDeniedError) {
+          sourceDecisions.set(sessionId, false);
+          return false;
+        }
+        if (error instanceof SessionAuthorizationUnavailableError)
+          throw new HTTPException(503, { message: "Session authorization is unavailable" });
+        throw error;
+      }
+    };
+    context.header("cache-control", "private, no-store");
+    return withSessionRlsActorContext(actor, async () => {
+      if (query.sourceSessionId && !(await canReadSession(query.sourceSessionId)))
+        throw new HTTPException(404, { message: "Session not found" });
+      const secret = resolveFirstPartyDelegationSecret(deps.settings);
+      if (!secret)
+        throw new HTTPException(503, { message: "Artifact catalog cursor signing is unavailable" });
+      const filters = { ...query, cursor: undefined };
+      const codec = artifactCatalogCursorCodec(
+        secret,
+        JSON.stringify({
+          accountId: grant.accountId,
+          workspaceId,
+          subjectId: grant.subjectId,
+          principalKind: grant.principalKind,
+          metadata: grant.metadata,
+          permissions: [...grant.permissions].sort(),
+          initiatingHumanSubjectId: actor.initiatingHumanSubjectId ?? null,
+          owner: actor.privateFileOwnerSubjectId ?? null,
+          kinds,
+          filters,
+        }),
+      );
+      const prior = query.cursor ? codec.decode(query.cursor) : undefined;
+      const snapshotAt = prior?.snapshotAt ?? new Date().toISOString();
+      const expiresAt = prior?.expiresAt ?? Date.now() + 60 * 60_000;
+      let after = prior?.after;
+      const items: ArtifactCatalogItem[] = [];
+      let lastReturned: ArtifactCatalogPosition | undefined;
+      let nextCursor: string | null = null;
+      const fileSubject = includesFiles ? await fileAuthoritySubjectIdForGrant(deps, grant) : null;
+      for (let batch = 0; batch < MAX_BATCHES; batch++) {
+        const candidates = await listArtifactCatalogCandidates(
+          deps.db,
+          { accountId: grant.accountId, workspaceId },
+          {
+            query,
+            kinds,
+            snapshotAt,
+            ...(after ? { after } : {}),
+            limit: CANDIDATE_BATCH,
+          },
+        );
+        for (const candidate of candidates) {
+          after = position(candidate);
+          const item = await projectCandidate(deps, grant, candidate, fileSubject);
+          if (
+            !item ||
+            item.status !== query.status ||
+            (query.q && !item.title.toLowerCase().includes(query.q.toLowerCase()))
+          )
+            continue;
+          if (items.length === query.limit) {
+            nextCursor = codec.encode({ version: 1, snapshotAt, expiresAt, after: lastReturned! });
+            return context.json(ArtifactCatalogListResponse.parse({ items, nextCursor }));
+          }
+          if (candidate.source_session_id && (await canReadSession(candidate.source_session_id)))
+            item.sourceSessionId = candidate.source_session_id;
+          items.push(ArtifactCatalogItem.parse(item));
+          lastReturned = after;
+        }
+        if (candidates.length < CANDIDATE_BATCH) break;
+        // Bounded scanning may produce an empty page; the encrypted frontier
+        // reveals neither denied identity nor provenance and can be continued.
+        if (batch === MAX_BATCHES - 1 && after)
+          nextCursor = codec.encode({ version: 1, snapshotAt, expiresAt, after });
+      }
+      return context.json(ArtifactCatalogListResponse.parse({ items, nextCursor }));
+    });
+  });
+}
+
+async function projectCandidate(
+  deps: Dependencies,
+  grant: AccessGrant,
+  row: ArtifactCatalogCandidate,
+  fileSubject: string | null,
+): Promise<ArtifactCatalogItem | null> {
+  const item: ArtifactCatalogItem = {
+    id: row.id,
+    kind: row.kind,
+    title: row.title,
+    status: row.status,
+    createdAt: iso(row.created_at),
+    updatedAt: iso(row.updated_at),
+  };
+  if (row.version_id) item.versionId = row.version_id;
+  if (editableKinds.has(row.kind)) {
+    const scope = editableArtifactScope({
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+    });
+    try {
+      // This is the HTTP application's read-only domain.getArtifact seam, NOT
+      // EditableArtifactAgentApplication.read (which touches session links).
+      const artifact = await deps.editableArtifacts!.readArtifact({
+        scope,
+        actor: editableArtifactActorForGrant(grant, "0000000000000001"),
+        artifactId: editableArtifactId(row.id),
+      });
+      if (
+        artifact.scope.accountId !== scope.accountId ||
+        artifact.scope.workspaceId !== scope.workspaceId ||
+        artifact.id !== row.id ||
+        artifact.modality !== row.kind
+      )
+        throw new Error("Artifact application returned mismatched catalog metadata");
+      return {
+        ...item,
+        title: artifact.title,
+        status: artifact.lifecycle,
+        createdAt: artifact.createdAt,
+        updatedAt: artifact.updatedAt,
+      };
+    } catch (error) {
+      if (isInvisibleListCandidate(error)) return null;
+      throw editableArtifactHttpError(error);
+    }
+  }
+  if (row.kind === "file" || row.kind === "image") {
+    const [file] = await getFilesForSubject(deps.db, {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      subjectId: fileSubject,
+      fileIds: [row.id],
+    });
+    if (!file || file.status !== "ready") return null;
+    const generated =
+      row.origin === "generated_image"
+        ? await getGeneratedImageArtifact(deps.db, grant.workspaceId, row.id)
+        : null;
+    const reference =
+      row.origin === "generated_image"
+        ? generated?.status === "ready"
+          ? retainedGeneratedImageReferenceFromFile({
+              ...file,
+              width: generated.width,
+              height: generated.height,
+            })
+          : null
+        : retainedArtifactReferenceFromFile(file, "file");
+    if (!reference) return null;
+    return {
+      ...item,
+      file: reference,
+      filename: file.filename,
+      contentType: reference.contentType,
+      sizeBytes: file.sizeBytes,
+    };
+  }
+  return item;
+}

package/src/routes/editable-artifacts.ts

@@ -909,7 +909,7 @@ function normalizeArtifactIdList(value: readonly string[]): readonly string[] {
   return ids;
 }
 
-function isInvisibleListCandidate(error: unknown): boolean {
+export function isInvisibleListCandidate(error: unknown): boolean {
   return (
     (error instanceof EditableArtifactDomainError &&
       (error.code === "forbidden" || error.code === "not_found")) ||
@@ -1050,7 +1050,7 @@ async function readBoundedJson(request: Request, maxBytes: number): Promise<unkn
   }
 }
 
-function editableArtifactHttpError(error: unknown): unknown {
+export function editableArtifactHttpError(error: unknown): unknown {
   if (error instanceof EditableArtifactDurableExportError) {
     switch (error.code) {
       case "invalid_request":

package/src/sandbox-file-artifacts.ts

@@ -22,6 +22,7 @@ import {
   prepareGeneratedWorkspaceFile,
   getSessionAuthorityProjection,
   requireWorkspace,
+  recordSandboxFilePublication,
   withSessionRlsActorContext,
 } from "@opengeni/db";
 import { retryWhileMissing, type ObjectHead, type ObjectStorage } from "@opengeni/storage";
@@ -225,6 +226,12 @@ async function publishSandboxFileArtifactInScope(
   if (!artifact) {
     throw new HTTPException(502, { message: "published sandbox artifact is not ready" });
   }
+  await recordSandboxFilePublication(deps.db, {
+    accountId: input.grant.accountId,
+    workspaceId: input.grant.workspaceId,
+    fileId: file.id,
+    sourceSessionId: input.session.id,
+  });
   return SandboxFileArtifactReceipt.parse({
     type: "sandbox_file",
     sandboxPath: `/workspace/${path}`,
@@ -300,7 +307,7 @@ export function sandboxFileContentType(filename: string): string {
   );
 }
 
-function sandboxArtifactIdentity(input: {
+export function sandboxArtifactIdentity(input: {
   workspaceId: string;
   sessionId: string;
   path: string;
@@ -330,7 +337,7 @@ function uuidFromDigest(digest: string, startByte: number): string {
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 }
 
-function assertSandboxArtifactFile(
+export function assertSandboxArtifactFile(
   file: NonNullable<Awaited<ReturnType<typeof getFile>>>,
   expected: {
     filename: string;