@agent-native/core 0.90.2 → 0.90.4

package/corpus/core/src/command-navigation/index.ts

@@ -0,0 +1,12 @@
+export * from "../navigation/index.js";
+export * from "./actions.js";
+export {
+  buildDeepLink,
+  toAbsoluteOpenUrl,
+  toDesktopOpenUrl,
+  toVsCodeOpenUrl,
+  DESKTOP_OPEN_URL,
+  OPEN_ROUTE_SUBPATH,
+  VSCODE_OPEN_URL,
+  type DeepLinkInput,
+} from "../server/deep-link.js";

package/corpus/core/src/comments-review/index.ts

@@ -0,0 +1 @@
+export * from "../review/index.js";

package/corpus/core/src/file-upload/builder.ts

@@ -60,6 +60,15 @@ function setSkipCompressionQueryParams(url: URL): void {
   }
 }
 
+function setRecordAssetQueryParam(
+  url: URL,
+  recordAsset: boolean | undefined,
+): void {
+  if (recordAsset === false) {
+    url.searchParams.set("record", "false");
+  }
+}
+
 async function assertOk(res: Response, label: string): Promise<void> {
   if (!res.ok) {
     const body = await res.text().catch(() => "");
@@ -111,7 +120,10 @@ async function uploadLargeFileViaSignedUrl(
     privateKey,
     assetId,
     input.filename,
-    { skipCompressionWait: input.skipCompressionWait },
+    {
+      skipCompressionWait: input.skipCompressionWait,
+      recordAsset: input.recordAsset,
+    },
   );
   console.log(`[builder-upload] done [${assetId}]: ${url}`);
   return { url, id, provider: "builder" };
@@ -165,20 +177,25 @@ async function completeBuilderUpload(
   privateKey: string,
   assetId: string,
   filename: string | undefined,
-  options?: { skipCompressionWait?: boolean },
+  options?: { skipCompressionWait?: boolean; recordAsset?: boolean },
 ): Promise<{ url: string; id?: string }> {
   const host = builderUploadHost();
   const url = new URL("/api/v1/upload/complete", host);
   if (options?.skipCompressionWait) {
     setSkipCompressionQueryParams(url);
   }
+  setRecordAssetQueryParam(url, options?.recordAsset);
   const res = await fetchWithTimeout(url.toString(), {
     method: "POST",
     headers: {
       Authorization: `Bearer ${privateKey}`,
       "Content-Type": "application/json",
     },
-    body: JSON.stringify({ assetId, name: filename }),
+    body: JSON.stringify({
+      assetId,
+      name: filename,
+      ...(options?.recordAsset === false ? { record: false } : {}),
+    }),
   });
   await assertOk(res, "Builder.io upload complete failed");
   const json = (await res.json()) as { url?: string; id?: string };
@@ -273,6 +290,7 @@ export const builderFileUploadProvider: FileUploadProvider = {
     if (input.skipCompressionWait) {
       setSkipCompressionQueryParams(url);
     }
+    setRecordAssetQueryParam(url, input.recordAsset);
 
     const response = await uploadSmallFile(url, {
       method: "POST",
@@ -414,6 +432,9 @@ export const builderFileUploadProvider: FileUploadProvider = {
           skipCompressionWait:
             options?.skipCompressionWait ||
             session.meta.skipCompressionWait === true,
+          recordAsset:
+            options?.recordAsset ??
+            (session.meta.recordAsset === false ? false : undefined),
         },
       );
       console.log(`[builder-resumable] upload complete: ${url}`);

package/corpus/core/src/file-upload/types.ts

@@ -18,6 +18,8 @@ export interface FileUploadInput {
   ownerEmail?: string;
   /** Builder.io upload hint: return after asset registration instead of waiting for server-side compression. */
   skipCompressionWait?: boolean;
+  /** Builder.io upload hint: set false for internal artifacts that should not appear in the asset library. */
+  recordAsset?: boolean;
 }
 
 export interface FileUploadResult {
@@ -79,7 +81,7 @@ export interface FileUploadProvider {
     completeSession(
       session: ResumableUploadSession,
       filename: string,
-      options?: { skipCompressionWait?: boolean },
+      options?: { skipCompressionWait?: boolean; recordAsset?: boolean },
     ): Promise<string>;
   };
 }

package/corpus/core/src/history/actions/create-resource-version.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import {
+  assertVersionedResourceAccess,
+  getVersionedResource,
+  normalizeHistoryVisibility,
+} from "../registry.js";
+import { insertResourceVersion } from "../store.js";
+import type { HistoryActorKind, VersionedResourceContext } from "../types.js";
+
+const schema = z.object({
+  resourceType: z.string().min(1),
+  resourceId: z.string().min(1),
+  title: z.string().optional(),
+  summary: z.string().optional(),
+  snapshot: z.unknown().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+export default defineAction({
+  description: "Create a reusable version-history snapshot for a resource.",
+  schema,
+  run: async (args, ctx) => {
+    const actionCtx = ctx as VersionedResourceContext | undefined;
+    const access = await assertVersionedResourceAccess(
+      args.resourceType,
+      args.resourceId,
+      actionCtx,
+      "editor",
+    );
+    const registration = getVersionedResource(args.resourceType);
+    // Prefer the registered server snapshot when available so editors/agents
+    // cannot plant arbitrary restore payloads for managed resource types.
+    const serverSnapshot = registration?.getSnapshot
+      ? await registration.getSnapshot({
+          resourceType: args.resourceType,
+          resourceId: args.resourceId,
+          ctx: actionCtx,
+          access,
+        })
+      : undefined;
+    const snapshot =
+      serverSnapshot !== undefined ? serverSnapshot : args.snapshot;
+
+    if (snapshot === undefined) {
+      throw new Error(
+        `No snapshot was provided and ${args.resourceType} has no getSnapshot history handler`,
+      );
+    }
+
+    return insertResourceVersion({
+      resourceType: args.resourceType,
+      resourceId: args.resourceId,
+      createdBy: actionCtx?.userEmail ?? null,
+      actorKind: actorKindFromContext(actionCtx),
+      ownerEmail: access.ownerEmail ?? actionCtx?.userEmail ?? null,
+      orgId: access.orgId ?? actionCtx?.orgId ?? null,
+      visibility: normalizeHistoryVisibility(access.visibility),
+      title: args.title,
+      summary: args.summary,
+      snapshot,
+      metadata: args.metadata,
+    });
+  },
+  audit: {
+    target: (args, result) => {
+      const version = result as {
+        ownerEmail?: string | null;
+        orgId?: string | null;
+        visibility?: "private" | "org" | "public";
+      };
+      return {
+        type: args.resourceType,
+        id: args.resourceId,
+        ownerEmail: version.ownerEmail,
+        orgId: version.orgId,
+        visibility: version.visibility,
+      };
+    },
+  },
+});
+
+function actorKindFromContext(
+  ctx: VersionedResourceContext | undefined,
+): HistoryActorKind {
+  const caller = typeof ctx?.caller === "string" ? ctx.caller : "";
+  if (caller === "agent" || caller === "tool") {
+    return "agent";
+  }
+  return ctx?.userEmail ? "human" : "system";
+}

package/corpus/core/src/history/actions/get-resource-version.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { assertVersionedResourceAccess } from "../registry.js";
+import {
+  getResourceVersionById,
+  getResourceVersionByNumber,
+} from "../store.js";
+import type { VersionedResourceContext } from "../types.js";
+
+const schema = z
+  .object({
+    id: z.string().optional(),
+    resourceType: z.string().min(1).optional(),
+    resourceId: z.string().min(1).optional(),
+    versionNumber: z.number().int().positive().optional(),
+  })
+  .refine(
+    (value) =>
+      value.id ||
+      (value.resourceType && value.resourceId && value.versionNumber),
+    {
+      message:
+        "Provide either id or resourceType, resourceId, and versionNumber",
+    },
+  );
+
+export default defineAction({
+  description: "Read one version-history snapshot for a reusable resource.",
+  schema,
+  http: { method: "GET" },
+  readOnly: true,
+  parallelSafe: true,
+  run: async (args, ctx) => {
+    const actionCtx = ctx as VersionedResourceContext | undefined;
+    const scope = {
+      userEmail: actionCtx?.userEmail ?? null,
+      orgId: actionCtx?.orgId ?? null,
+    };
+    const version = args.id
+      ? await getResourceVersionById(args.id, scope, { bypassScope: true })
+      : await getResourceVersionByNumber(
+          args.resourceType!,
+          args.resourceId!,
+          args.versionNumber!,
+          scope,
+          { bypassScope: true },
+        );
+    if (!version) {
+      throw new Error("Resource version not found");
+    }
+    await assertVersionedResourceAccess(
+      version.resourceType,
+      version.resourceId,
+      actionCtx,
+      "viewer",
+    );
+    return { version };
+  },
+});

package/corpus/core/src/history/actions/list-resource-history.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { queryAuditEvents } from "../../audit/store.js";
+import { assertVersionedResourceAccess } from "../registry.js";
+import { queryResourceVersions } from "../store.js";
+import type { VersionedResourceContext } from "../types.js";
+
+const schema = z.object({
+  resourceType: z.string().min(1),
+  resourceId: z.string().min(1),
+  limit: z.number().int().positive().max(200).optional(),
+});
+
+export default defineAction({
+  description: "List versions and audit events for a reusable resource.",
+  schema,
+  http: { method: "GET" },
+  readOnly: true,
+  parallelSafe: true,
+  run: async (args, ctx) => {
+    const actionCtx = ctx as VersionedResourceContext | undefined;
+    await assertVersionedResourceAccess(
+      args.resourceType,
+      args.resourceId,
+      actionCtx,
+      "viewer",
+    );
+    const scope = {
+      userEmail: actionCtx?.userEmail ?? null,
+      orgId: actionCtx?.orgId ?? null,
+    };
+    const auditScope = {
+      userEmail: actionCtx?.userEmail ?? undefined,
+      orgId: actionCtx?.orgId ?? undefined,
+    };
+    const [versions, auditEvents] = await Promise.all([
+      queryResourceVersions({
+        resourceType: args.resourceType,
+        resourceId: args.resourceId,
+        scope,
+        bypassScope: true,
+        limit: args.limit,
+      }),
+      queryAuditEvents(auditScope, {
+        targetType: args.resourceType,
+        targetId: args.resourceId,
+        limit: args.limit ?? 50,
+      }),
+    ]);
+    return { versions, auditEvents };
+  },
+});

package/corpus/core/src/history/actions/list-resource-versions.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { assertVersionedResourceAccess } from "../registry.js";
+import { queryResourceVersions } from "../store.js";
+import type { VersionedResourceContext } from "../types.js";
+
+const schema = z.object({
+  resourceType: z.string().min(1),
+  resourceId: z.string().min(1),
+  limit: z.number().int().positive().max(200).optional(),
+  offset: z.number().int().nonnegative().optional(),
+});
+
+export default defineAction({
+  description: "List version-history snapshots for a reusable resource.",
+  schema,
+  http: { method: "GET" },
+  readOnly: true,
+  parallelSafe: true,
+  run: async (args, ctx) => {
+    const actionCtx = ctx as VersionedResourceContext | undefined;
+    await assertVersionedResourceAccess(
+      args.resourceType,
+      args.resourceId,
+      actionCtx,
+      "viewer",
+    );
+    return {
+      versions: await queryResourceVersions({
+        resourceType: args.resourceType,
+        resourceId: args.resourceId,
+        scope: {
+          userEmail: actionCtx?.userEmail ?? null,
+          orgId: actionCtx?.orgId ?? null,
+        },
+        bypassScope: true,
+        limit: args.limit,
+        offset: args.offset,
+      }),
+    };
+  },
+});

package/corpus/core/src/history/actions/restore-resource-version.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import {
+  assertVersionedResourceAccess,
+  getVersionedResource,
+} from "../registry.js";
+import {
+  getResourceVersionById,
+  getResourceVersionByNumber,
+} from "../store.js";
+import type { VersionedResourceContext } from "../types.js";
+
+const schema = z
+  .object({
+    id: z.string().optional(),
+    resourceType: z.string().min(1).optional(),
+    resourceId: z.string().min(1).optional(),
+    versionNumber: z.number().int().positive().optional(),
+  })
+  .refine(
+    (value) =>
+      value.id ||
+      (value.resourceType && value.resourceId && value.versionNumber),
+    {
+      message:
+        "Provide either id or resourceType, resourceId, and versionNumber",
+    },
+  );
+
+export default defineAction({
+  description: "Restore a resource from a reusable version-history snapshot.",
+  schema,
+  run: async (args, ctx) => {
+    const actionCtx = ctx as VersionedResourceContext | undefined;
+    const scope = {
+      userEmail: actionCtx?.userEmail ?? null,
+      orgId: actionCtx?.orgId ?? null,
+    };
+    const version = args.id
+      ? await getResourceVersionById(args.id, scope, { bypassScope: true })
+      : await getResourceVersionByNumber(
+          args.resourceType!,
+          args.resourceId!,
+          args.versionNumber!,
+          scope,
+          { bypassScope: true },
+        );
+    if (!version) {
+      throw new Error("Resource version not found");
+    }
+
+    const access = await assertVersionedResourceAccess(
+      version.resourceType,
+      version.resourceId,
+      actionCtx,
+      "editor",
+    );
+    const registration = getVersionedResource(version.resourceType);
+    if (!registration?.restoreSnapshot) {
+      throw new Error(
+        `${version.resourceType} has no restoreSnapshot history handler registered`,
+      );
+    }
+
+    const result = await registration.restoreSnapshot({
+      resourceType: version.resourceType,
+      resourceId: version.resourceId,
+      ctx: actionCtx,
+      access,
+      version,
+      snapshot: version.snapshot,
+    });
+    return { version, result };
+  },
+  audit: {
+    target: (_args, result) => {
+      const restored = result as {
+        version: {
+          resourceType: string;
+          resourceId: string;
+          ownerEmail?: string | null;
+          orgId?: string | null;
+          visibility?: "private" | "org" | "public";
+        };
+      };
+      return {
+        type: restored.version.resourceType,
+        id: restored.version.resourceId,
+        ownerEmail: restored.version.ownerEmail,
+        orgId: restored.version.orgId,
+        visibility: restored.version.visibility,
+      };
+    },
+  },
+});

package/corpus/core/src/history/index.ts

@@ -0,0 +1,26 @@
+export type {
+  HistoryActorKind,
+  HistoryResourceRole,
+  ResourceHistoryScope,
+  ResourceVersion,
+  VersionedResourceAccess,
+  VersionedResourceContext,
+  VersionedResourceRegistration,
+  VersionedResourceRestoreContext,
+  VersionedResourceSnapshotContext,
+} from "./types.js";
+export {
+  __resetVersionedResourcesForTests,
+  assertVersionedResourceAccess,
+  getVersionedResource,
+  listVersionedResources,
+  registerVersionedResource,
+  resolveVersionedResourceAccess,
+} from "./registry.js";
+export {
+  __resetHistoryInitForTests,
+  ensureResourceVersionsTable,
+  getResourceVersionById,
+  getResourceVersionByNumber,
+  queryResourceVersions,
+} from "./store.js";

package/corpus/core/src/history/registry.ts

@@ -0,0 +1,111 @@
+import {
+  ForbiddenError,
+  resolveAccess,
+  type AccessContext,
+} from "../sharing/access.js";
+import { getShareableResource } from "../sharing/registry.js";
+import { roleSatisfies, type Visibility } from "../sharing/schema.js";
+import type {
+  HistoryResourceRole,
+  VersionedResourceAccess,
+  VersionedResourceContext,
+  VersionedResourceRegistration,
+} from "./types.js";
+
+const registrations = new Map<string, VersionedResourceRegistration>();
+
+export function registerVersionedResource(
+  registration: VersionedResourceRegistration,
+): void {
+  if (!registration.type.trim()) {
+    throw new Error(
+      "registerVersionedResource requires a non-empty resource type",
+    );
+  }
+  registrations.set(registration.type, registration);
+}
+
+export function getVersionedResource(
+  type: string,
+): VersionedResourceRegistration | undefined {
+  return registrations.get(type);
+}
+
+export function listVersionedResources(): VersionedResourceRegistration[] {
+  return Array.from(registrations.values());
+}
+
+function accessContextFrom(
+  ctx?: VersionedResourceContext,
+): AccessContext | undefined {
+  if (!ctx) return undefined;
+  return {
+    userEmail: ctx.userEmail ?? undefined,
+    orgId: ctx.orgId ?? undefined,
+  };
+}
+
+export async function resolveVersionedResourceAccess(
+  resourceType: string,
+  resourceId: string,
+  ctx?: VersionedResourceContext,
+): Promise<VersionedResourceAccess | null> {
+  const registration = getVersionedResource(resourceType);
+  if (registration?.resolveAccess) {
+    return registration.resolveAccess(resourceId, ctx);
+  }
+
+  if (getShareableResource(resourceType)) {
+    const access = await resolveAccess(
+      resourceType,
+      resourceId,
+      accessContextFrom(ctx),
+    );
+    if (!access) {
+      return null;
+    }
+    return {
+      role: access.role as HistoryResourceRole,
+      ownerEmail: access.resource.ownerEmail ?? null,
+      orgId: access.resource.orgId ?? null,
+      visibility: access.resource.visibility,
+      resource: access.resource,
+    };
+  }
+
+  // Fail closed: unregistered types, and registered types without an access
+  // resolver that aren't shareable, never invent ownership. bypassScope on
+  // history queries is only safe after a real resource ACL.
+  return null;
+}
+
+export async function assertVersionedResourceAccess(
+  resourceType: string,
+  resourceId: string,
+  ctx: VersionedResourceContext | undefined,
+  minimumRole: HistoryResourceRole,
+): Promise<VersionedResourceAccess> {
+  const access = await resolveVersionedResourceAccess(
+    resourceType,
+    resourceId,
+    ctx,
+  );
+  if (!access || !roleSatisfies(access.role, minimumRole)) {
+    throw new ForbiddenError(
+      `Not allowed to access ${resourceType}:${resourceId}`,
+    );
+  }
+  return access;
+}
+
+export function normalizeHistoryVisibility(
+  visibility: Visibility | null | undefined,
+): Visibility {
+  return visibility === "org" || visibility === "public"
+    ? visibility
+    : "private";
+}
+
+export function __resetVersionedResourcesForTests(): void {
+  registrations.clear();
+}