@miller-tech/uap 2.21.3 → 2.36.4

package/dist/dashboard/server.js

@@ -12,10 +12,17 @@ import { readFileSync, existsSync } from 'fs';
 import { join, dirname, sep } from 'path';
 import { fileURLToPath } from 'url';
 import { getDashboardData, probeDatabaseHealth } from './data-service.js';
+import { getPlacementState, getPlacementPending, getPlacementPreview, getPlacementAdmit } from './placement-routes.js';
+import { resolvePendingPlacement, dismissPendingPlacement, loadPlacement, unloadPlacement } from '../placement/enforce.js';
+import { autoPolicyPath, loadAutoPolicy, MIN_UNLOAD_IDLE_SECS, saveAutoPolicy } from '../placement/auto.js';
+import { startIdleSweep } from '../placement/idle.js';
+import { resolveAttentionBySource, sweepExpired } from '../delivery/attention.js';
 import { seedDashboardData, cleanupSeeder } from './data-seeder.js';
 import { getPolicyMemoryManager } from '../policies/policy-memory.js';
 import { heuristicOrder, buildOrderPrompt, parseOrderResponse } from '../policies/policy-order.js';
 import { readEventsSince, readRecentEvents } from '../utils/telemetry-store.js';
+import { loadPolicy, runDoctor, worstHealth } from '../capacity/probe.js';
+import { getClientSummaries, ensureClientDashboard, stopClientDashboard } from './client-registry.js';
 /** First prose sentence of a policy's markdown (its description), fail-soft. */
 function policyPromptDescription(md) {
     if (!md)
@@ -147,6 +154,14 @@ export function startDashboardServer(options = {}) {
     // Updated to the real bound port once the server is listening.
     let boundPort = requestedPort;
     const host = options.host || 'localhost';
+    // Idle-resident sweep handle (started in the listen callback once cwd's
+    // seeder has run; see §4.4.2). Stopped in close().
+    let idleSweeper = null;
+    // P3 attention decider handle — rides the SAME fleet-ownership guard as
+    // the idle sweeper (UAP_IDLE_SWEEP=0 marks a fleet-spawned CLIENT
+    // dashboard: exactly one sweeper may touch shared state). Stopped in
+    // close().
+    let attentionSweeper = null;
     // Precedence: explicit option (--refresh) > UAP_DASH_REFRESH_MS > 2000.
     // Floor 250ms — getDashboardData reads several DBs per snapshot, so a
     // too-small interval would peg the event loop. Ceiling 1h — past 2^31-1ms,
@@ -156,6 +171,9 @@ export function startDashboardServer(options = {}) {
     // Track SSE clients for live event streaming
     const sseClients = new Set();
     const cwd = process.cwd();
+    // In-flight /api/doctor run (probes block the loop; concurrent requests
+    // coalesce onto one sweep instead of serializing N of them).
+    let doctorInFlight = null;
     // Mutation auth (security audit D1): the policy-mutation POST routes disable
     // security controls (delivery-enforcement, self-protect) and persist the
     // change to the DB. Without a gate, any LAN host (--host 0.0.0.0) or any web
@@ -230,7 +248,13 @@ export function startDashboardServer(options = {}) {
         if (!isTokenBearingPage) {
             res.setHeader('Access-Control-Allow-Origin', '*');
             res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-            res.setHeader('Access-Control-Allow-Headers', 'Content-Type, X-Uap-Dashboard-Token');
+            // The mutation-token header is deliberately NOT advertised in the
+            // preflight allow-list: the same-origin UI needs no CORS permission
+            // for it, and a wildcard `Access-Control-Allow-Headers` would let any
+            // origin's scripted preflight ride the token header name (security
+            // review — the mutation surface now includes process termination via
+            // /api/clients/stop). Reads stay open; mutations stay same-origin.
+            res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
         }
         if (req.method === 'OPTIONS') {
             res.writeHead(204);
@@ -257,6 +281,146 @@ export function startDashboardServer(options = {}) {
                 res.end(JSON.stringify(data));
                 return;
             }
+            // API: Fleet of client folders — registry + auto-scan, with per-client
+            // fail-soft summaries (deliver runs, queue depth, git, health probe).
+            // Read-only (no token): identical authority to /api/dashboard, one
+            // client at a time. Method-guarded so a future POST /api/clients
+            // mutation can't silently fall through to this read handler instead
+            // of the token-gated control chokepoint.
+            if (url === '/api/clients' && req.method === 'GET') {
+                try {
+                    const clients = await getClientSummaries(cwd, boundPort);
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ clients }));
+                }
+                catch (err) {
+                    res.writeHead(503, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: `client fleet unavailable: ${err.message}` }));
+                }
+                return;
+            }
+            // API: Model placement (spec §4.7) — READS ONLY in this phase; the
+            // load/unload/resolve mutation routes arrive with phase-3 enforcement
+            // and will go through mutationAuthorized(). `state` syncs the ledger
+            // (probes + unit reconcile) — heavier than the 2s dash refresh, so the
+            // tab throttles its own polling rather than riding the refresh tick.
+            if (url === '/api/placement/state') {
+                try {
+                    const data = getPlacementState(cwd);
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(data));
+                }
+                catch (err) {
+                    res.writeHead(503, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: `placement state unavailable: ${err.message}` }));
+                }
+                return;
+            }
+            if (url === '/api/placement/pending') {
+                const pending = getPlacementPending();
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ pending }));
+                return;
+            }
+            // API: Placement admission (spec §4.3) — the proxy gate's controller
+            // endpoint. POST, and LOOPBACK-ONLY rather than mutationToken-gated:
+            // the caller is the proxy (a local process that has no dashboard
+            // token), and its answer parks or forwards live model traffic, so it
+            // must never be reachable from off-host. Non-loopback callers get 403
+            // before the body is even read.
+            if (url === '/api/placement/admit' && req.method === 'POST') {
+                // Peer address captured from the live socket only: no '' fallback —
+                // a destroyed socket reports undefined and must FAIL CLOSED here,
+                // not coerce into the allowlist (this server is TCP-only, so an
+                // empty peer is never a unix socket).
+                const peer = req.socket.remoteAddress;
+                const loopback = peer === '127.0.0.1' || peer === '::1' || peer === '::ffff:127.0.0.1';
+                if (!loopback) {
+                    res.writeHead(403, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'placement admit is loopback-only' }));
+                    return;
+                }
+                const body = await readBody(req);
+                const parsed = parseJsonBody(body);
+                const modelId = typeof parsed.model_id === 'string' ? parsed.model_id : '';
+                if (!modelId) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'missing model_id' }));
+                    return;
+                }
+                const answer = getPlacementAdmit(cwd, {
+                    model_id: modelId,
+                    client: typeof parsed.client === 'string' ? parsed.client : undefined,
+                    session: typeof parsed.session === 'string' ? parsed.session : undefined,
+                    // The request's context need — spec §4.4 cost is per-request.
+                    // getPlacementAdmit sanitizes the shape, the route just forwards.
+                    cells: typeof parsed.cells === 'number' ? parsed.cells : undefined,
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(answer));
+                return;
+            }
+            if (url.startsWith('/api/placement/preview')) {
+                const urlObj = new URL(url, `http://${host}:${boundPort}`);
+                const model = urlObj.searchParams.get('model');
+                if (!model) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'missing ?model=<id>' }));
+                    return;
+                }
+                const cells = Number(urlObj.searchParams.get('cells'));
+                try {
+                    const preview = getPlacementPreview(cwd, model, {
+                        cells: Number.isFinite(cells) && cells > 0 ? cells : undefined,
+                    });
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(preview));
+                }
+                catch (err) {
+                    res.writeHead(503, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: `placement preview unavailable: ${err.message}` }));
+                }
+                return;
+            }
+            // API: Capacity doctor (`uap doctor` as a read route). Same shape the
+            // CLI prints with --json (reportVersion pins it). On-demand: the
+            // Overview tab fetches it once per visit (plus a Refresh button) — the
+            // probes are execFileSync-bounded (5s cap each), so it must NOT ride
+            // the 2s snapshot tick. Concurrent requests COALESCE onto the in-flight
+            // run (the probes block the event loop; two tabs must not serialize
+            // two full probe sweeps). Fail-open shape: policy-load errors surface
+            // as an `error` field, never a 500 crash of the panel.
+            if (url === '/api/doctor') {
+                try {
+                    if (!doctorInFlight) {
+                        doctorInFlight = (async () => {
+                            try {
+                                const loaded = loadPolicy(cwd);
+                                const services = runDoctor(loaded.policy);
+                                return {
+                                    reportVersion: 1,
+                                    policy: loaded.path,
+                                    worst: worstHealth(services),
+                                    services,
+                                };
+                            }
+                            catch (err) {
+                                return { reportVersion: 1, error: err.message };
+                            }
+                            finally {
+                                doctorInFlight = null;
+                            }
+                        })();
+                    }
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(await doctorInFlight));
+                }
+                catch (err) {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ reportVersion: 1, error: err.message }));
+                }
+                return;
+            }
             // API: SSE event stream
             if (url === '/api/events') {
                 res.writeHead(200, {
@@ -579,10 +743,54 @@ export function startDashboardServer(options = {}) {
             return false;
         }
     };
+    // Bind failure is the ONE error every deployment hits eventually (two
+    // projects, one 3847). Without this handler the process dies with a raw
+    // EADDRINUSE stack and a Restart=on-failure unit crash-loops against a
+    // port squatter. With it: say WHO owns the port (the fix depends on it —
+    // another UAP dashboard is a deliberate operator state, anything else is
+    // a genuine failure) and exit with a status systemd can act on.
+    // Attached to BOTH the http server AND the WebSocketServer: when ws wraps
+    // an existing server, the bind error surfaces on the WebSocketServer
+    // instance ('Emitted error event on WebSocketServer instance' — verified
+    // live), so an http-only handler never fires.
+    const onBindError = (err) => {
+        const die = (message, code) => {
+            console.error(message);
+            process.exit(code);
+        };
+        if (err.code !== 'EADDRINUSE') {
+            die(`UAP Dashboard: server error: ${err.message} — exiting`, 1);
+            return;
+        }
+        const probeUrl = `http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${requestedPort}/api/health`;
+        fetch(probeUrl, { signal: AbortSignal.timeout(1500) })
+            .then(async (r) => (r.ok ? (await r.json()) : null))
+            .then((body) => {
+            if (body?.service === 'uap-dashboard') {
+                // Exit 0 on purpose: the port's owner is a functioning UAP
+                // dashboard, so restarting cannot help — the operator must decide
+                // which project owns the port. A on-failure unit must NOT loop.
+                die(`UAP Dashboard: port ${requestedPort} is already owned by another UAP dashboard` +
+                    ` (root: ${body.root ?? 'unknown'} — it serves THAT project's data, not this one: ${cwd}).`, 0);
+                return;
+            }
+            die(`UAP Dashboard: port ${requestedPort} is busy (not a UAP dashboard) — ` +
+                `free it or run with --port <n>. (${err.message})`, 1);
+        })
+            .catch(() => {
+            die(`UAP Dashboard: port ${requestedPort} is busy and did not answer a health probe — ` +
+                `free it or run with --port <n>. (${err.message})`, 1);
+        });
+    };
+    server.on('error', onBindError);
     const wss = new WebSocketServer({
         server,
         verifyClient: ({ origin }) => originAllowed(origin),
     });
+    // Bind errors surface HERE too (ws re-emits them on the WebSocketServer
+    // instance when it wraps the http server) — without this, a port conflict
+    // crashes with a raw stack instead of the owner report + exit contract.
+    wss.on('error', onBindError);
     const pushInterval = setInterval(async () => {
         if (wss.clients.size === 0 && sseClients.size === 0)
             return;
@@ -677,6 +885,36 @@ export function startDashboardServer(options = {}) {
         catch {
             /* seeder failure is non-fatal */
         }
+        // Idle-resident sweep (§4.4.2): this process already owns placement
+        // enforcement, so it owns the reverse too — unloading residents whose
+        // idle clock ran out. OFF unless the policy armed it (per-tick re-read:
+        // operator edits take effect without a restart). Fleet-spawned CLIENT
+        // dashboards set UAP_IDLE_SWEEP=0 so exactly one sweeper touches the
+        // shared ledger.
+        if (!['0', 'false', 'off'].includes((process.env.UAP_IDLE_SWEEP ?? '').toLowerCase())) {
+            idleSweeper = startIdleSweep(cwd, {
+                log: (m) => console.warn(m),
+            });
+            // P3: during a long unattended run — the exact AFK case this rail
+            // exists for — session starts are rare, and without a periodic
+            // sweep the decider would never fire between them while retry
+            // minted asks accumulate. 60s cadence: pending TTL is 120s and
+            // deadlines are pinned, so adoption lands within a minute of the
+            // real expiry. sweepExpired is fail-open and no-ops under
+            // UAP_ATTENTION_OFF.
+            attentionSweeper = setInterval(() => {
+                try {
+                    const r = sweepExpired(cwd);
+                    if (r.adopted + r.escalated > 0) {
+                        console.warn(`[attention] sweep: ${r.adopted} auto-decided, ${r.escalated} escalated`);
+                    }
+                }
+                catch {
+                    /* the timer must never kill the dashboard */
+                }
+            }, 60_000);
+            attentionSweeper.unref();
+        }
         // Signal readiness with the actually-bound port (essential for port: 0).
         options.onListening?.({ port: boundPort, host });
     });
@@ -688,6 +926,16 @@ export function startDashboardServer(options = {}) {
         close: () => {
             clearInterval(eventPoller);
             clearInterval(pushInterval);
+            // Stop the idle-resident sweep before the rest of the teardown —
+            // a tick firing mid-close would race the server/ledger shutdown.
+            if (idleSweeper) {
+                idleSweeper.stop();
+                idleSweeper = null;
+            }
+            if (attentionSweeper) {
+                clearInterval(attentionSweeper);
+                attentionSweeper = null;
+            }
             // Cleanup seeder (clear heartbeat, mark agent completed)
             try {
                 cleanupSeeder(cwd);
@@ -733,7 +981,7 @@ function parseJsonBody(body) {
         throw new Error('Invalid JSON in request body');
     }
 }
-const CONTROL_PREFIXES = ['/api/tasks', '/api/ledger', '/api/orchestrator', '/api/agents', '/api/deliver'];
+const CONTROL_PREFIXES = ['/api/tasks', '/api/ledger', '/api/orchestrator', '/api/agents', '/api/deliver', '/api/placement', '/api/clients'];
 async function routeControl(url, cwd, body) {
     const seg = url.split('/').filter(Boolean); // ['api','tasks','<id>','update']
     const dec = (s) => decodeURIComponent(s);
@@ -768,6 +1016,164 @@ async function routeControl(url, cwd, body) {
         return handleDeliverCancel(cwd, dec(seg[2]));
     if (seg[1] === 'deliver' && seg.length === 4 && seg[3] === 'resume')
         return handleDeliverResume(cwd, dec(seg[2]));
+    // Placement mutations (spec §4.7): token-gated like every control route.
+    // The result object is returned whole (200) even on ok:false — the steps
+    // and rollback detail are the operator's evidence, not an error string.
+    if (url === '/api/placement/resolve')
+        return handlePlacementResolve(cwd, body);
+    if (url === '/api/placement/dismiss')
+        return handlePlacementDismiss(cwd, body);
+    if (url === '/api/placement/load')
+        return handlePlacementLoad(cwd, body);
+    if (url === '/api/placement/unload')
+        return handlePlacementUnload(cwd, body);
+    if (url === '/api/placement/auto')
+        return handlePlacementAuto(body);
+    // Fleet spawn-on-demand (Option B link-out): bring up the selected client's
+    // OWN dashboard server — full control stays on that instance, token-gated
+    // and loopback-bound exactly like this one. Registry-only: the path is
+    // resolved against listClients() inside, never trusted from the wire.
+    if (url === '/api/clients/serve')
+        return handleClientsServe(cwd, body);
+    // Fleet teardown: stops the client's own dashboard instance (pid recorded
+    // at spawn, ownership-verified before SIGTERM — see stopClientDashboard).
+    if (url === '/api/clients/stop')
+        return handleClientsStop(cwd, body);
     return undefined;
 }
+async function handleClientsServe(cwd, body) {
+    const clientPath = typeof body.path === 'string' ? body.path : '';
+    if (!clientPath)
+        throw new Error('path is required');
+    return ensureClientDashboard(cwd, clientPath);
+}
+async function handleClientsStop(cwd, body) {
+    const clientPath = typeof body.path === 'string' ? body.path : '';
+    if (!clientPath)
+        throw new Error('path is required');
+    return stopClientDashboard(cwd, clientPath);
+}
+async function handlePlacementResolve(cwd, body) {
+    const placementId = typeof body.placement_id === 'string' ? body.placement_id : '';
+    const option = Number(body.option);
+    if (!placementId)
+        throw new Error('placement_id is required');
+    if (!Number.isInteger(option) || option < 1)
+        throw new Error('option must be a 1-based index (as `uap models pending` prints them)');
+    // Approval signature (spec §4.5): the dashboard UI sends the victim list
+    // the operator actually SAW in the preview; enforcement refuses if the
+    // recomputed option's victims differ.
+    const expectedVictims = Array.isArray(body.expected_victims)
+        ? body.expected_victims
+            .filter((v) => typeof v === 'object' && v !== null &&
+            typeof v.model === 'string' &&
+            typeof v.config === 'string')
+            .map((v) => ({ model: v.model, config: v.config }))
+        : undefined;
+    const result = await resolvePendingPlacement(cwd, placementId, option, expectedVictims ? { expectedVictims } : {});
+    // P3: the operator answered through the PLACEMENT surface, not the queue —
+    // close the attention ask by origin or a later sweep would record a false
+    // AFK adoption over a decision that was actually made. Best-effort: no
+    // open ask for this placement resolves nothing (idempotent).
+    if (result.ok) {
+        resolveAttentionBySource(cwd, `placement:${placementId}`, `operator applied option ${option} via the dashboard`);
+    }
+    return result;
+}
+function handlePlacementDismiss(cwd, body) {
+    const placementId = typeof body.placement_id === 'string' ? body.placement_id : '';
+    if (!placementId)
+        throw new Error('placement_id is required');
+    const { dismissed } = dismissPendingPlacement(placementId);
+    if (dismissed) {
+        resolveAttentionBySource(cwd, `placement:${placementId}`, 'operator dismissed the parked request via the dashboard');
+    }
+    return { dismissed };
+}
+async function handlePlacementLoad(cwd, body) {
+    const model = typeof body.model === 'string' ? body.model : '';
+    if (!model)
+        throw new Error('model is required');
+    return loadPlacement(cwd, model);
+}
+async function handlePlacementUnload(cwd, body) {
+    const model = typeof body.model === 'string' ? body.model : '';
+    if (!model)
+        throw new Error('model is required');
+    return unloadPlacement(cwd, model);
+}
+/** Phase-4 auto policy (§4.4.1) — the UI twin of `uap models auto`: status
+ * read with no fields, enable/disable, and the displacement allowlist whose
+ * additions require the same explicit `yes` consent the CLI's --yes demands
+ * (what is being recorded is standing consent to evict unattended).
+ * NO policy_path from the body (security review S1): an HTTP caller must not
+ * redirect the policy write at an arbitrary filesystem path — the route always
+ * writes the single authority (`autoPolicyPath()`, env-overridable for tests
+ * via UAP_PLACEMENT_AUTO exactly like the CLI). */
+function handlePlacementAuto(body) {
+    const stringList = (v) => Array.isArray(v) ? v.filter((m) => typeof m === 'string' && m.length > 0) : [];
+    const enable = body.enable === true;
+    const disable = body.disable === true;
+    const allow = stringList(body.allow_displace);
+    const disallow = stringList(body.disallow_displace);
+    if (enable && disable)
+        throw new Error('enable and disable are mutually exclusive');
+    const path = autoPolicyPath();
+    const allowUnload = stringList(body.allow_unload);
+    const disallowUnload = stringList(body.disallow_unload);
+    const idleSecs = body.unload_idle_after_secs;
+    // `null` explicitly disarms the timer; a number arms/updates it. Anything
+    // else in that field is a caller error, not a silent no-op.
+    if (idleSecs !== undefined && idleSecs !== null && typeof idleSecs !== 'number') {
+        throw new Error('unload_idle_after_secs must be a number of seconds, or null to disarm');
+    }
+    if (!enable && !disable && allow.length === 0 && disallow.length === 0 &&
+        allowUnload.length === 0 && disallowUnload.length === 0 && idleSecs === undefined) {
+        return loadAutoPolicy(path); // status: same shape the state payload serves
+    }
+    if (allow.length > 0 && body.yes !== true) {
+        throw new Error('allow_displace records standing consent to UNLOAD the current resident(s) and load the requested ' +
+            'model without an operator prompt — confirm with yes: true (the same gate as ' +
+            '`uap models auto --allow-displace <model> --yes`)');
+    }
+    if (allowUnload.length > 0 && body.yes !== true) {
+        throw new Error('allow_unload records standing consent to STOP this model\'s resident automatically once it ' +
+            'goes idle — confirm with yes: true (the same gate as ' +
+            '`uap models auto --allow-unload <model> --yes`)');
+    }
+    const prev = loadAutoPolicy(path);
+    // Spread prev (NOT a literal rebuild): every field the route doesn't
+    // know about must survive a save. The allowlists are cloned to fresh
+    // arrays so the in-place filtering below never mutates `prev`.
+    const allowDisplace = [...prev.allow_displace];
+    const unloadAllow = [...(prev.unload_allow ?? [])];
+    const touchesUnload = allowUnload.length > 0 || disallowUnload.length > 0 || prev.unload_allow !== undefined;
+    // Old-shape policies keep their old-shape responses: unload_allow is only
+    // (re)written when the caller touches it or it already exists on disk.
+    const next = { ...prev, allow_displace: allowDisplace };
+    if (enable)
+        next.enabled = true;
+    if (disable)
+        next.enabled = false;
+    for (const m of allow)
+        if (!allowDisplace.includes(m))
+            allowDisplace.push(m);
+    next.allow_displace = allowDisplace.filter((m) => !disallow.includes(m));
+    if (touchesUnload) {
+        for (const m of allowUnload)
+            if (!unloadAllow.includes(m))
+                unloadAllow.push(m);
+        next.unload_allow = unloadAllow.filter((m) => !disallowUnload.includes(m));
+    }
+    if (idleSecs === null)
+        delete next.unload_idle_after_secs;
+    else if (idleSecs !== undefined) {
+        if (!Number.isFinite(idleSecs) || idleSecs < MIN_UNLOAD_IDLE_SECS) {
+            throw new Error(`unload_idle_after_secs must be >= ${MIN_UNLOAD_IDLE_SECS} (under a minute the sweep would thrash)`);
+        }
+        next.unload_idle_after_secs = Math.floor(idleSecs);
+    }
+    saveAutoPolicy(next, path);
+    return next;
+}
 //# sourceMappingURL=server.js.map