@nshipster/sosumi 1.0.8 → 1.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nshipster/sosumi",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Making Apple docs AI-readable",
   "license": "MIT",
   "author": "NSHipster",

package/public/index.html

@@ -11,6 +11,8 @@
     <meta name="robots" content="index, follow">
 
     <link rel="canonical" href="https://sosumi.ai/">
+    <link rel="ard" href="/.well-known/ard.json" type="application/ai-catalog+json">
+    <link rel="ai-catalog" href="/.well-known/ai-catalog.json" type="application/ai-catalog+json">
 
     <meta property="og:title" content="sosumi.ai - Apple Docs for LLMs">
     <meta property="og:description"
@@ -1057,4 +1059,4 @@ curl -o ~/.agents/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md</code></pre>
     </footer>
 </body>
 
-</html>
+</html>

package/public/robots.txt

@@ -1,5 +1,6 @@
 User-agent: *
 Content-Signal: search=yes, ai-input=yes, ai-train=no
+Content-Usage: train-ai=n, search=y
 Allow: /
 Disallow: /documentation/
 Disallow: /external/
@@ -7,3 +8,4 @@ Disallow: /design/human-interface-guidelines
 Disallow: /videos/play/
 
 Sitemap: https://sosumi.ai/sitemap.xml
+Agentmap: https://sosumi.ai/.well-known/ard.json

package/src/index.ts

@@ -5,7 +5,24 @@ import { cache } from "hono/cache"
 import { cors } from "hono/cors"
 import { HTTPException } from "hono/http-exception"
 import { trimTrailingSlash } from "hono/trailing-slash"
-import { buildAgentCard } from "./lib/a2a"
+import {
+  A2A_MEDIA_TYPE,
+  A2A_MESSAGE_PATH,
+  A2AError,
+  buildAgentCard,
+  capabilityError,
+  createA2AErrorResponse,
+  handleA2AMessage,
+  parseA2AListTasksQuery,
+  pushNotificationsNotSupported,
+  readA2ACapabilityText,
+  readA2AJsonBody,
+  taskNotFound,
+  unsupportedOperation,
+  validateA2ARequestHeaders,
+} from "./lib/a2a"
+import { AI_CATALOG_MEDIA_TYPE, buildAiCatalog } from "./lib/ard"
+import { buildDidDocument, DID_DOCUMENT_MEDIA_TYPE } from "./lib/did"
 import {
   decodeExternalTargetPath,
   ExternalAccessError,
@@ -51,6 +68,42 @@ interface Env {
 
 const app = new Hono<{ Bindings: Env }>()
 
+function requestedA2AVersion(request: Request): string | null {
+  return request.headers.get("A2A-Version") ?? new URL(request.url).searchParams.get("A2A-Version")
+}
+
+function fixedA2AError(request: Request, error: A2AError): Response {
+  try {
+    validateA2ARequestHeaders(
+      request.method === "POST" ? request.headers.get("Content-Type") : null,
+      requestedA2AVersion(request),
+    )
+    return createA2AErrorResponse(error)
+  } catch (headerError) {
+    return createA2AErrorResponse(headerError)
+  }
+}
+
+function taskIdFromPath(path: string): string {
+  const taskPath = path.slice("/tasks/".length)
+  const encodedTaskId = taskPath.split(/[:/]/, 1)[0] ?? ""
+  try {
+    return decodeURIComponent(encodedTaskId) || "unknown"
+  } catch {
+    return encodedTaskId || "unknown"
+  }
+}
+
+function isMarkdownContentRoute(path: string): boolean {
+  return (
+    path.startsWith("/documentation/") ||
+    path.startsWith("/external/") ||
+    path === "/design/human-interface-guidelines" ||
+    path.startsWith("/design/human-interface-guidelines/") ||
+    path.startsWith("/videos/play/")
+  )
+}
+
 app.use("*", async (c, next) => {
   // Prime Web Bot Auth signing before any route or outbound fetch runs.
   configureWebBotAuth(c.env)
@@ -63,6 +116,7 @@ app.use("*", async (c, next) => {
   c.header("X-XSS-Protection", "1; mode=block")
   c.header("Referrer-Policy", "strict-origin-when-cross-origin")
   c.header("Permissions-Policy", "camera=(), microphone=(), geolocation=()")
+  c.header("Content-Usage", "train-ai=n, search=y")
 
   // Performance headers
   c.header("Vary", "Accept")
@@ -72,18 +126,30 @@ app.use("*", async (c, next) => {
     c.header("Cache-Control", "no-store")
   }
 
+  const links = ['</llms.txt>; rel="describedby"']
+
   if (c.req.path === "/") {
-    c.header(
-      "Link",
-      [
-        '</.well-known/api-catalog>; rel="api-catalog"',
-        '</.well-known/agent-card.json>; rel="service-desc"; type="application/json"',
-        '</.well-known/mcp/server-card.json>; rel="service-desc"; type="application/json"',
-        '</SKILL.md>; rel="service-doc"',
-        '</llms.txt>; rel="alternate"; type="text/markdown"',
-      ].join(", "),
+    links.unshift(
+      '</.well-known/api-catalog>; rel="api-catalog"',
+      `</.well-known/ard.json>; rel="ard"; type="${AI_CATALOG_MEDIA_TYPE}"`,
+      `</.well-known/ai-catalog.json>; rel="ai-catalog"; type="${AI_CATALOG_MEDIA_TYPE}"`,
+      '</.well-known/agent-card.json>; rel="service-desc"; type="application/json"',
+      '</.well-known/mcp/server-card.json>; rel="service-desc"; type="application/json"',
+      '</SKILL.md>; rel="service-doc"',
+      '</llms.txt>; rel="alternate"; type="text/markdown"',
     )
   }
+
+  if (isMarkdownContentRoute(c.req.path)) {
+    links.push(`<${c.req.path}>; rel="alternate"; type="text/markdown"`)
+  }
+
+  const existingLink = c.res.headers.get("Link")
+  if (existingLink) {
+    links.unshift(existingLink)
+  }
+
+  c.header("Link", links.join(", "))
 })
 
 app.use("*", cors())
@@ -188,6 +254,51 @@ const discoveryHeaders = {
   "Cache-Control": "public, max-age=300, s-maxage=600",
 } as const
 
+const SECURITY_TXT_EXPIRY_MS = 364 * 24 * 60 * 60 * 1000 // 364 days
+
+app.get("/.well-known/security.txt", (c) => {
+  const expires = new Date(Date.now() + SECURITY_TXT_EXPIRY_MS).toISOString()
+  const origin = new URL(c.req.url).origin
+
+  return c.text(
+    [
+      "Contact: mailto:info@sosumi.ai",
+      `Expires: ${expires}`,
+      `Canonical: ${origin}/.well-known/security.txt`,
+      "Preferred-Languages: en",
+      "",
+    ].join("\n"),
+    200,
+    {
+      ...discoveryHeaders,
+      "Content-Type": "text/plain; charset=utf-8",
+    },
+  )
+})
+
+app.on("GET", ["/.well-known/ard.json", "/.well-known/ai-catalog.json"], (c) => {
+  const origin = new URL(c.req.url).origin
+
+  return c.json(buildAiCatalog(origin), 200, {
+    ...discoveryHeaders,
+    "Content-Type": `${AI_CATALOG_MEDIA_TYPE}; charset=utf-8`,
+  })
+})
+
+app.get("/.well-known/did.json", async (c) => {
+  const document = await buildDidDocument()
+  if (!document) {
+    return c.json({ error: "DID signing key is unavailable." }, 404, {
+      "Cache-Control": "no-store",
+    })
+  }
+
+  return c.json(document, 200, {
+    ...discoveryHeaders,
+    "Content-Type": `${DID_DOCUMENT_MEDIA_TYPE}; charset=utf-8`,
+  })
+})
+
 app.get("/.well-known/api-catalog", (c) => {
   const origin = new URL(c.req.url).origin
 
@@ -250,6 +361,73 @@ app.get("/.well-known/agent-card.json", (c) => {
   })
 })
 
+app.post(A2A_MESSAGE_PATH, async (c) => {
+  try {
+    validateA2ARequestHeaders(c.req.header("Content-Type") ?? null, requestedA2AVersion(c.req.raw))
+
+    const input = await readA2AJsonBody(c.req.raw)
+
+    const response = await handleA2AMessage(input, async (endpoint, outputMode) => {
+      const capabilityResponse = await app.request(
+        new URL(endpoint, c.req.url).toString(),
+        { headers: { Accept: outputMode } },
+        c.env,
+      )
+      const text = await readA2ACapabilityText(capabilityResponse)
+      if (!capabilityResponse.ok) {
+        throw capabilityError(
+          capabilityResponse.status,
+          text || `Sosumi capability request failed with status ${capabilityResponse.status}.`,
+        )
+      }
+      return text
+    })
+
+    return c.json(response, 200, {
+      "Content-Type": A2A_MEDIA_TYPE,
+      "Cache-Control": "no-store",
+    })
+  } catch (error) {
+    if (!(error instanceof A2AError)) {
+      console.error("A2A message execution failed", error)
+    }
+    return createA2AErrorResponse(error)
+  }
+})
+
+app.post("/message:stream", (c) =>
+  fixedA2AError(c.req.raw, unsupportedOperation("Streaming messages")),
+)
+
+app.get("/tasks", (c) => {
+  try {
+    validateA2ARequestHeaders(null, requestedA2AVersion(c.req.raw))
+    const pageSize = parseA2AListTasksQuery(new URL(c.req.url).searchParams)
+    return c.json({ tasks: [], nextPageToken: "", pageSize, totalSize: 0 }, 200, {
+      "Content-Type": A2A_MEDIA_TYPE,
+      "Cache-Control": "no-store",
+    })
+  } catch (error) {
+    return createA2AErrorResponse(error)
+  }
+})
+
+app.all("/tasks", (c) => fixedA2AError(c.req.raw, unsupportedOperation("This task operation")))
+
+app.all("/tasks/*", (c) => {
+  if (c.req.path.includes("/pushNotificationConfigs")) {
+    return fixedA2AError(c.req.raw, pushNotificationsNotSupported())
+  }
+  if (c.req.path.endsWith(":subscribe")) {
+    return fixedA2AError(c.req.raw, unsupportedOperation("Task subscriptions"))
+  }
+  return fixedA2AError(c.req.raw, taskNotFound(taskIdFromPath(c.req.path)))
+})
+
+app.get("/extendedAgentCard", (c) =>
+  fixedA2AError(c.req.raw, unsupportedOperation("Extended Agent Cards")),
+)
+
 app.get("/webmcp/manifest.json", (c) =>
   c.json(buildWebMcpManifest(), 200, {
     ...discoveryHeaders,