Merge pull request #11 from block/codex/surface-policy-simplification

Introduce SurfacePolicy front door

Author: nahiyankhan

.agents/skills/summon/SKILL.md

@@ -28,7 +28,8 @@ Follow this path unless the user explicitly asks for a runtime redesign:
 
 ```txt
 host capability registry
-  -> SurfacePlan: purpose/runtime/data/authority/persistence
+  -> SurfacePolicy: tier/grants/components/purpose/persistence
+  -> compiled SurfacePlan: purpose/runtime/data/authority/persistence
   -> createCapabilityRegistry(...).toContract()
   -> compileSystemContracts()
   -> protocol hardener and repair feedback
@@ -37,8 +38,8 @@ host capability registry
 ```
 
 Capabilities are host-owned. The model sees the contract; the host owns
-handlers, network, credentials, state, grants, and the selected `SurfacePlan`.
-Generated artifacts must not emit or widen `/surface-plan`.
+handlers, network, credentials, state, grants, and the selected `SurfacePolicy`.
+Generated artifacts must not emit or widen `/surface-policy` or `/surface-plan`.
 
 New generation servers should prefer `runSurfaceGeneration(input, emit)` from
 `@anarchitecture/summon-server`; `generateSurfaceStream()` remains available for
@@ -70,8 +71,9 @@ host approval adapter.
 
 For generation failures, inspect `/error`, `/validation-summary`,
 `/validation-blocked`, `/repair-feedback`, `/repair-summary`,
-`/stream-graph-summary`, `/protocol-skip`, `/surface-plan`, `/shape`,
-`/token-overrides`, `/screen-synthesized`, and `/mode-upgraded`.
+`/stream-graph-summary`, `/protocol-skip`, `/surface-policy`,
+`/surface-plan`, `/shape`, `/token-overrides`, `/screen-synthesized`, and
+`/mode-upgraded`.
 
 For client behavior, inspect Devtools events: `surface-plan`, `protocol-line`,
 `protocol-parse-error`, `sandbox-ready`, `render`, `intent-emitted`,
@@ -80,7 +82,7 @@ For client behavior, inspect Devtools events: `surface-plan`, `protocol-line`,
 
 Use `ContractIssue` plus `hintsForContractIssue(issue)` when feeding validation
 problems back to a model or another agent. For surface problems, check whether
-the requested runtime, data source, or authority exceeds the selected
+the requested grant/component exceeds the selected `SurfacePolicy` or compiled
 `SurfacePlan`.
 
 ## Commands

README.md

@@ -63,7 +63,8 @@ Summon's supported integration path is intentionally narrow:
 
 ```txt
 host capability registry
-  -> SurfacePlan: purpose/runtime/data/authority/persistence
+  -> SurfacePolicy: tier/grants/components/purpose/persistence
+  -> compiled SurfacePlan: purpose/runtime/data/authority/persistence
   -> createCapabilityRegistry(...).toContract()
   -> compileSystemContracts()
   -> protocol hardener + repair feedback
@@ -74,18 +75,16 @@ host capability registry
 No generated artifact gets to mint permissions for itself. Artifact-declared
 intents are advisory; execution is governed by host grants.
 
-Surface planning is Summon's lifecycle layer. A host can declare the minimum
-safe surface across purpose, runtime, data, authority, and persistence before
-generation starts. The model sees that plan as a contract but cannot widen it.
-Prompt-based `suggestSurfacePlan()` output is only advisory host UI scaffolding;
-generation falls back to no host data or authority unless the host submits an
-explicit accepted `SurfacePlan`.
+Surface policy is Summon's lifecycle layer. A host declares the public tier,
+grants, trusted components, purpose, and persistence before generation starts.
+Summon compiles that policy into the stricter `SurfacePlan` contract the model
+sees and cannot widen.
 
 ## Demo Map
 
 - `examples/surface-gallery` - first-run OSS gallery with curated live presets,
   compact host contracts, a sandboxed surface, and a small event strip.
-- `/generate.html` - contract cockpit with scenario grants, surface plans,
+- `/generate.html` - contract cockpit with scenario grants, compiled surface plans,
   static/declarative/scripted/worker tiers, component islands, host resources,
   token overrides, repair diagnostics, edit/replay, Ghost steering, Devtools,
   and stream graph events.

apps/demo/src/generate-main.ts

@@ -12,28 +12,28 @@ import {
   parseSurfaceEnvelope,
   type SurfaceEnvelope,
 } from '@anarchitecture/summon/envelope';
-import {
-  parseTokenValues,
-  SectionAccumulator,
-  type ProtocolLine,
-  type SummonLayout,
-  type ValidationCapability,
-  type ValidationComponent,
-} from '@anarchitecture/summon/engine';
 import {
   deriveSurfacePlanControls,
   normalizeSurfacePlan,
-  PolicyEngine,
+  parseTokenValues,
+  SectionAccumulator,
   SURFACE_AUTHORITY_VALUES,
   SURFACE_DATA_VALUES,
   SURFACE_PERSISTENCE_VALUES,
   SURFACE_PURPOSE_VALUES,
   SURFACE_RUNTIME_VALUES,
   type CapabilityPack,
   type ComponentPack,
+  type ProtocolLine,
   type ScriptPolicy,
+  type SummonLayout,
   type SurfaceCeiling,
   type SurfacePlan,
+  type ValidationCapability,
+  type ValidationComponent,
+} from '@anarchitecture/summon/engine';
+import {
+  PolicyEngine,
 } from '@anarchitecture/summon';
 import { createEventStore, type DevtoolsEvent } from '@anarchitecture/summon/devtools';
 import bootstrapSource from '@anarchitecture/summon/bootstrap.js?raw';

apps/demo/src/showcase.test.ts

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { deriveSurfacePlanControls } from '@anarchitecture/summon';
+import { deriveSurfacePlanControls } from '@anarchitecture/summon/engine';
 import {
   createScopedDemoRegistry,
   narrowCapabilityPack,

apps/demo/src/showcase.ts

@@ -3,7 +3,7 @@ import type {
   ScriptPolicy,
   SurfacePlan,
   SurfacePlanMode,
-} from '@anarchitecture/summon';
+} from '@anarchitecture/summon/engine';
 import type { CapabilityRegistry } from '@anarchitecture/summon';
 import { createDemoCapabilityRegistry, type DemoHandlerOptions } from './capabilities.js';
 

apps/server/src/capability-pack.ts

@@ -55,7 +55,11 @@ export function parseCapabilityPack(raw: unknown): CapabilityPack | null {
       if (!r || typeof r !== 'object') continue;
       const p = r as Record<string, unknown>;
       if (typeof p.name !== 'string' || typeof p.code !== 'string') continue;
-      patterns.push({ name: p.name.slice(0, 100), code: p.code.slice(0, 4000) });
+      patterns.push({
+        name: p.name.slice(0, 100),
+        code: p.code.slice(0, 4000),
+        ...(typeof p.intent === 'string' && p.intent ? { intent: p.intent.slice(0, 40) } : {}),
+      });
       if (patterns.length >= 12) break;
     }
   }

apps/server/src/generate-route.test.ts

@@ -6,8 +6,12 @@ import { createServer, type IncomingMessage } from 'node:http';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import test from 'node:test';
-import type { CapabilityPack, SurfaceCeiling, SurfacePlan } from '@anarchitecture/summon';
-import type { ProtocolLine } from '@anarchitecture/summon/engine';
+import type {
+  CapabilityPack,
+  ProtocolLine,
+  SurfaceCeiling,
+  SurfacePlan,
+} from '@anarchitecture/summon/engine';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(here, '..');
@@ -171,6 +175,55 @@ test('api generate sends narrowed contract and stream meta shape through package
   assert.equal((lines[1] as Extract<ProtocolLine, { op: 'meta' }>).value, 'writing');
   assert.equal(lines.at(-1)?.path, '/stream-graph-summary');
   assert.equal(lines.some((line) => line.path === '/error'), false);
+
+  const policyResponse = await fetch(`http://127.0.0.1:${appPort}/api/generate`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      prompt: 'build a dinner finder where i can search',
+      mode: 'static',
+      scriptPolicy: 'allow',
+      surfacePolicy: {
+        tier: 'declarative',
+        purpose: 'explore',
+        grants: ['search'],
+      },
+      capabilities: searchCapability,
+    }),
+  });
+  const policyBody = await policyResponse.text();
+  assert.equal(policyResponse.status, 200, policyBody);
+
+  assert.equal(anthropicRequests.length, 2);
+  const policyRequest = anthropicRequests[1] as { system?: Array<{ text?: string }>; stream?: boolean };
+  assert.equal(policyRequest.stream, true);
+  const policySystemText = policyRequest.system?.map((block) => block.text ?? '').join('\n') ?? '';
+  assert.match(policySystemText, /Search host-owned dinner data/);
+  assert.match(policySystemText, /Surface plan/);
+  assert.match(policySystemText, /Runtime: `declarative`/);
+  assert.match(policySystemText, /Data: `host-resource`/);
+  assert.doesNotMatch(policySystemText, /Rules for scripts/);
+
+  const policyLines = policyBody
+    .trim()
+    .split(/\n/)
+    .filter(Boolean)
+    .map((raw) => JSON.parse(raw) as ProtocolLine);
+  assert.deepEqual(policyLines.slice(0, 4).map((line) => `${line.op} ${line.path}`), [
+    'meta /surface-policy',
+    'meta /surface-plan',
+    'meta /status',
+    'set /screen',
+  ]);
+  assert.equal(policyLines.some((line) => line.path === '/mode-upgraded'), false);
+  assert.deepEqual((policyLines[0] as Extract<ProtocolLine, { op: 'meta' }>).value, {
+    tier: 'declarative',
+    purpose: 'explore',
+    grants: ['search'],
+    components: [],
+    persistence: 'replayable',
+  });
+  assert.deepEqual((policyLines[1] as Extract<ProtocolLine, { op: 'meta' }>).value, surfacePlan);
 });
 
 function sse(event: string, data: unknown): string {

apps/server/src/main.ts

@@ -2,14 +2,14 @@ import express from 'express';
 import cors from 'cors';
 import Anthropic from '@anthropic-ai/sdk';
 import {
-  type CapabilityPack,
-  type ScriptPolicy,
-} from '@anarchitecture/summon';
-import {
+  compileSurfacePolicy,
   parseTokenValues,
+  type CapabilityPack,
   type ContractPromptBlock,
   type ProtocolLine,
+  type ScriptPolicy,
   type SummonLayout,
+  type SurfacePlan,
   type TokenOverride,
 } from '@anarchitecture/summon/engine';
 import {
@@ -516,6 +516,8 @@ app.post('/api/generate', async (req, res) => {
   const edit = parsedEdit.edit;
   const repairOptions = parseRepairOptions(req.body?.repair);
 
+  const hasSurfacePolicy =
+    req.body?.surfacePolicy !== undefined && req.body.surfacePolicy !== null;
   const requestedMode: 'static' | 'interactive' =
     req.body?.mode === 'interactive' ? 'interactive' : 'static';
   let scriptPolicy: ScriptPolicy | undefined =
@@ -527,6 +529,7 @@ app.post('/api/generate', async (req, res) => {
   let pack: CapabilityPack | null = null;
   let modeUpgraded = false;
   let inferenceUsed = false;
+  let surfacePlan: SurfacePlan;
 
   // Shape classification — picks ONE response shape so the per-direction
   // block ships only the matching shape exemplar (atoms always ship). Falls
@@ -539,53 +542,64 @@ app.post('/api/generate', async (req, res) => {
     shape = await inferShape(anthropic, prompt);
   }
 
-  // Layer 3: Haiku-based capability inference. Decides mode + narrows the
-  // pack to the minimal subset of intents the prompt actually needs. The
-  // pack is treated as a ceiling — inference can only narrow, never expand.
-  // Falls through to the Layer 2 regex on timeout or error.
-  if (process.env.SUMMON_INFER_CAPABILITIES === '1' && capabilityCeiling) {
-    const inferred = await inferPack(anthropic, prompt, capabilityCeiling);
-    if (inferred) {
-      inferenceUsed = true;
-      if (requestedMode === 'interactive') {
-        // Respect the user's explicit interactive choice. Haiku may narrow
-        // the pack, but won't downgrade to static.
-        mode = 'interactive';
-        pack = inferred.pack ?? capabilityCeiling;
-      } else {
-        mode = inferred.mode;
-        pack = inferred.pack;
-        modeUpgraded = mode === 'interactive';
+  if (hasSurfacePolicy) {
+    const compiledPolicy = compileSurfacePolicy(req.body.surfacePolicy, {
+      capabilities: capabilityCeiling,
+      components: componentPack,
+    });
+    mode = compiledPolicy.mode;
+    scriptPolicy = compiledPolicy.scriptPolicy;
+    pack = compiledPolicy.capabilities;
+    surfacePlan = compiledPolicy.surfacePlan;
+  } else {
+    // Layer 3: Haiku-based capability inference. Decides mode + narrows the
+    // pack to the minimal subset of intents the prompt actually needs. The
+    // pack is treated as a ceiling — inference can only narrow, never expand.
+    // Falls through to the Layer 2 regex on timeout or error.
+    if (process.env.SUMMON_INFER_CAPABILITIES === '1' && capabilityCeiling) {
+      const inferred = await inferPack(anthropic, prompt, capabilityCeiling);
+      if (inferred) {
+        inferenceUsed = true;
+        if (requestedMode === 'interactive') {
+          // Respect the user's explicit interactive choice. Haiku may narrow
+          // the pack, but won't downgrade to static.
+          mode = 'interactive';
+          pack = inferred.pack ?? capabilityCeiling;
+        } else {
+          mode = inferred.mode;
+          pack = inferred.pack;
+          modeUpgraded = mode === 'interactive';
+        }
       }
     }
-  }
 
-  // Layer 2 regex fallback — runs when inference is disabled, ceiling is
-  // missing, or Haiku returned null (timeout/parse failure). Only upgrades
-  // when a ceiling exists; without one there's no Capabilities block to emit.
-  if (!inferenceUsed) {
-    if (requestedMode === 'static' && capabilityCeiling && detectsInteractiveIntent(prompt)) {
-      mode = 'interactive';
-      modeUpgraded = true;
+    // Layer 2 regex fallback — runs when inference is disabled, ceiling is
+    // missing, or Haiku returned null (timeout/parse failure). Only upgrades
+    // when a ceiling exists; without one there's no Capabilities block to emit.
+    if (!inferenceUsed) {
+      if (requestedMode === 'static' && capabilityCeiling && detectsInteractiveIntent(prompt)) {
+        mode = 'interactive';
+        modeUpgraded = true;
+      }
+      pack = mode === 'interactive' ? capabilityCeiling : null;
     }
-    pack = mode === 'interactive' ? capabilityCeiling : null;
-  }
 
-  const resolvedSurface = resolveSurfaceGenerationPlan({
-    prompt,
-    mode,
-    scriptPolicy,
-    capabilities: pack,
-    rawSurfacePlan: req.body?.surfacePlan,
-    rawSurfaceCeiling: req.body?.surfaceCeiling,
-  });
-  if (mode !== resolvedSurface.mode) {
-    modeUpgraded = mode === 'static' && resolvedSurface.mode === 'interactive' ? true : modeUpgraded;
-    mode = resolvedSurface.mode;
-    pack = mode === 'interactive' ? pack ?? capabilityCeiling : null;
+    const resolvedSurface = resolveSurfaceGenerationPlan({
+      prompt,
+      mode,
+      scriptPolicy,
+      capabilities: pack,
+      rawSurfacePlan: req.body?.surfacePlan,
+      rawSurfaceCeiling: req.body?.surfaceCeiling,
+    });
+    if (mode !== resolvedSurface.mode) {
+      modeUpgraded = mode === 'static' && resolvedSurface.mode === 'interactive' ? true : modeUpgraded;
+      mode = resolvedSurface.mode;
+      pack = mode === 'interactive' ? pack ?? capabilityCeiling : null;
+    }
+    scriptPolicy = resolvedSurface.scriptPolicy;
+    surfacePlan = resolvedSurface.surfacePlan;
   }
-  scriptPolicy = resolvedSurface.scriptPolicy;
-  const surfacePlan = resolvedSurface.surfacePlan;
 
   res.setHeader('Content-Type', 'text/plain; charset=utf-8');
   res.setHeader('Cache-Control', 'no-cache, no-transform');
@@ -666,10 +680,11 @@ app.post('/api/generate', async (req, res) => {
         ghostPrompt: ghostContext?.prompt ?? null,
         layout,
         edit,
-        capabilities: pack,
+        capabilities: hasSurfacePolicy ? capabilityCeiling : pack,
         components: componentPack,
-        scriptPolicy,
-        surfacePlan,
+        surfacePolicy: hasSurfacePolicy ? req.body.surfacePolicy : null,
+        scriptPolicy: hasSurfacePolicy ? undefined : scriptPolicy,
+        surfacePlan: hasSurfacePolicy ? null : surfacePlan,
         tokenOverrides: overrides.applied,
         activeTokensCss: ghostContext?.tokenSource.css ?? direction?.tokensCss ?? null,
         preludeLines,