@agent-native/core 0.87.0 → 0.88.0

package/corpus/templates/analytics/shared/resource-agent-access.ts

@@ -0,0 +1,6 @@
+export const ANALYTICS_DASHBOARD_AGENT_RESOURCE_KIND = "analytics:dashboard";
+export const ANALYTICS_ANALYSIS_AGENT_RESOURCE_KIND = "analytics:analysis";
+export const ANALYTICS_DASHBOARD_AGENT_CONTEXT_ENDPOINT =
+  "/api/dashboard-agent-context.json";
+export const ANALYTICS_ANALYSIS_AGENT_CONTEXT_ENDPOINT =
+  "/api/analysis-agent-context.json";

package/corpus/templates/content/app/routes/p.$id.tsx

@@ -1,23 +1,82 @@
 import { agentNativePath, useT } from "@agent-native/core/client";
+import {
+  AGENT_ACCESS_PARAM,
+  verifyScopedAgentAccessToken,
+} from "@agent-native/core/server";
 import {
   getConfiguredAppBasePath,
   getRequestUserEmail,
 } from "@agent-native/core/server";
+import {
+  AGENT_READABLE_RESOURCE_SCRIPT_TYPE,
+  safeJsonForHtml,
+} from "@agent-native/core/shared";
 import { resolveAccess } from "@agent-native/core/sharing";
 import { buildPublicDocumentDescription } from "@shared/og-description";
 import { IconLock, IconMessageCircle } from "@tabler/icons-react";
 import { eq } from "drizzle-orm";
 import { useEffect, useState } from "react";
-import type { LoaderFunctionArgs, MetaFunction } from "react-router";
-import { redirect, useLoaderData } from "react-router";
+import type {
+  HeadersArgs,
+  LoaderFunctionArgs,
+  MetaFunction,
+} from "react-router";
+import { data, redirect, useLoaderData } from "react-router";
 
 import { VisualEditor } from "@/components/editor/VisualEditor";
 
 import { getDb, schema } from "../../server/db";
+import {
+  buildContentDocumentAgentDiscovery,
+  buildContentPublicDocumentUrl,
+  DOCUMENT_AGENT_RESOURCE_KIND,
+} from "../../shared/agent-readable";
+
+type PublicDocumentLoaderData =
+  | {
+      document: {
+        id: string;
+        title: string;
+        content: string;
+        updatedAt: string;
+        visibility: string;
+      };
+      agentAccessToken: string | null;
+      basePath: string;
+      unavailable?: undefined;
+    }
+  | {
+      document: null;
+      agentAccessToken: null;
+      basePath: string;
+      unavailable: { reason: "private"; id: string; basePath: string };
+    };
+
+const PRIVATE_AGENT_DOCUMENT_HEADERS = {
+  "Cache-Control": "private, max-age=0, no-store",
+  "Referrer-Policy": "no-referrer",
+};
 
-export async function loader({ params }: LoaderFunctionArgs) {
+function publicDocumentLoaderData(
+  payload: PublicDocumentLoaderData,
+  privateAgentAccess = false,
+) {
+  if (!privateAgentAccess) return payload;
+  return data(payload, {
+    headers: PRIVATE_AGENT_DOCUMENT_HEADERS,
+  });
+}
+
+export function headers({ loaderHeaders }: HeadersArgs) {
+  return loaderHeaders;
+}
+
+export async function loader({ params, request }: LoaderFunctionArgs) {
   const id = params.id;
   if (!id) throw new Response("Not found", { status: 404 });
+  const agentAccessToken = new URL(request.url).searchParams.get(
+    AGENT_ACCESS_PARAM,
+  );
 
   // This is a server loader; use the server-side base-path helper
   // (reads APP_BASE_PATH / VITE_APP_BASE_PATH at request time)
@@ -45,7 +104,22 @@ export async function loader({ params }: LoaderFunctionArgs) {
     .limit(1);
 
   if (!doc) throw new Response("Not found", { status: 404 });
-  if (doc.visibility === "public") return { document: doc };
+  const tokenAccess = agentAccessToken
+    ? verifyScopedAgentAccessToken(agentAccessToken, {
+        resourceKind: DOCUMENT_AGENT_RESOURCE_KIND,
+        resourceId: id,
+      }).ok
+    : false;
+  if (doc.visibility === "public" || tokenAccess) {
+    return publicDocumentLoaderData(
+      {
+        document: doc,
+        agentAccessToken: tokenAccess ? agentAccessToken : null,
+        basePath,
+      },
+      tokenAccess,
+    );
+  }
 
   // Doc exists but isn't public. SSR renders impersonally (no session is read
   // server-side, so the page can be CDN-cached for everyone), which means we
@@ -56,10 +130,12 @@ export async function loader({ params }: LoaderFunctionArgs) {
   // routes the viewer to the auth-guarded `/page/<id>` editor, where the real
   // per-user access check runs (signed-in-with-access sees the doc; everyone
   // else gets the standard sign-in / no-access handling).
-  return {
+  return publicDocumentLoaderData({
     document: null,
+    agentAccessToken: null,
+    basePath,
     unavailable: { reason: "private" as const, id, basePath },
-  };
+  });
 }
 
 export const meta: MetaFunction<typeof loader> = ({ loaderData }) => {
@@ -139,6 +215,7 @@ function renderMarkdownBlocks(content: string) {
 
 function PublicDocumentContextSync({
   document,
+  basePath,
 }: {
   document: {
     id: string;
@@ -146,6 +223,7 @@ function PublicDocumentContextSync({
     content: string;
     updatedAt: string;
   };
+  basePath?: string;
 }) {
   useEffect(() => {
     fetch(agentNativePath("/_agent-native/application-state/navigation"), {
@@ -156,10 +234,10 @@ function PublicDocumentContextSync({
         view: "public-document",
         documentId: document.id,
         title: document.title,
-        publicUrl: `/p/${document.id}`,
+        publicUrl: buildContentPublicDocumentUrl(document.id, { basePath }),
       }),
     }).catch(() => {});
-  }, [document.id, document.title]);
+  }, [basePath, document.id, document.title]);
 
   return null;
 }
@@ -178,6 +256,28 @@ function ReadOnlyMarkdownContent({ content }: { content: string }) {
   );
 }
 
+function AgentReadableDocumentDiscovery({
+  document,
+  token,
+  basePath,
+}: {
+  document: { id: string; title: string };
+  token?: string | null;
+  basePath?: string;
+}) {
+  const discovery = buildContentDocumentAgentDiscovery({
+    document,
+    token,
+    basePath,
+  });
+  return (
+    <script
+      type={AGENT_READABLE_RESOURCE_SCRIPT_TYPE}
+      dangerouslySetInnerHTML={{ __html: safeJsonForHtml(discovery) }}
+    />
+  );
+}
+
 function PrivateDocumentNotice({
   id,
   basePath,
@@ -230,7 +330,12 @@ export default function PublicDocumentPage() {
 
   return (
     <main className="min-h-screen bg-background text-foreground">
-      <PublicDocumentContextSync document={document} />
+      <PublicDocumentContextSync document={document} basePath={data.basePath} />
+      <AgentReadableDocumentDiscovery
+        document={document}
+        token={data.agentAccessToken}
+        basePath={data.basePath}
+      />
       <div className="mx-auto flex max-w-3xl justify-end px-6 pt-5 sm:px-8">
         <button
           type="button"

package/corpus/templates/content/server/db/index.ts

@@ -1,6 +1,10 @@
 import { createGetDb } from "@agent-native/core/db";
 import { registerShareableResource } from "@agent-native/core/sharing";
 
+import {
+  DOCUMENT_AGENT_CONTEXT_ENDPOINT,
+  DOCUMENT_AGENT_RESOURCE_KIND,
+} from "../../shared/agent-readable.js";
 import * as schema from "./schema.js";
 
 export const getDb = createGetDb(schema);
@@ -13,5 +17,10 @@ registerShareableResource({
   displayName: "Document",
   titleColumn: "title",
   getResourcePath: (document) => `/page/${document.id}`,
+  agentReadable: {
+    resourceKind: DOCUMENT_AGENT_RESOURCE_KIND,
+    getContextPath: () => DOCUMENT_AGENT_CONTEXT_ENDPOINT,
+    getPagePath: (document) => `/p/${document.id}`,
+  },
   getDb,
 });

package/corpus/templates/content/server/routes/api/document-agent-context.json.get.ts

@@ -0,0 +1,90 @@
+import {
+  AGENT_ACCESS_PARAM,
+  getConfiguredAppBasePath,
+  verifyScopedAgentAccessToken,
+} from "@agent-native/core/server";
+import { eq } from "drizzle-orm";
+import {
+  defineEventHandler,
+  getQuery,
+  setResponseHeader,
+  setResponseStatus,
+} from "h3";
+
+import {
+  buildContentPublicDocumentUrl,
+  DOCUMENT_AGENT_RESOURCE_KIND,
+} from "../../../shared/agent-readable.js";
+import { getDb, schema } from "../../db/index.js";
+
+function queryString(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && typeof value[0] === "string") return value[0];
+  return "";
+}
+
+function deny(statusCode: number, message: string) {
+  return { statusCode, body: { error: message } };
+}
+
+export default defineEventHandler(async (event) => {
+  setResponseHeader(event, "Cache-Control", "no-store");
+  setResponseHeader(event, "Referrer-Policy", "no-referrer");
+  setResponseHeader(event, "X-Content-Type-Options", "nosniff");
+
+  const query = getQuery(event);
+  const id = queryString(query.id);
+  if (!id) {
+    setResponseStatus(event, 400);
+    return { error: "Document id is required" };
+  }
+
+  const token = queryString(query[AGENT_ACCESS_PARAM]);
+  const db = getDb();
+  // guard:allow-unscoped -- this endpoint returns a document only when it is public or a document-scoped agent_access token verifies for this id.
+  const [document] = await db
+    .select({
+      id: schema.documents.id,
+      title: schema.documents.title,
+      content: schema.documents.content,
+      icon: schema.documents.icon,
+      visibility: schema.documents.visibility,
+      updatedAt: schema.documents.updatedAt,
+      createdAt: schema.documents.createdAt,
+    })
+    .from(schema.documents)
+    .where(eq(schema.documents.id, id))
+    .limit(1);
+
+  if (!document) {
+    setResponseStatus(event, 404);
+    return { error: "Document not found" };
+  }
+
+  const tokenAccess = token
+    ? verifyScopedAgentAccessToken(token, {
+        resourceKind: DOCUMENT_AGENT_RESOURCE_KIND,
+        resourceId: id,
+      }).ok
+    : false;
+  if (document.visibility !== "public" && !tokenAccess) {
+    const denied = deny(403, "Invalid or expired agent access token");
+    setResponseStatus(event, denied.statusCode);
+    return denied.body;
+  }
+
+  return {
+    resourceType: "document",
+    id: document.id,
+    title: document.title,
+    icon: document.icon,
+    content: document.content,
+    visibility: document.visibility,
+    createdAt: document.createdAt,
+    updatedAt: document.updatedAt,
+    url: buildContentPublicDocumentUrl(document.id, {
+      basePath: getConfiguredAppBasePath(),
+      token: tokenAccess ? token : null,
+    }),
+  };
+});

package/corpus/templates/content/shared/agent-readable.ts

@@ -0,0 +1,56 @@
+import {
+  AGENT_ACCESS_PARAM,
+  buildAgentAccessUrl,
+  buildAgentReadableResourceDiscovery,
+  normalizeAgentAccessBasePath,
+  toAgentAccessUrl,
+  type AgentReadableResourceDiscovery,
+} from "@agent-native/core/shared";
+
+export const DOCUMENT_AGENT_RESOURCE_KIND = "content:document";
+export const DOCUMENT_AGENT_CONTEXT_ENDPOINT =
+  "/api/document-agent-context.json";
+export const DOCUMENT_AGENT_READABLE_INSTRUCTIONS =
+  "Use contextUrl to read this shared Content document as structured JSON. The page is read-only for token and public viewers.";
+
+export function buildContentPublicDocumentPath(documentId: string): string {
+  return `/p/${documentId}`;
+}
+
+export function buildContentPublicDocumentUrl(
+  documentId: string,
+  options: { basePath?: string; token?: string | null } = {},
+): string {
+  const path = buildContentPublicDocumentPath(documentId);
+  const basePath = normalizeAgentAccessBasePath(options.basePath);
+  if (options.token) {
+    return buildAgentAccessUrl({
+      path,
+      basePath,
+      token: options.token,
+      tokenParam: AGENT_ACCESS_PARAM,
+    });
+  }
+  return toAgentAccessUrl(path, { basePath });
+}
+
+export function buildContentDocumentAgentDiscovery({
+  document,
+  token,
+  basePath,
+}: {
+  document: { id: string; title: string };
+  token?: string | null;
+  basePath?: string;
+}): AgentReadableResourceDiscovery {
+  return buildAgentReadableResourceDiscovery({
+    resourceType: "document",
+    resourceId: document.id,
+    title: document.title,
+    path: buildContentPublicDocumentPath(document.id),
+    contextEndpoint: DOCUMENT_AGENT_CONTEXT_ENDPOINT,
+    token,
+    basePath,
+    instructions: DOCUMENT_AGENT_READABLE_INSTRUCTIONS,
+  });
+}

package/corpus/templates/design/server/db/index.ts

@@ -1,6 +1,10 @@
 import { createGetDb } from "@agent-native/core/db";
 import { registerShareableResource } from "@agent-native/core/sharing";
 
+import {
+  DESIGN_AGENT_CONTEXT_ENDPOINT,
+  DESIGN_AGENT_RESOURCE_KIND,
+} from "../../shared/agent-readable.js";
 import * as schema from "./schema.js";
 
 export const getDb = createGetDb(schema);
@@ -63,6 +67,10 @@ registerShareableResource({
   displayName: "Design",
   titleColumn: "title",
   getResourcePath: (design) => `/design/${design.id}`,
+  agentReadable: {
+    resourceKind: DESIGN_AGENT_RESOURCE_KIND,
+    getContextPath: () => DESIGN_AGENT_CONTEXT_ENDPOINT,
+  },
   getDb,
   publicAccessRole: (design) =>
     isLoopbackLocalhostDesign(design) ? "editor" : "viewer",

package/corpus/templates/design/server/routes/[...page].get.ts

@@ -1,5 +1,98 @@
+import {
+  AGENT_ACCESS_PARAM,
+  getConfiguredAppBasePath,
+} from "@agent-native/core/server";
 import { createH3SSRHandler } from "@agent-native/core/server/ssr-handler";
+import {
+  buildAgentReadableResourceDiscovery,
+  renderAgentReadableResourceDiscoveryScript,
+} from "@agent-native/core/shared";
+import {
+  defineEventHandler,
+  getQuery,
+  getRequestURL,
+  setResponseHeader,
+} from "h3";
 
-export default createH3SSRHandler(
+import { DESIGN_AGENT_CONTEXT_ENDPOINT } from "../../shared/agent-readable.js";
+
+const ssrHandler = createH3SSRHandler(
   () => import("virtual:react-router/server-build"),
 );
+
+function stripBasePath(pathname: string): string {
+  const basePath = getConfiguredAppBasePath();
+  if (!basePath) return pathname;
+  if (pathname === basePath) return "/";
+  if (pathname.startsWith(`${basePath}/`)) {
+    return pathname.slice(basePath.length) || "/";
+  }
+  return pathname;
+}
+
+function designIdFromPath(pathname: string): string | null {
+  const match = stripBasePath(pathname).match(/^\/design\/([^/]+)\/?$/);
+  if (!match?.[1]) return null;
+  try {
+    return decodeURIComponent(match[1]);
+  } catch {
+    return match[1];
+  }
+}
+
+function queryString(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && typeof value[0] === "string") return value[0];
+  return "";
+}
+
+function injectScript(html: string, script: string): string {
+  if (html.includes("agent-native-design-agent-context")) return html;
+  if (html.includes("</head>"))
+    return html.replace("</head>", `${script}</head>`);
+  if (html.includes("</body>"))
+    return html.replace("</body>", `${script}</body>`);
+  return `${html}${script}`;
+}
+
+export default defineEventHandler(async (event) => {
+  const response = (await ssrHandler(event)) as Response;
+  const requestUrl = getRequestURL(event);
+  const designId = designIdFromPath(requestUrl.pathname);
+  if (!designId) return response;
+
+  const token = queryString(getQuery(event)[AGENT_ACCESS_PARAM]);
+  const script = renderAgentReadableResourceDiscoveryScript(
+    buildAgentReadableResourceDiscovery({
+      resourceType: "design",
+      resourceId: designId,
+      path: `/design/${designId}`,
+      contextEndpoint: DESIGN_AGENT_CONTEXT_ENDPOINT,
+      origin: requestUrl.origin,
+      basePath: getConfiguredAppBasePath(),
+      token,
+      instructions:
+        "Use contextUrl to read the current design handoff JSON. Token links are read-only and do not grant edit access.",
+    }),
+    { id: "agent-native-design-agent-context" },
+  );
+
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.includes("text/html")) return response;
+
+  const html = await response.text();
+  const headers = new Headers(response.headers);
+  headers.delete("content-length");
+  if (token) {
+    headers.set("Cache-Control", "private, max-age=0, no-store");
+    headers.set("Referrer-Policy", "no-referrer");
+    setResponseHeader(event, "Cache-Control", "private, max-age=0, no-store");
+    setResponseHeader(event, "Referrer-Policy", "no-referrer");
+  }
+
+  return new Response(injectScript(html, script), {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+});

package/corpus/templates/design/server/routes/api/design-agent-context.json.get.ts

@@ -0,0 +1,84 @@
+import {
+  AGENT_ACCESS_PARAM,
+  verifyScopedAgentAccessToken,
+} from "@agent-native/core/server";
+import { eq } from "drizzle-orm";
+import {
+  defineEventHandler,
+  getQuery,
+  setResponseHeader,
+  setResponseStatus,
+} from "h3";
+
+import { DESIGN_AGENT_RESOURCE_KIND } from "../../../shared/agent-readable.js";
+import { getDb, schema } from "../../db/index.js";
+import { buildDesignHandoffPayload } from "../../lib/coding-handoff.js";
+import { buildDesignSnapshot } from "../../lib/design-snapshot.js";
+
+function queryString(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && typeof value[0] === "string") return value[0];
+  return "";
+}
+
+export default defineEventHandler(async (event) => {
+  setResponseHeader(event, "Cache-Control", "no-store");
+  setResponseHeader(event, "Referrer-Policy", "no-referrer");
+  setResponseHeader(event, "X-Content-Type-Options", "nosniff");
+
+  const query = getQuery(event);
+  const id = queryString(query.id);
+  if (!id) {
+    setResponseStatus(event, 400);
+    return { error: "Design id is required" };
+  }
+
+  const token = queryString(query[AGENT_ACCESS_PARAM]);
+  const db = getDb();
+  // guard:allow-unscoped -- this endpoint returns a design handoff only when it is public or a design-scoped agent_access token verifies for this id.
+  const [design] = await db
+    .select()
+    .from(schema.designs)
+    .where(eq(schema.designs.id, id))
+    .limit(1);
+
+  if (!design) {
+    setResponseStatus(event, 404);
+    return { error: "Design not found" };
+  }
+
+  const tokenAccess = token
+    ? verifyScopedAgentAccessToken(token, {
+        resourceKind: DESIGN_AGENT_RESOURCE_KIND,
+        resourceId: id,
+      }).ok
+    : false;
+  if (design.visibility !== "public" && !tokenAccess) {
+    setResponseStatus(event, 403);
+    return { error: "Invalid or expired agent access token" };
+  }
+
+  const snapshot = await buildDesignSnapshot(id, design.data);
+  if (snapshot.files.length === 0) {
+    setResponseStatus(event, 404);
+    return { error: "This design has no files to hand off yet" };
+  }
+
+  return {
+    resourceType: "design",
+    id: design.id,
+    visibility: design.visibility,
+    url: `/design/${design.id}`,
+    handoff: buildDesignHandoffPayload({
+      design,
+      files: snapshot.files.map((f) => ({
+        filename: f.filename,
+        fileType: f.fileType,
+        content: f.content,
+      })),
+      resolvedCssVars: snapshot.resolvedCssVars,
+    }),
+    appliedTweaks: snapshot.appliedTweaks,
+    resolvedCssVars: snapshot.resolvedCssVars,
+  };
+});

package/corpus/templates/design/shared/agent-readable.ts

@@ -0,0 +1,2 @@
+export const DESIGN_AGENT_RESOURCE_KIND = "design:design";
+export const DESIGN_AGENT_CONTEXT_ENDPOINT = "/api/design-agent-context.json";

package/corpus/templates/plan/server/db/index.ts

@@ -1,6 +1,10 @@
 import { createGetDb } from "@agent-native/core/db";
 import { registerShareableResource } from "@agent-native/core/sharing";
 
+import {
+  PLAN_AGENT_CONTEXT_ENDPOINT,
+  PLAN_AGENT_RESOURCE_KIND,
+} from "../../shared/agent-readable.js";
 import { resolvePlanAccessContext } from "../lib/local-identity.js";
 import * as schema from "./schema.js";
 
@@ -17,6 +21,14 @@ registerShareableResource({
     (plan as { kind?: string }).kind === "recap"
       ? `/recaps/${plan.id}`
       : `/plans/${plan.id}`,
+  agentReadable: {
+    resourceKind: PLAN_AGENT_RESOURCE_KIND,
+    getContextPath: () => PLAN_AGENT_CONTEXT_ENDPOINT,
+    getPagePath: (plan) =>
+      (plan as { kind?: string }).kind === "recap"
+        ? `/recaps/${plan.id}`
+        : `/plans/${plan.id}`,
+  },
   getDb,
   resolveAccessContext: resolvePlanAccessContext,
 });

package/corpus/templates/plan/server/plans.ts

@@ -740,6 +740,30 @@ export async function loadPlanBundle(planId: string): Promise<PlanBundle> {
   if (plan.deletedAt) {
     throw new ForbiddenError(`Plan ${planId} not found`);
   }
+  return loadPlanBundleForAuthorizedPlan(planId, plan, access.role);
+}
+
+export async function loadPlanBundleForAgentAccess(
+  planId: string,
+): Promise<PlanBundle> {
+  const db = getDb();
+  // guard:allow-unscoped -- callers must verify a plan-scoped agent_access token before using this helper; it intentionally returns a read-only viewer bundle.
+  const [plan] = await db
+    .select()
+    .from(schema.plans)
+    .where(eq(schema.plans.id, planId))
+    .limit(1);
+  if (!plan || plan.deletedAt) {
+    throw new ForbiddenError(`Plan ${planId} not found`);
+  }
+  return loadPlanBundleForAuthorizedPlan(planId, plan, "viewer");
+}
+
+async function loadPlanBundleForAuthorizedPlan(
+  planId: string,
+  plan: typeof schema.plans.$inferSelect,
+  role: PlanBundle["access"]["role"],
+): Promise<PlanBundle> {
   const db = getDb();
   const [sectionRows, commentRows, eventRows] = await Promise.all([
     db
@@ -802,7 +826,7 @@ export async function loadPlanBundle(planId: string): Promise<PlanBundle> {
       deletedBy: plan.deletedBy,
     },
     access: {
-      role: access.role,
+      role,
       ownerEmail: plan.ownerEmail ?? null,
       orgId: plan.orgId ?? null,
       visibility: plan.visibility ?? "private",