Serve Orbit agent guide without stale cache

Author: sametbasbug

docs/V6_PROJECT_LEDGER.md

@@ -870,6 +870,13 @@ Bu dosya yalnız sonuçları değil; kararları, reddedilen alternatifleri, migr
 - No migration, dashboard visual change, public feed change or announcement
   body exposure was introduced. Announcement endpoints remain authenticated
   and `no-store`.
+- The first live smoke exposed a separate delivery hazard: the new Worker API
+  was active while the canonical bare `/skill.md` URL could still return the
+  previous guide body from the static asset cache; a cache-busted URL returned
+  `2.5.0`. The Worker now serves `machineAgentSkill` directly for GET/HEAD with
+  UTF-8, `nosniff` and `no-store, no-transform`, keeping the API and canonical
+  agent contract atomic across deploys instead of relying on asset-cache
+  invalidation.
 - Local proof passed: 95 D1/workerd tests, 63 content assertions, 74 CLI
   assertions, 1,807 site assertions, 352 browser assertions, Astro zero
   diagnostics, 54 production-config assertions and a production Worker

scripts/orbit-slice1-worker-tests.ts

@@ -273,12 +273,17 @@ describe('Orbit V6 deployment-mode contract', () => {
     assert.match(await robots.text(), /Allow: \//u);
   });
 
-  test('serves the machine guide with an explicit UTF-8 charset', async () => {
+  test('serves the current machine guide directly without stale asset caching', async () => {
     const env = productionBindings('live');
     const response = await worker.fetch(new Request(`${LIVE_ORIGIN}/skill.md`), env);
     assert.equal(response.status, 200);
     assert.equal(response.headers.get('content-type'), 'text/markdown; charset=utf-8');
-    assert.match(await response.text(), /Türkçe karakterler: ğüşöçıİ/u);
+    assert.equal(response.headers.get('cache-control'), 'no-store, no-transform');
+    assert.match(await response.text(), /version: 2\.5\.0/u);
+    const head = await worker.fetch(new Request(`${LIVE_ORIGIN}/skill.md`, { method: 'HEAD' }), env);
+    assert.equal(head.status, 200);
+    assert.equal(head.headers.get('cache-control'), 'no-store, no-transform');
+    assert.equal(await head.text(), '');
   });
 
   test('applies dashboard privacy and frame protection to GET and HEAD', async () => {

src/pages/skill.md.ts

@@ -3,7 +3,7 @@ import { machineAgentSkill } from '../data/agentOnboarding';
 export function GET() {
   return new Response(machineAgentSkill, {
     headers: {
-      'cache-control': 'public, max-age=300',
+      'cache-control': 'no-store, no-transform',
       'content-type': 'text/markdown; charset=utf-8',
       'x-content-type-options': 'nosniff',
     },

src/worker.ts

@@ -19,6 +19,7 @@ import { D1PublicRepository } from './server/repositories/d1/d1-public-repositor
 import type { AgentRepository } from './server/repositories/agent-repository';
 import type { PublicRepository } from './server/repositories/public-repository';
 import { serveDynamicPublicPage } from './server/public/response';
+import { machineAgentSkill } from './data/agentOnboarding';
 
 interface ExecutionContextLike {
   waitUntil(promise: Promise<unknown>): void;
@@ -45,11 +46,14 @@ function denyAllRobots(): Response {
   });
 }
 
-function preserveMachineGuideEncoding(request: Request, response: Response): Response {
-  if (new URL(request.url).pathname !== '/skill.md') return response;
-  const encodedResponse = new Response(response.body, response);
-  encodedResponse.headers.set('content-type', 'text/markdown; charset=utf-8');
-  return encodedResponse;
+function machineGuideResponse(method: string): Response {
+  return new Response(method === 'HEAD' ? null : machineAgentSkill, {
+    headers: {
+      'cache-control': 'no-store, no-transform',
+      'content-type': 'text/markdown; charset=utf-8',
+      'x-content-type-options': 'nosniff',
+    },
+  });
 }
 
 async function startStagingOAuth(request: Request, env: OrbitBindings): Promise<Response> {
@@ -89,6 +93,12 @@ export async function handleWorkerRequest(
     if (url.pathname === '/healthz') {
       return Response.json({ ok: true, service: 'orbit-v6', environment: env.ORBIT_ENVIRONMENT });
     }
+    if (
+      url.pathname === '/skill.md'
+      && (request.method === 'GET' || request.method === 'HEAD')
+    ) {
+      return machineGuideResponse(request.method);
+    }
     if (url.pathname.startsWith('/v1/')) {
       const response = await servePublicRead(request, env, async () => {
         const testNow = env.ORBIT_ENVIRONMENT === 'test'
@@ -125,7 +135,7 @@ export async function handleWorkerRequest(
       dependencies.agentRepository ?? new D1AgentRepository(env.DB),
     );
     if (publicPage) return publicPage;
-    return preserveMachineGuideEncoding(request, await env.ASSETS.fetch(request));
+    return await env.ASSETS.fetch(request);
   }, env.ORBIT_ENVIRONMENT);
   return protectFromIndexing(response, env);
 }