@agent-native/core 0.86.0 → 0.87.0

package/corpus/core/src/server/builder-design-systems.ts

@@ -12,6 +12,68 @@ export interface BuilderDesignSystemIndexFile {
   mimeType?: string;
 }
 
+export interface BuilderDesignSystemCodeFileInput {
+  filename: string;
+  content: string;
+  mimeType?: string;
+}
+
+export interface BuildBuilderDesignSystemIndexFilesOptions {
+  codeFiles?: BuilderDesignSystemCodeFileInput[];
+  designMd?: string;
+  designMdFilename?: string;
+  maxCodeFiles?: number;
+  maxTotalCodeBytes?: number;
+}
+
+export interface BuilderDesignSystemProxyFieldsOptions {
+  result: BuilderDesignSystemIndexResult;
+  projectName?: string;
+  description?: string;
+  surface: "design" | "slides";
+}
+
+export interface BuilderDesignSystemProxyFields {
+  title: string;
+  description: string;
+  data: string;
+  customInstructions: string;
+}
+
+export interface BuilderDesignSystemProxyReference {
+  source: "builder";
+  builderDesignSystemId: string;
+  builderJobId: string;
+  builderProjectId?: string;
+  builderUrl?: string;
+  builderStatus?: string;
+}
+
+export interface BuilderDesignSystemDocsOptions {
+  page?: number;
+  pageSize?: number;
+  minimal?: boolean;
+  type?: string;
+}
+
+export interface BuilderDesignSystemDocument {
+  id?: string;
+  name?: string;
+  type?: string;
+  description?: string;
+  content?: string;
+  tokenValues?: Record<string, string>;
+  rawTokens?: string[];
+  relevantFiles?: string[];
+  relatedComponents?: string[];
+}
+
+export interface BuilderDesignSystemHydratedReference extends BuilderDesignSystemProxyReference {
+  docs: BuilderDesignSystemDocument[];
+  tokenValues: Record<string, string>;
+  docCount: number;
+}
+
 export interface BuilderDesignSystemIndexOptions {
   projectName?: string;
   description?: string;
@@ -49,6 +111,10 @@ interface GenerateResponse {
   designSystemId?: string;
 }
 
+const DEFAULT_MAX_CODE_FILES = 50;
+const DEFAULT_MAX_TOTAL_CODE_BYTES = 2 * 1024 * 1024;
+const MAX_DOC_CONTENT_CHARS = 4_000;
+
 function trimTrailingSlash(value: string): string {
   return value.replace(/\/+$/, "");
 }
@@ -89,6 +155,66 @@ function makeBuilderHeaders(
   };
 }
 
+export function mimeTypeForBuilderDesignSystemFilename(
+  filename: string,
+  explicit?: string,
+): string {
+  if (explicit?.trim()) return explicit.trim();
+  const lower = filename.toLowerCase();
+  if (lower.endsWith(".fig")) return "application/octet-stream";
+  if (lower.endsWith(".pdf")) return "application/pdf";
+  if (lower.endsWith(".md") || lower.endsWith(".markdown"))
+    return "text/markdown";
+  if (lower.endsWith(".mdx")) return "text/markdown";
+  if (lower.endsWith(".json")) return "application/json";
+  if (lower.endsWith(".css")) return "text/css";
+  if (lower.endsWith(".html") || lower.endsWith(".htm")) return "text/html";
+  if (lower.endsWith(".svg")) return "image/svg+xml";
+  return "text/plain";
+}
+
+export function buildBuilderDesignSystemIndexFiles({
+  codeFiles,
+  designMd,
+  designMdFilename,
+  maxCodeFiles = DEFAULT_MAX_CODE_FILES,
+  maxTotalCodeBytes = DEFAULT_MAX_TOTAL_CODE_BYTES,
+}: BuildBuilderDesignSystemIndexFilesOptions): BuilderDesignSystemIndexFile[] {
+  const encoder = new TextEncoder();
+  const files: BuilderDesignSystemIndexFile[] = [];
+  let totalBytes = 0;
+
+  function pushTextFile(filename: string, content: string, mimeType?: string) {
+    const normalizedName = filename.replace(/^\/+/, "") || "code.txt";
+    const data = encoder.encode(content);
+    if (data.byteLength === 0) return;
+    if (totalBytes + data.byteLength > maxTotalCodeBytes) return;
+    totalBytes += data.byteLength;
+    files.push({
+      name: normalizedName,
+      data,
+      mimeType: mimeTypeForBuilderDesignSystemFilename(
+        normalizedName,
+        mimeType,
+      ),
+    });
+  }
+
+  if (designMd?.trim()) {
+    pushTextFile(
+      designMdFilename?.trim() || "design.md",
+      designMd,
+      "text/markdown",
+    );
+  }
+
+  for (const file of (codeFiles ?? []).slice(0, maxCodeFiles)) {
+    pushTextFile(file.filename, file.content, file.mimeType);
+  }
+
+  return files;
+}
+
 async function resolveBuilderDesignSystemCredentials(): Promise<BuilderDesignSystemCredentials> {
   const credentials = await resolveBuilderCredentials();
   if (!credentials.privateKey || !credentials.publicKey) {
@@ -107,15 +233,7 @@ async function resolveBuilderDesignSystemCredentials(): Promise<BuilderDesignSys
 }
 
 function mimeTypeForFile(file: BuilderDesignSystemIndexFile): string {
-  if (file.mimeType?.trim()) return file.mimeType.trim();
-  const lower = file.name.toLowerCase();
-  if (lower.endsWith(".fig")) return "application/octet-stream";
-  if (lower.endsWith(".pdf")) return "application/pdf";
-  if (lower.endsWith(".md") || lower.endsWith(".markdown"))
-    return "text/markdown";
-  if (lower.endsWith(".json")) return "application/json";
-  if (lower.endsWith(".css")) return "text/css";
-  return "text/plain";
+  return mimeTypeForBuilderDesignSystemFilename(file.name, file.mimeType);
 }
 
 function makeBody(bytes: Uint8Array, mimeType: string): BodyInit {
@@ -204,6 +322,207 @@ export function builderDesignSystemUrl(designSystemId?: string | null): string {
     : `${host}/app/design-system-intelligence`;
 }
 
+export function localBuilderDesignSystemId(
+  builderDesignSystemId: string,
+): string {
+  const slug = builderDesignSystemId
+    .replace(/[^a-zA-Z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 96);
+  return `builder-${slug || "design-system"}`;
+}
+
+export function createBuilderDesignSystemProxyFields({
+  result,
+  projectName,
+  description,
+  surface,
+}: BuilderDesignSystemProxyFieldsOptions): BuilderDesignSystemProxyFields {
+  const title = projectName?.trim() || "Builder indexed design system";
+  const fallbackDescription =
+    description ?? `Builder indexed design system ${result.designSystemId}`;
+  const surfaceNoun = surface === "slides" ? "slides" : "designs";
+  const spacingKey = surface === "slides" ? "slidePadding" : "pagePadding";
+  const data = JSON.stringify({
+    source: "builder",
+    builderDesignSystemId: result.designSystemId,
+    builderJobId: result.jobId,
+    builderProjectId: result.projectId,
+    builderUrl: result.builderUrl,
+    builderStatus: result.status,
+    colors: {
+      primary: "var(--primary)",
+      secondary: "var(--secondary)",
+      accent: "var(--accent)",
+      background: "var(--background)",
+      surface: "var(--card)",
+      text: "var(--foreground)",
+      textMuted: "var(--muted-foreground)",
+    },
+    typography: {
+      headingFont: "inherit",
+      bodyFont: "inherit",
+      headingWeight: "700",
+      bodyWeight: "400",
+      headingSizes: { h1: "48px", h2: "32px", h3: "24px" },
+    },
+    spacing: { elementGap: "24px", [spacingKey]: "48px" },
+    borders: { radius: "12px", accentWidth: "1px" },
+    logos: [],
+    notes: [
+      "This is a local selectable proxy for a Builder DSI-indexed design system.",
+      `Builder design system id: ${result.designSystemId}`,
+      `Builder indexing job id: ${result.jobId}`,
+      `Builder project id: ${result.projectId}`,
+      `Builder URL: ${result.builderUrl}`,
+      projectName ? `Requested name: ${projectName}` : "",
+      description ? `Context: ${description}` : "",
+      "Builder Design System Intelligence is the source of truth for extracted tokens, components, assets, and usage guidance.",
+    ]
+      .filter(Boolean)
+      .join("\n"),
+  });
+  const customInstructions = [
+    "This design system is indexed by Builder Design System Intelligence (DSI).",
+    `Builder design system id: ${result.designSystemId}`,
+    `Builder job id: ${result.jobId}`,
+    `Builder project id: ${result.projectId}`,
+    `Builder URL: ${result.builderUrl}`,
+    `When generating ${surfaceNoun}, treat Builder DSI as the source of truth for extracted tokens, components, assets, and usage guidance.`,
+    "Call get-design-system for this local id before generation and use the returned builder docs and token values when available.",
+  ].join("\n");
+
+  return {
+    title,
+    description: fallbackDescription,
+    data,
+    customInstructions,
+  };
+}
+
+export function parseBuilderDesignSystemProxyReference(
+  data: unknown,
+): BuilderDesignSystemProxyReference | null {
+  let parsed: unknown = data;
+  if (typeof data === "string") {
+    try {
+      parsed = JSON.parse(data);
+    } catch {
+      return null;
+    }
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const value = parsed as Record<string, unknown>;
+  if (value.source !== "builder") return null;
+  if (typeof value.builderDesignSystemId !== "string") return null;
+  if (typeof value.builderJobId !== "string") return null;
+  return {
+    source: "builder",
+    builderDesignSystemId: value.builderDesignSystemId,
+    builderJobId: value.builderJobId,
+    builderProjectId:
+      typeof value.builderProjectId === "string"
+        ? value.builderProjectId
+        : undefined,
+    builderUrl:
+      typeof value.builderUrl === "string" ? value.builderUrl : undefined,
+    builderStatus:
+      typeof value.builderStatus === "string" ? value.builderStatus : undefined,
+  };
+}
+
+function truncateDocContent(content: unknown): string | undefined {
+  if (typeof content !== "string") return undefined;
+  if (content.length <= MAX_DOC_CONTENT_CHARS) return content;
+  return `${content.slice(0, MAX_DOC_CONTENT_CHARS)}\n\n[truncated]`;
+}
+
+function normalizeBuilderDesignSystemDocument(
+  value: unknown,
+): BuilderDesignSystemDocument {
+  const doc =
+    value && typeof value === "object"
+      ? (value as Record<string, unknown>)
+      : {};
+  return {
+    id: typeof doc.id === "string" ? doc.id : undefined,
+    name: typeof doc.name === "string" ? doc.name : undefined,
+    type: typeof doc.type === "string" ? doc.type : undefined,
+    description:
+      typeof doc.description === "string" ? doc.description : undefined,
+    content: truncateDocContent(doc.content),
+    tokenValues:
+      doc.tokenValues && typeof doc.tokenValues === "object"
+        ? (doc.tokenValues as Record<string, string>)
+        : undefined,
+    rawTokens: Array.isArray(doc.rawTokens)
+      ? doc.rawTokens.filter(
+          (token): token is string => typeof token === "string",
+        )
+      : undefined,
+    relevantFiles: Array.isArray(doc.relevantFiles)
+      ? doc.relevantFiles.filter(
+          (file): file is string => typeof file === "string",
+        )
+      : undefined,
+    relatedComponents: Array.isArray(doc.relatedComponents)
+      ? doc.relatedComponents.filter(
+          (component): component is string => typeof component === "string",
+        )
+      : undefined,
+  };
+}
+
+export async function fetchBuilderDesignSystemDocs(
+  designSystemId: string,
+  options: BuilderDesignSystemDocsOptions = {},
+): Promise<BuilderDesignSystemDocument[]> {
+  const credentials = await resolveBuilderDesignSystemCredentials();
+  const url = makeBuilderDesignSystemUrl(
+    `${encodeURIComponent(designSystemId)}/docs`,
+    credentials,
+  );
+  if (options.page !== undefined)
+    url.searchParams.set("page", String(options.page));
+  if (options.pageSize !== undefined)
+    url.searchParams.set("pageSize", String(options.pageSize));
+  if (options.minimal !== undefined)
+    url.searchParams.set("minimal", options.minimal ? "true" : "false");
+  if (options.type?.trim()) url.searchParams.set("type", options.type.trim());
+
+  const response = await fetchWithTimeout(url, {
+    method: "GET",
+    headers: makeBuilderHeaders(credentials),
+  });
+  await assertOk(response, "Builder design-system docs fetch failed");
+  const json = (await response.json()) as unknown;
+  if (!Array.isArray(json)) return [];
+  return json.map(normalizeBuilderDesignSystemDocument);
+}
+
+export async function hydrateBuilderDesignSystemReference(
+  reference: BuilderDesignSystemProxyReference,
+  options: BuilderDesignSystemDocsOptions = { page: 0, pageSize: 40 },
+): Promise<BuilderDesignSystemHydratedReference> {
+  const docs = await fetchBuilderDesignSystemDocs(
+    reference.builderDesignSystemId,
+    options,
+  );
+  const tokenValues: Record<string, string> = {};
+  for (const doc of docs) {
+    if (!doc.tokenValues) continue;
+    for (const [name, value] of Object.entries(doc.tokenValues)) {
+      if (typeof value === "string") tokenValues[name] = value;
+    }
+  }
+  return {
+    ...reference,
+    docs,
+    tokenValues,
+    docCount: docs.length,
+  };
+}
+
 export async function startBuilderDesignSystemIndex(
   options: BuilderDesignSystemIndexOptions,
 ): Promise<BuilderDesignSystemIndexResult> {

package/corpus/core/src/server/h3-helpers.ts

@@ -1,5 +1,4 @@
 import type { ReadStream } from "node:fs";
-import { Readable } from "node:stream";
 
 /**
  * Small helpers around h3 v2 that polish ergonomics for templates.
@@ -158,5 +157,18 @@ export async function readBodyWithSizeLimit<T = any>(
  *   return streamFile(fs.createReadStream(filePath));
  */
 export function streamFile(stream: ReadStream): ReadableStream {
-  return Readable.toWeb(stream) as ReadableStream;
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      stream.on("data", (chunk: string | Uint8Array) => {
+        controller.enqueue(
+          typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk,
+        );
+      });
+      stream.on("end", () => controller.close());
+      stream.on("error", (error) => controller.error(error));
+    },
+    cancel() {
+      stream.destroy();
+    },
+  });
 }

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

@@ -388,11 +388,26 @@ export {
 } from "./credential-provider.js";
 export {
   builderDesignSystemUrl,
+  buildBuilderDesignSystemIndexFiles,
+  createBuilderDesignSystemProxyFields,
+  fetchBuilderDesignSystemDocs,
   getBuilderDesignSystemsBaseUrl,
+  hydrateBuilderDesignSystemReference,
+  localBuilderDesignSystemId,
+  mimeTypeForBuilderDesignSystemFilename,
+  parseBuilderDesignSystemProxyReference,
   startBuilderDesignSystemIndex,
+  type BuildBuilderDesignSystemIndexFilesOptions,
+  type BuilderDesignSystemCodeFileInput,
+  type BuilderDesignSystemDocsOptions,
+  type BuilderDesignSystemDocument,
+  type BuilderDesignSystemHydratedReference,
   type BuilderDesignSystemIndexFile,
   type BuilderDesignSystemIndexOptions,
   type BuilderDesignSystemIndexResult,
+  type BuilderDesignSystemProxyFields,
+  type BuilderDesignSystemProxyFieldsOptions,
+  type BuilderDesignSystemProxyReference,
 } from "./builder-design-systems.js";
 export {
   getBuilderBranchProjectId,
@@ -444,6 +459,25 @@ export {
   type ShortLivedTokenClaims,
   type VerifyResult as ShortLivedTokenVerifyResult,
 } from "./short-lived-token.js";
+export {
+  AGENT_ACCESS_PARAM,
+  DEFAULT_AGENT_ACCESS_TTL_SECONDS,
+  appendAgentAccessParam,
+  buildAgentAccessApiUrl,
+  buildAgentAccessUrl,
+  createScopedAgentAccessGrant,
+  normalizeAgentAccessBasePath,
+  normalizeAgentAccessOrigin,
+  scopedAgentAccessResourceId,
+  signScopedAgentAccessToken,
+  toAgentAccessUrl,
+  verifyScopedAgentAccessToken,
+  type AgentAccessApiUrlOptions,
+  type AgentAccessResourceScope,
+  type AgentAccessUrlOptions,
+  type ScopedAgentAccessGrant,
+  type ScopedAgentAccessTokenOptions,
+} from "./agent-access.js";
 
 // SSR handler is NOT re-exported here — it uses a virtual module
 // (virtual:react-router/server-build) that only exists at Vite dev/build time.

package/corpus/core/src/server/request-context.ts

@@ -15,7 +15,62 @@
  * process.env so existing `AGENT_USER_EMAIL=x pnpm action foo` invocations
  * continue to work.
  */
-import { AsyncLocalStorage } from "node:async_hooks";
+
+type AsyncLocalStorageLike<T> = {
+  getStore(): T | undefined;
+  run<R>(store: T, callback: () => R): R;
+};
+
+type AsyncLocalStorageCtor = new <T>() => AsyncLocalStorageLike<T>;
+
+class StackAsyncLocalStorage<T> implements AsyncLocalStorageLike<T> {
+  private readonly stack: T[] = [];
+
+  getStore(): T | undefined {
+    return this.stack.at(-1);
+  }
+
+  run<R>(store: T, callback: () => R): R {
+    this.stack.push(store);
+    try {
+      const result = callback();
+      const maybePromise = result as unknown as
+        | { finally?: (callback: () => void) => unknown }
+        | undefined;
+      if (maybePromise && typeof maybePromise.finally === "function") {
+        return maybePromise.finally(() => {
+          this.stack.pop();
+        }) as R;
+      }
+      this.stack.pop();
+      return result;
+    } catch (error) {
+      this.stack.pop();
+      throw error;
+    }
+  }
+}
+
+function getAsyncLocalStorageCtor(): AsyncLocalStorageCtor | undefined {
+  if (
+    typeof window !== "undefined" ||
+    typeof process === "undefined" ||
+    !process.versions?.node ||
+    typeof process.getBuiltinModule !== "function"
+  ) {
+    return undefined;
+  }
+  return process.getBuiltinModule("node:async_hooks")?.AsyncLocalStorage as
+    | AsyncLocalStorageCtor
+    | undefined;
+}
+
+const AsyncLocalStorageCtor = getAsyncLocalStorageCtor();
+
+function processEnv(name: string): string | undefined {
+  if (typeof process === "undefined") return undefined;
+  return process.env?.[name];
+}
 
 /**
  * Per-request agent-run state. Lives on `RequestContext.run` so the
@@ -114,12 +169,14 @@ const GLOBAL_KEY = "__agentNativeRequestContextAls" as const;
 const OBSERVERS_KEY = "__agentNativeRequestContextObservers" as const;
 type RequestContextObserver = (ctx: RequestContext) => void;
 type GlobalWithRequestContext = typeof globalThis & {
-  [GLOBAL_KEY]?: AsyncLocalStorage<RequestContext>;
+  [GLOBAL_KEY]?: AsyncLocalStorageLike<RequestContext>;
   [OBSERVERS_KEY]?: RequestContextObserver[];
 };
 const globalRef = globalThis as GlobalWithRequestContext;
 if (!globalRef[GLOBAL_KEY]) {
-  globalRef[GLOBAL_KEY] = new AsyncLocalStorage<RequestContext>();
+  globalRef[GLOBAL_KEY] = AsyncLocalStorageCtor
+    ? new AsyncLocalStorageCtor<RequestContext>()
+    : new StackAsyncLocalStorage<RequestContext>();
 }
 if (!globalRef[OBSERVERS_KEY]) {
   globalRef[OBSERVERS_KEY] = [];
@@ -211,7 +268,7 @@ export function getRequestUserEmail(): string | undefined {
     if (store.userEmail) markAuthContextAccess(store);
     return store.userEmail;
   }
-  return process.env.AGENT_USER_EMAIL;
+  return processEnv("AGENT_USER_EMAIL");
 }
 
 /**
@@ -227,7 +284,7 @@ export function getRequestUserName(): string | undefined {
     if (store.userName) markAuthContextAccess(store);
     return store.userName;
   }
-  return process.env.AGENT_USER_NAME;
+  return processEnv("AGENT_USER_NAME");
 }
 
 /**
@@ -243,7 +300,7 @@ export function getRequestOrgId(): string | undefined {
     if (store.orgId) markAuthContextAccess(store);
     return store.orgId;
   }
-  return process.env.AGENT_ORG_ID;
+  return processEnv("AGENT_ORG_ID");
 }
 
 function markAuthContextAccess(ctx: RequestContext | undefined) {
@@ -267,7 +324,7 @@ export function hasAuthContextAccess(ctx: RequestContext | undefined): boolean {
 export function getRequestTimezone(): string | undefined {
   const store = als.getStore();
   if (store !== undefined) return store.timezone;
-  return process.env.AGENT_USER_TIMEZONE;
+  return processEnv("AGENT_USER_TIMEZONE");
 }
 
 /**

package/corpus/core/src/shared/agent-access.ts

@@ -0,0 +1,112 @@
+export const AGENT_ACCESS_PARAM = "agent_access";
+export const DEFAULT_AGENT_ACCESS_TTL_SECONDS = 2 * 60 * 60;
+
+export interface AgentAccessResourceScope {
+  resourceKind: string;
+  resourceId: string;
+}
+
+export interface AgentAccessUrlOptions {
+  origin?: string;
+  basePath?: string;
+  tokenParam?: string;
+}
+
+export interface AgentAccessApiUrlOptions extends AgentAccessUrlOptions {
+  endpoint: string;
+  resourceId: string;
+  idParam?: string;
+  token?: string | null;
+  extraParams?: Array<[string, string | number | boolean | null | undefined]>;
+}
+
+function normalizeResourcePart(value: string, label: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) throw new Error(`${label} is required`);
+  return trimmed;
+}
+
+export function scopedAgentAccessResourceId(
+  resourceKind: string,
+  resourceId: string,
+): string {
+  return `${normalizeResourcePart(resourceKind, "resourceKind")}:${normalizeResourcePart(resourceId, "resourceId")}`;
+}
+
+function trimSlashes(value: string): string {
+  return value.replace(/^\/+|\/+$/g, "");
+}
+
+export function normalizeAgentAccessBasePath(basePath?: string): string {
+  const trimmed = trimSlashes(basePath ?? "");
+  return trimmed ? `/${trimmed}` : "";
+}
+
+export function normalizeAgentAccessOrigin(origin?: string): string {
+  if (!origin) return "";
+  return origin.replace(/\/+$/g, "");
+}
+
+function isAbsoluteUrl(value: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
+}
+
+export function toAgentAccessUrl(
+  pathOrUrl: string,
+  options: Pick<AgentAccessUrlOptions, "origin" | "basePath"> = {},
+): string {
+  if (isAbsoluteUrl(pathOrUrl)) return pathOrUrl;
+  const path = pathOrUrl.startsWith("/") ? pathOrUrl : `/${pathOrUrl}`;
+  return `${normalizeAgentAccessOrigin(options.origin)}${normalizeAgentAccessBasePath(options.basePath)}${path}`;
+}
+
+export function appendAgentAccessParam(
+  urlOrPath: string,
+  token: string,
+  param = AGENT_ACCESS_PARAM,
+): string {
+  const hashIndex = urlOrPath.indexOf("#");
+  const base = hashIndex >= 0 ? urlOrPath.slice(0, hashIndex) : urlOrPath;
+  const hash = hashIndex >= 0 ? urlOrPath.slice(hashIndex) : "";
+  const sep = base.includes("?") ? "&" : "?";
+  return `${base}${sep}${encodeURIComponent(param)}=${encodeURIComponent(token)}${hash}`;
+}
+
+export function buildAgentAccessUrl({
+  path,
+  token,
+  origin,
+  basePath,
+  tokenParam = AGENT_ACCESS_PARAM,
+}: AgentAccessUrlOptions & {
+  path: string;
+  token: string;
+}): string {
+  return appendAgentAccessParam(
+    toAgentAccessUrl(path, { origin, basePath }),
+    token,
+    tokenParam,
+  );
+}
+
+export function buildAgentAccessApiUrl({
+  endpoint,
+  resourceId,
+  idParam = "id",
+  token,
+  tokenParam = AGENT_ACCESS_PARAM,
+  extraParams,
+  origin,
+  basePath,
+}: AgentAccessApiUrlOptions): string {
+  const params = new URLSearchParams({ [idParam]: resourceId });
+  if (token) params.set(tokenParam, token);
+  for (const [key, value] of extraParams ?? []) {
+    if (value === undefined || value === null || value === "") continue;
+    params.set(key, String(value));
+  }
+  return toAgentAccessUrl(`${endpoint}?${params.toString()}`, {
+    origin,
+    basePath,
+  });
+}

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

@@ -58,3 +58,17 @@ export {
   EMBED_START_PATH,
   EMBED_TOKEN_QUERY_PARAM,
 } from "./embed-auth.js";
+export {
+  AGENT_ACCESS_PARAM,
+  DEFAULT_AGENT_ACCESS_TTL_SECONDS,
+  appendAgentAccessParam,
+  buildAgentAccessApiUrl,
+  buildAgentAccessUrl,
+  normalizeAgentAccessBasePath,
+  normalizeAgentAccessOrigin,
+  scopedAgentAccessResourceId,
+  toAgentAccessUrl,
+  type AgentAccessApiUrlOptions,
+  type AgentAccessResourceScope,
+  type AgentAccessUrlOptions,
+} from "./agent-access.js";