@agent-native/core 0.87.0 → 0.88.0

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

@@ -1,5 +1,111 @@
+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 { PLAN_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 planFromPath(pathname: string): {
+  id: string;
+  kind: "plan" | "recap";
+} | null {
+  const stripped = stripBasePath(pathname);
+  const match = stripped.match(/^\/(plans|recaps)\/([^/]+)\/?$/);
+  if (!match?.[1] || !match[2]) return null;
+  try {
+    return {
+      kind: match[1] === "recaps" ? "recap" : "plan",
+      id: decodeURIComponent(match[2]),
+    };
+  } catch {
+    return {
+      kind: match[1] === "recaps" ? "recap" : "plan",
+      id: match[2],
+    };
+  }
+}
+
+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-plan-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 resource = planFromPath(requestUrl.pathname);
+  if (!resource) return response;
+
+  const token = queryString(getQuery(event)[AGENT_ACCESS_PARAM]);
+  const script = renderAgentReadableResourceDiscoveryScript(
+    buildAgentReadableResourceDiscovery({
+      resourceType: "plan",
+      resourceId: resource.id,
+      path:
+        resource.kind === "recap"
+          ? `/recaps/${resource.id}`
+          : `/plans/${resource.id}`,
+      contextEndpoint: PLAN_AGENT_CONTEXT_ENDPOINT,
+      origin: requestUrl.origin,
+      basePath: getConfiguredAppBasePath(),
+      token,
+      instructions:
+        "Use contextUrl to read the visual plan bundle as structured JSON. Token links are read-only.",
+    }),
+    { id: "agent-native-plan-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/plan/server/routes/api/plan-agent-context.json.get.ts

@@ -0,0 +1,65 @@
+import {
+  AGENT_ACCESS_PARAM,
+  verifyScopedAgentAccessToken,
+} from "@agent-native/core/server";
+import {
+  defineEventHandler,
+  getQuery,
+  setResponseHeader,
+  setResponseStatus,
+} from "h3";
+
+import { PLAN_AGENT_RESOURCE_KIND } from "../../../shared/agent-readable.js";
+import { loadPlanBundle, loadPlanBundleForAgentAccess } from "../../plans.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: "Plan id is required" };
+  }
+
+  const token = queryString(query[AGENT_ACCESS_PARAM]);
+  try {
+    const tokenAccess = token
+      ? verifyScopedAgentAccessToken(token, {
+          resourceKind: PLAN_AGENT_RESOURCE_KIND,
+          resourceId: id,
+        }).ok
+      : false;
+    const bundle = tokenAccess
+      ? await loadPlanBundleForAgentAccess(id)
+      : await loadPlanBundle(id);
+
+    return {
+      resourceType: "plan",
+      id: bundle.plan.id,
+      title: bundle.plan.title,
+      kind: bundle.plan.kind,
+      access: bundle.access,
+      plan: bundle.plan,
+      sections: bundle.sections,
+      comments: bundle.comments,
+      events: bundle.events,
+      summary: bundle.summary,
+      url:
+        bundle.plan.kind === "recap"
+          ? `/recaps/${bundle.plan.id}`
+          : `/plans/${bundle.plan.id}`,
+    };
+  } catch (error: any) {
+    setResponseStatus(event, error?.statusCode === 403 ? 403 : 404);
+    return { error: "Plan not found" };
+  }
+});

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

@@ -0,0 +1,2 @@
+export const PLAN_AGENT_RESOURCE_KIND = "plan:plan";
+export const PLAN_AGENT_CONTEXT_ENDPOINT = "/api/plan-agent-context.json";

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

@@ -1,4 +1,13 @@
-import { getConfiguredAppBasePath } from "@agent-native/core/server";
+import {
+  AGENT_ACCESS_PARAM,
+  getConfiguredAppBasePath,
+  verifyScopedAgentAccessToken,
+} from "@agent-native/core/server";
+import {
+  AGENT_READABLE_RESOURCE_SCRIPT_TYPE,
+  buildAgentReadableResourceDiscovery,
+  safeJsonForHtml,
+} from "@agent-native/core/shared";
 import {
   toSharedDeckSlide,
   type SharedDeckResponse,
@@ -6,15 +15,29 @@ import {
 } from "@shared/api";
 import { eq } from "drizzle-orm";
 import { useEffect } from "react";
-import type { LoaderFunctionArgs, MetaFunction } from "react-router";
-import { useLoaderData } from "react-router";
+import type {
+  HeadersArgs,
+  LoaderFunctionArgs,
+  MetaFunction,
+} from "react-router";
+import { data, useLoaderData } from "react-router";
 
 import SharedPresentation from "@/pages/SharedPresentation";
 
 import { getDb, schema } from "../../server/db";
+import {
+  DECK_AGENT_CONTEXT_ENDPOINT,
+  DECK_AGENT_RESOURCE_KIND,
+} from "../../shared/agent-readable";
 
 type LoaderData =
-  | { deck: SharedDeckResponse; error?: undefined }
+  | {
+      deck: SharedDeckResponse;
+      error?: undefined;
+      id: string;
+      basePath: string;
+      agentAccessToken?: string | null;
+    }
   | {
       deck: null;
       error: string;
@@ -34,6 +57,22 @@ type DeckData = {
   aspectRatio?: SharedDeckResponse["aspectRatio"];
 };
 
+const PRIVATE_AGENT_DECK_HEADERS = {
+  "Cache-Control": "private, max-age=0, no-store",
+  "Referrer-Policy": "no-referrer",
+};
+
+function publicDeckLoaderData(payload: LoaderData, privateAgentAccess = false) {
+  if (!privateAgentAccess) return payload;
+  return data(payload, {
+    headers: PRIVATE_AGENT_DECK_HEADERS,
+  });
+}
+
+export function headers({ loaderHeaders }: HeadersArgs) {
+  return loaderHeaders;
+}
+
 function toSharedDeck(row: {
   title: string | null;
   data: string;
@@ -48,11 +87,13 @@ function toSharedDeck(row: {
   };
 }
 
-export async function loader({
-  params,
-}: LoaderFunctionArgs): Promise<LoaderData> {
+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,
+  );
+  const basePath = getConfiguredAppBasePath();
 
   // Access is checked on the deck, not the URL shape: `/p/<id>` (presentation)
   // and `/deck/<id>` (editor) share the same rules. SSR renders impersonally (no
@@ -76,12 +117,28 @@ export async function loader({
     .limit(1);
 
   if (!deck) throw new Response("Not found", { status: 404 });
-  if (deck.visibility === "public") return { deck: toSharedDeck(deck) };
-  return {
+  const tokenAccess = agentAccessToken
+    ? verifyScopedAgentAccessToken(agentAccessToken, {
+        resourceKind: DECK_AGENT_RESOURCE_KIND,
+        resourceId: id,
+      }).ok
+    : false;
+  if (deck.visibility === "public" || tokenAccess) {
+    return publicDeckLoaderData(
+      {
+        deck: toSharedDeck(deck),
+        id,
+        basePath,
+        agentAccessToken: tokenAccess ? agentAccessToken : null,
+      },
+      tokenAccess,
+    );
+  }
+  return publicDeckLoaderData({
     deck: null,
     error: "restricted",
-    restricted: { id, basePath: getConfiguredAppBasePath() },
-  };
+    restricted: { id, basePath },
+  });
 }
 
 export const meta: MetaFunction<typeof loader> = ({ loaderData }) => {
@@ -101,8 +158,65 @@ export default function PublicDeckRoute() {
 
   // Redirecting to the guarded editor to resolve per-user access client-side.
   if (restricted) return null;
+  if (data.deck === null) {
+    return (
+      <SharedPresentation initialDeck={data.deck} initialError={data.error} />
+    );
+  }
 
   return (
-    <SharedPresentation initialDeck={data.deck} initialError={data.error} />
+    <>
+      <AgentReadableDeckDiscovery
+        id={data.id}
+        title={data.deck.title}
+        basePath={data.basePath}
+        token={data.agentAccessToken}
+      />
+      <SharedPresentation initialDeck={data.deck} initialError={data.error} />
+    </>
+  );
+}
+
+export function buildDeckDiscovery({
+  id,
+  title,
+  basePath,
+  token,
+}: {
+  id: string;
+  title?: string;
+  basePath?: string;
+  token?: string | null;
+}) {
+  return buildAgentReadableResourceDiscovery({
+    resourceType: "deck",
+    resourceId: id,
+    title,
+    path: `/p/${id}`,
+    contextEndpoint: DECK_AGENT_CONTEXT_ENDPOINT,
+    basePath,
+    token,
+    instructions:
+      "Use contextUrl to read this shared Slides deck as JSON. Slide numbers are 1-based for users.",
+  });
+}
+
+function AgentReadableDeckDiscovery({
+  id,
+  title,
+  basePath,
+  token,
+}: {
+  id: string;
+  title?: string;
+  basePath?: string;
+  token?: string | null;
+}) {
+  const discovery = buildDeckDiscovery({ id, title, basePath, token });
+  return (
+    <script
+      type={AGENT_READABLE_RESOURCE_SCRIPT_TYPE}
+      dangerouslySetInnerHTML={{ __html: safeJsonForHtml(discovery) }}
+    />
   );
 }

package/corpus/templates/slides/app/routes/share.$token.tsx

@@ -1,12 +1,17 @@
+import {
+  AGENT_READABLE_RESOURCE_PAYLOAD_TYPE,
+  AGENT_READABLE_RESOURCE_SCRIPT_TYPE,
+  safeJsonForHtml,
+} from "@agent-native/core/shared";
 import type { SharedDeckResponse } from "@shared/api";
 import type { LoaderFunctionArgs } from "react-router";
-import { useLoaderData } from "react-router";
+import { useLoaderData, useParams } from "react-router";
 
 import messages from "@/i18n/en-US";
 import SharedPresentation from "@/pages/SharedPresentation";
 
 type LoaderData =
-  | { deck: SharedDeckResponse; error?: undefined }
+  | { deck: SharedDeckResponse; error?: undefined; basePath: string }
   | { deck: null; error: string };
 
 function normalizeBasePath(value: string | undefined): string {
@@ -30,10 +35,8 @@ export async function loader({
     return { deck: null, error: "Token is required" };
   }
 
-  const url = new URL(
-    `${appBasePathForRequest()}/api/share/${params.token}`,
-    requestUrl,
-  );
+  const basePath = appBasePathForRequest();
+  const url = new URL(`${basePath}/api/share/${params.token}`, requestUrl);
   const res = await fetch(url, { headers: { accept: "application/json" } });
   const data = await res.json().catch(() => null);
 
@@ -44,7 +47,7 @@ export async function loader({
     };
   }
 
-  return { deck: data as SharedDeckResponse };
+  return { deck: data as SharedDeckResponse, basePath };
 }
 
 export function meta() {
@@ -54,6 +57,50 @@ export function meta() {
 export default function SharedPresentationRoute() {
   const data = useLoaderData<typeof loader>();
   return (
-    <SharedPresentation initialDeck={data.deck} initialError={data.error} />
+    <>
+      {data.deck ? (
+        <SnapshotDiscovery deck={data.deck} basePath={data.basePath} />
+      ) : null}
+      <SharedPresentation initialDeck={data.deck} initialError={data.error} />
+    </>
+  );
+}
+
+export function buildSnapshotDiscovery({
+  deck,
+  token,
+  basePath,
+}: {
+  deck: SharedDeckResponse;
+  token: string;
+  basePath?: string;
+}) {
+  const normalizedBasePath = normalizeBasePath(basePath);
+  return {
+    type: AGENT_READABLE_RESOURCE_PAYLOAD_TYPE,
+    resourceType: "deck-snapshot",
+    resourceId: token,
+    title: deck.title,
+    contextUrl: `${normalizedBasePath}/api/share/${encodeURIComponent(token)}`,
+    instructions:
+      "Use contextUrl to read this shared Slides snapshot as JSON. This snapshot link is independent of live deck visibility.",
+  };
+}
+
+function SnapshotDiscovery({
+  deck,
+  basePath,
+}: {
+  deck: SharedDeckResponse;
+  basePath: string;
+}) {
+  const { token } = useParams<{ token: string }>();
+  if (!token) return null;
+  const discovery = buildSnapshotDiscovery({ deck, token, basePath });
+  return (
+    <script
+      type={AGENT_READABLE_RESOURCE_SCRIPT_TYPE}
+      dangerouslySetInnerHTML={{ __html: safeJsonForHtml(discovery) }}
+    />
   );
 }

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

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

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

@@ -0,0 +1,97 @@
+import {
+  AGENT_ACCESS_PARAM,
+  verifyScopedAgentAccessToken,
+} from "@agent-native/core/server";
+import { toSharedDeckSlide } from "@shared/api";
+import { eq } from "drizzle-orm";
+import {
+  defineEventHandler,
+  getQuery,
+  setResponseHeader,
+  setResponseStatus,
+} from "h3";
+
+import { DECK_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 parseDeckData(value: string): Record<string, any> {
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    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: "Deck id is required" };
+  }
+
+  const token = queryString(query[AGENT_ACCESS_PARAM]);
+  const db = getDb();
+  // guard:allow-unscoped -- this endpoint returns a deck only when it is public or a deck-scoped agent_access token verifies for this id.
+  const [deck] = await db
+    .select({
+      id: schema.decks.id,
+      title: schema.decks.title,
+      data: schema.decks.data,
+      visibility: schema.decks.visibility,
+      designSystemId: schema.decks.designSystemId,
+      createdAt: schema.decks.createdAt,
+      updatedAt: schema.decks.updatedAt,
+    })
+    .from(schema.decks)
+    .where(eq(schema.decks.id, id))
+    .limit(1);
+
+  if (!deck) {
+    setResponseStatus(event, 404);
+    return { error: "Deck not found" };
+  }
+
+  const tokenAccess = token
+    ? verifyScopedAgentAccessToken(token, {
+        resourceKind: DECK_AGENT_RESOURCE_KIND,
+        resourceId: id,
+      }).ok
+    : false;
+  if (deck.visibility !== "public" && !tokenAccess) {
+    setResponseStatus(event, 403);
+    return { error: "Invalid or expired agent access token" };
+  }
+
+  const data = parseDeckData(deck.data);
+  const slides = Array.isArray(data.slides)
+    ? data.slides.map((slide: unknown, index: number) =>
+        toSharedDeckSlide(slide, index),
+      )
+    : [];
+
+  return {
+    resourceType: "deck",
+    id: deck.id,
+    title: deck.title || data.title || "Untitled",
+    visibility: deck.visibility,
+    designSystemId: deck.designSystemId ?? null,
+    slideCount: slides.length,
+    aspectRatio: data.aspectRatio ?? null,
+    slides,
+    createdAt: deck.createdAt,
+    updatedAt: deck.updatedAt,
+    url: `/p/${deck.id}`,
+  };
+});

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

@@ -0,0 +1,2 @@
+export const DECK_AGENT_RESOURCE_KIND = "slides:deck";
+export const DECK_AGENT_CONTEXT_ENDPOINT = "/api/deck-agent-context.json";

package/dist/collab/routes.d.ts

@@ -41,9 +41,9 @@ export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import
  * Body: { text: string, fieldName?: string, requestSource?: string }
  */
 export declare const postCollabText: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    text?: undefined;
     ok?: undefined;
     error: string;
+    text?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/collab/struct-routes.d.ts

@@ -13,8 +13,8 @@
  * Body: { json: any, fieldName?: string, type?: "map"|"array", requestSource?: string }
  */
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/notifications/routes.d.ts

@@ -28,7 +28,7 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
 } | {
     count?: undefined;
     updated?: undefined;
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;
 //# sourceMappingURL=routes.d.ts.map

package/dist/observability/routes.d.ts

@@ -41,28 +41,28 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
-    error?: undefined;
-    ok?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
-} | {
     error?: undefined;
     ok?: undefined;
+} | {
     summary?: undefined;
     spans?: undefined;
     id: string;
-} | {
+    error?: undefined;
     ok?: undefined;
+} | {
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     error: any;
+    ok?: undefined;
 } | {
-    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
+    error?: undefined;
     ok: boolean;
 }>>;
 //# sourceMappingURL=routes.d.ts.map

package/dist/progress/routes.d.ts

@@ -15,7 +15,7 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;
 //# sourceMappingURL=routes.d.ts.map

package/dist/provider-api/corpus-jobs.d.ts

@@ -73,7 +73,6 @@ export declare function createProviderCorpusJobAction(options: CreateProviderCor
     offset?: unknown;
     limit?: unknown;
 }, {
-    deleted?: undefined;
     jobs: {
         id: string;
         name: string;
@@ -84,6 +83,7 @@ export declare function createProviderCorpusJobAction(options: CreateProviderCor
         updatedAt: string;
     }[];
     total: number;
+    deleted?: undefined;
     jobId?: undefined;
 } | {
     jobs?: undefined;
@@ -91,9 +91,9 @@ export declare function createProviderCorpusJobAction(options: CreateProviderCor
     deleted: boolean;
     jobId: string;
 } | {
-    deleted?: undefined;
     jobs?: undefined;
     total?: undefined;
+    deleted?: undefined;
     jobId?: undefined;
     hits: Record<string, unknown>[];
     offset: number;