headscale: describe an acl change in english, read the diff, then save

The policy editor now opens read-only behind an Edit button, and edit mode brings up an assistant:
describe the change, get a complete revised document back, read a line diff of it, and only then press
Save. Nobody writes an ACL from memory — it is HuJSON in Tailscale's grammar keyed to names only the
server knows — and that, not typing speed, is what made this screen unusable.

The model never touches Headscale. It proposes text, the text lands in the editor's draft, and the
existing Save button is still the only thing that leaves the browser. A model that could write the ACL
directly is one that can partition the network the owner is connected through.

The sidecar calls officer-anthropic-proxy on loopback for one request with a timeout — no session, no
agent, nothing persisted. It sends the draft on screen plus the tailnet's vocabulary (user, node and tag
names) and no credentials of any kind. It does not validate the reply either: Headscale owns the only
parser that counts, same argument as policy.ts.

src/workspaces/officerdev/src/apps/Headscale/PolicyAssistant.tsx

@@ -0,0 +1,177 @@
+import { useMemo, useState } from 'react';
+import { Check, Loader2, Sparkles, Wand2, X } from 'lucide-react';
+import { useHeadscalePolicyAssist, assistFailure } from './useHeadscalePolicy';
+import { collapseUnchanged, diffCounts, diffLines } from './diff';
+import { Button, Card, ErrorNote } from './Cards';
+
+// Ask for a policy change in English; read the diff; decide.
+//
+// The whole point of this panel is the middle step. The model is good at the grammar — HuJSON, tagOwners,
+// the src/dst shapes — and has no idea which of the owner's machines matter, so its proposal is a draft to
+// be read, not an answer to be trusted. Nothing here writes to Headscale: Apply puts the text in the editor
+// above and the existing Save button is still the only thing that leaves the browser.
+//
+// The diff is against what is CURRENTLY in the editor, which is also what was sent up, so it always shows
+// exactly what accepting would change on screen — including edits the owner made and hasn't saved.
+
+const EXAMPLES = [
+  'let everyone reach the machines tagged tag:server on port 22',
+  'stop the phones from reaching anything except the DNS server',
+  'add a group for family with just my own user in it',
+];
+
+const DiffBody = ({ before, after }: { before: string; after: string }) => {
+  const lines = useMemo(() => diffLines(before, after), [before, after]);
+  const rows = useMemo(() => collapseUnchanged(lines), [lines]);
+  const { added, removed } = useMemo(() => diffCounts(lines), [lines]);
+
+  if (!added && !removed) {
+    return <p className="px-3 py-2.5 text-[11px] text-zinc-500">No change — the proposal matches what you have.</p>;
+  }
+
+  return (
+    <>
+      <div className="flex items-center gap-3 border-b border-white/10 px-3 py-1.5 text-[11px]">
+        <span className="text-emerald-400">+{added}</span>
+        <span className="text-red-400">−{removed}</span>
+        <span className="text-zinc-600">unchanged lines collapsed</span>
+      </div>
+      <div className="max-h-72 overflow-auto p-1 font-mono text-[11px] leading-relaxed">
+        {rows.map((row, index) =>
+          row === null ? (
+            <div key={index} className="px-2 py-1 text-center text-zinc-700 select-none">
+              ⋯
+            </div>
+          ) : (
+            <div
+              key={index}
+              className={`px-2 whitespace-pre-wrap ${
+                row.kind === 'add'
+                  ? 'bg-emerald-500/10 text-emerald-300'
+                  : row.kind === 'remove'
+                    ? 'bg-red-500/10 text-red-300'
+                    : 'text-zinc-500'
+              }`}
+            >
+              {row.kind === 'add' ? '+' : row.kind === 'remove' ? '−' : ' '} {row.text}
+            </div>
+          ),
+        )}
+      </div>
+    </>
+  );
+};
+
+type PolicyAssistantProps = {
+  /** The text on screen right now. Sent up as the base, and diffed against. */
+  policy: string;
+  /** Accepting a proposal — puts it in the editor's draft. Never saves. */
+  onApply: (policy: string) => void;
+  disabled?: boolean;
+};
+
+export const PolicyAssistant = ({ policy, onApply, disabled }: PolicyAssistantProps) => {
+  const assist = useHeadscalePolicyAssist();
+  const [prompt, setPrompt] = useState('');
+  // The proposal lives here, not in the mutation's `data`, so that discarding it is a real state change and
+  // a second ask doesn't briefly show the previous answer against the new base.
+  const [proposal, setProposal] = useState<{ explanation: string; policy: string } | null>(null);
+
+  const ask = async () => {
+    const request = prompt.trim();
+    if (!request || assist.isPending) return;
+    setProposal(null);
+    try {
+      setProposal(await assist.mutateAsync({ prompt: request, policy }));
+    } catch {
+      // Rendered from `assist.error` below — mutateAsync rejecting is the same failure twice.
+    }
+  };
+
+  const apply = () => {
+    if (!proposal) return;
+    onApply(proposal.policy);
+    setProposal(null);
+    setPrompt('');
+    assist.reset();
+  };
+
+  return (
+    <Card>
+      <div className="flex items-center gap-2 border-b border-white/10 px-3 py-2">
+        <Sparkles className="h-3.5 w-3.5 text-primary" />
+        <span className="text-xs font-medium text-zinc-200">Describe the change</span>
+        <span className="ml-auto text-[11px] text-zinc-600">Proposes a document — never saves it</span>
+      </div>
+
+      <div className="flex flex-col gap-2 p-3">
+        <textarea
+          value={prompt}
+          onChange={(ev) => setPrompt(ev.target.value)}
+          onKeyDown={(ev) => {
+            // Enter sends: this is a one-line instruction far more often than a paragraph, and shift-enter
+            // is still there for the times it isn't.
+            if (ev.key === 'Enter' && !ev.shiftKey) {
+              ev.preventDefault();
+              void ask();
+            }
+          }}
+          rows={2}
+          spellCheck={false}
+          disabled={disabled}
+          placeholder="e.g. give my laptop SSH access to everything tagged tag:server"
+          className="w-full resize-y rounded-lg border border-white/10 bg-black/40 px-3 py-2 text-sm leading-relaxed text-zinc-100 outline-none transition-colors placeholder:text-zinc-600 focus:border-primary/50 disabled:opacity-50"
+        />
+
+        <div className="flex flex-wrap items-center gap-2">
+          {!prompt.trim() &&
+            EXAMPLES.map((example) => (
+              <button
+                key={example}
+                type="button"
+                onClick={() => setPrompt(example)}
+                disabled={disabled}
+                className="cursor-pointer rounded-full border border-white/10 px-2.5 py-1 text-[11px] text-zinc-500 transition-colors hover:border-white/20 hover:text-zinc-300 disabled:opacity-40"
+              >
+                {example}
+              </button>
+            ))}
+          <div className="ml-auto">
+            <Button variant="primary" onClick={() => void ask()} disabled={!prompt.trim() || assist.isPending}>
+              {assist.isPending ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : <Wand2 className="h-3.5 w-3.5" />}
+              {assist.isPending ? 'Drafting…' : 'Ask'}
+            </Button>
+          </div>
+        </div>
+
+        {assist.error && <ErrorNote>{assistFailure(assist.error)}</ErrorNote>}
+      </div>
+
+      {proposal && (
+        <div className="border-t border-white/10">
+          {proposal.explanation && (
+            <p className="px-3 py-2.5 text-xs leading-relaxed whitespace-pre-wrap text-zinc-300">
+              {proposal.explanation}
+            </p>
+          )}
+          <div className="border-t border-white/10">
+            <DiffBody before={policy} after={proposal.policy} />
+          </div>
+          <div className="flex items-center gap-2 border-t border-white/10 px-3 py-2">
+            <span className="text-[11px] text-zinc-600">Applying only fills the editor — you still press Save.</span>
+            <span className="ml-auto flex items-center gap-2">
+              <Button onClick={() => setProposal(null)}>
+                <X className="h-3.5 w-3.5" />
+                Discard
+              </Button>
+              <Button variant="primary" onClick={apply}>
+                <Check className="h-3.5 w-3.5" />
+                Apply to editor
+              </Button>
+            </span>
+          </div>
+        </div>
+      )}
+    </Card>
+  );
+};

src/workspaces/officerdev/src/apps/Headscale/PolicyView.tsx

@@ -1,7 +1,8 @@
 import { useEffect, useRef, useState } from 'react';
-import { AlertTriangle, FileLock2, Loader2, RotateCcw, Save, ShieldCheck } from 'lucide-react';
+import { AlertTriangle, FileLock2, Loader2, Pencil, RotateCcw, Save, ShieldCheck } from 'lucide-react';
 import { timeAgo } from './format';
 import { useHeadscalePolicy, policySaveFailure, type PolicySaveFailure } from './useHeadscalePolicy';
+import { PolicyAssistant } from './PolicyAssistant';
 import { Card, SectionHeader, Button, ErrorNote } from './Cards';
 import { ViewShell } from './ViewShell';
 
@@ -9,6 +10,11 @@ import { ViewShell } from './ViewShell';
 // hand-kept alignment are half the document's value to whoever maintains it, and a rich editor that
 // reformats or a client-side parser that disagrees with Headscale would both destroy more than they add.
 //
+// It opens READ-ONLY behind an Edit button. This is the document that decides which machine can reach
+// which, it is usually being looked at rather than changed, and a textarea focused by a stray click is a
+// way to alter it without meaning to. Edit mode also brings up the assistant, because "I do not know what
+// this file should look like" is the actual reason this screen was hard to use.
+//
 // Validation is entirely Headscale's. It has the only parser that counts: it resolves groups, tags and
 // host aliases, and it is what will actually enforce the result. Officer sends the text up untouched and
 // shows the verdict verbatim — including the line and column, which is the whole reason to show it at all.
@@ -68,6 +74,7 @@ export const PolicyView = () => {
   const { policy, isLoading, error, save } = useHeadscalePolicy();
 
   const [draft, setDraft] = useState<string | null>(null);
+  const [editing, setEditing] = useState(false);
   const [failure, setFailure] = useState<PolicySaveFailure | null>(null);
   // Sticky for the session: once a server has refused a write, every later save would refuse identically,
   // and re-discovering that by pressing save again is not information.
@@ -86,6 +93,8 @@ export const PolicyView = () => {
       await save.mutateAsync(text);
       setDraft(null);
       setSavedAt(Date.now());
+      // A clean save is the end of the edit, not the start of the next one — back to reading.
+      setEditing(false);
     } catch (err) {
       const parsed = policySaveFailure(err);
       setFailure(parsed);
@@ -93,13 +102,19 @@ export const PolicyView = () => {
     }
   };
 
-  useSaveShortcut(() => void submit(), dirty && !readOnly);
+  useSaveShortcut(() => void submit(), editing && dirty && !readOnly);
 
   const revert = () => {
     setDraft(null);
     setFailure(null);
   };
 
+  /** Leaving edit mode throws the draft away — there is nowhere else for unsaved text to go. */
+  const stopEditing = () => {
+    revert();
+    setEditing(false);
+  };
+
   return (
     <ViewShell isLoading={isLoading} error={error} label="the access policy">
       <div className="mx-auto flex max-w-4xl flex-col gap-3">
@@ -107,18 +122,31 @@ export const PolicyView = () => {
           title="Access policy"
           subtitle="HuJSON — JSON with comments and trailing commas. Headscale validates it on save; nothing is stored unless it passes."
           action={
-            <div className="flex items-center gap-2">
-              {dirty && !readOnly && (
-                <Button onClick={revert} disabled={save.isPending}>
+            editing ? (
+              <div className="flex items-center gap-2">
+                <Button onClick={stopEditing} disabled={save.isPending}>
                   <RotateCcw className="h-3.5 w-3.5" />
-                  Revert
+                  {dirty ? 'Discard' : 'Done'}
                 </Button>
-              )}
-              <Button variant="primary" onClick={() => void submit()} disabled={!dirty || !!readOnly || save.isPending}>
-                {save.isPending ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : <Save className="h-3.5 w-3.5" />}
-                {save.isPending ? 'Validating…' : 'Save'}
+                <Button
+                  variant="primary"
+                  onClick={() => void submit()}
+                  disabled={!dirty || !!readOnly || save.isPending}
+                >
+                  {save.isPending ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : <Save className="h-3.5 w-3.5" />}
+                  {save.isPending ? 'Validating…' : 'Save'}
+                </Button>
+              </div>
+            ) : (
+              <Button
+                onClick={() => setEditing(true)}
+                disabled={!!readOnly}
+                title={readOnly ? 'This server will not accept written policies' : undefined}
+              >
+                <Pencil className="h-3.5 w-3.5" />
+                Edit
               </Button>
-            </div>
+            )
           }
         />
 
@@ -126,6 +154,18 @@ export const PolicyView = () => {
         {failure?.kind === 'rejected' && <Rejected message={failure.message} />}
         {failure?.kind === 'unknown' && <ErrorNote>{failure.message}</ErrorNote>}
 
+        {editing && (
+          <PolicyAssistant
+            policy={text}
+            onApply={(proposed) => {
+              setDraft(proposed);
+              setFailure(null);
+              setSavedAt(null);
+            }}
+            disabled={save.isPending}
+          />
+        )}
+
         <Card>
           <textarea
             value={text}
@@ -136,8 +176,11 @@ export const PolicyView = () => {
             }}
             spellCheck={false}
             autoComplete="off"
+            readOnly={!editing}
             placeholder={'{\n  "acls": [\n    { "action": "accept", "src": ["*"], "dst": ["*:*"] },\n  ],\n}'}
-            className="block h-[28rem] w-full resize-y bg-black/40 p-4 font-mono text-[12px] leading-relaxed text-zinc-200 outline-none placeholder:text-zinc-700"
+            className={`block h-[28rem] w-full resize-y p-4 font-mono text-[12px] leading-relaxed outline-none placeholder:text-zinc-700 ${
+              editing ? 'bg-black/40 text-zinc-200' : 'bg-black/20 text-zinc-400'
+            }`}
           />
           <div className="flex flex-wrap items-center gap-3 border-t border-white/10 px-3 py-2 text-[11px] text-zinc-500">
             <span>
@@ -158,7 +201,8 @@ export const PolicyView = () => {
 
         <p className="px-1 text-[11px] leading-relaxed text-zinc-600">
           This document decides which node may reach which. A policy that saves cleanly can still cut a machine off —
-          Headscale checks that the document is valid, not that it is what you meant. Ctrl/Cmd-S saves.
+          Headscale checks that the document is valid, not that it is what you meant.
+          {editing ? ' Ctrl/Cmd-S saves.' : ' Press Edit to change it.'}
         </p>
       </div>
     </ViewShell>

src/workspaces/officerdev/src/apps/Headscale/diff.ts

@@ -0,0 +1,77 @@
+// A line diff, for showing what a proposed policy actually changes before anyone saves it.
+//
+// Hand-rolled rather than a dependency: this is one screen showing one document, the inputs are a few
+// hundred lines at most, and the alternative is adding a package to the frozen lockfile for forty lines of
+// well-understood algorithm. If a second surface ever needs a diff, that trade flips.
+
+export type DiffLine = { kind: 'same' | 'add' | 'remove'; text: string };
+
+/** Longest common subsequence table over the two line arrays. O(n·m) — fine at document scale. */
+function lcsLengths(a: string[], b: string[]): number[][] {
+  const table: number[][] = Array.from({ length: a.length + 1 }, () => new Array<number>(b.length + 1).fill(0));
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      table[i]![j] = a[i] === b[j] ? table[i + 1]![j + 1]! + 1 : Math.max(table[i + 1]![j]!, table[i]![j + 1]!);
+    }
+  }
+  return table;
+}
+
+/** Every line of both documents, in order, tagged with what happened to it. */
+export function diffLines(before: string, after: string): DiffLine[] {
+  const a = before.split('\n');
+  const b = after.split('\n');
+  const table = lcsLengths(a, b);
+
+  const out: DiffLine[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      out.push({ kind: 'same', text: a[i]! });
+      i++;
+      j++;
+    } else if (table[i + 1]![j]! >= table[i]![j + 1]!) {
+      out.push({ kind: 'remove', text: a[i]! });
+      i++;
+    } else {
+      out.push({ kind: 'add', text: b[j]! });
+      j++;
+    }
+  }
+  while (i < a.length) out.push({ kind: 'remove', text: a[i++]! });
+  while (j < b.length) out.push({ kind: 'add', text: b[j++]! });
+  return out;
+}
+
+/**
+ * Drop long runs of unchanged lines, keeping `context` either side of every change.
+ *
+ * A policy is mostly unchanged by any one edit, and an unabridged diff buries the three lines that matter.
+ * `null` marks each elision so the view can draw a gap rather than pretend the lines are adjacent.
+ */
+export function collapseUnchanged(lines: DiffLine[], context = 3): (DiffLine | null)[] {
+  const keep = new Array<boolean>(lines.length).fill(false);
+  lines.forEach((line, index) => {
+    if (line.kind === 'same') return;
+    for (let k = Math.max(0, index - context); k <= Math.min(lines.length - 1, index + context); k++) keep[k] = true;
+  });
+
+  const out: (DiffLine | null)[] = [];
+  let gap = false;
+  lines.forEach((line, index) => {
+    if (keep[index]) {
+      out.push(line);
+      gap = false;
+    } else if (!gap) {
+      out.push(null);
+      gap = true;
+    }
+  });
+  return out;
+}
+
+export const diffCounts = (lines: DiffLine[]) => ({
+  added: lines.filter((l) => l.kind === 'add').length,
+  removed: lines.filter((l) => l.kind === 'remove').length,
+});

src/workspaces/officerdev/src/apps/Headscale/useHeadscalePolicy.ts

@@ -29,6 +29,32 @@ export function policySaveFailure(err: unknown): PolicySaveFailure {
   }
 }
 
+/** What the assistant proposes. Never saved by the hook — PolicyView puts it in the draft. */
+export type PolicyProposal = { explanation: string; policy: string };
+
+/** The assistant's failures are all one sentence to the owner; only the sidecar's `error` field is useful. */
+export function assistFailure(err: unknown): string {
+  const raw = (err as { message?: unknown } | null)?.message;
+  if (typeof raw !== 'string' || !raw) return 'The assistant could not be reached';
+  try {
+    const parsed = JSON.parse(raw) as { error?: unknown };
+    return typeof parsed.error === 'string' && parsed.error ? parsed.error : 'The assistant could not be reached';
+  } catch {
+    return raw.slice(0, 300);
+  }
+}
+
+/**
+ * Ask for a revised policy in English. Separate from `useHeadscalePolicy` because it is a different kind of
+ * thing: no cache, no query key, nothing to invalidate — one request, one answer, discarded on reload.
+ */
+export function useHeadscalePolicyAssist() {
+  const { post } = useClient();
+  return useMutation({
+    mutationFn: (input: { prompt: string; policy: string }) => post<PolicyProposal>(`${PATH}/assist`, input),
+  });
+}
+
 export function useHeadscalePolicy() {
   const { get, put } = useClient();
   const qc = useQueryClient();