@pleri/olam-cli 0.1.169 → 0.1.170

package/host-cp/src/server.mjs

@@ -34,7 +34,15 @@ import { computeProgress } from './world-progress.mjs';
 import { createPrCache } from './pr-cache.mjs';
 import { fetchContainerSecret } from './container-secret-fetcher.mjs';
 import { subscribeDockerEvents } from './docker-events.mjs';
+import {
+  recordWorldLifecycle,
+  emptyEvidence,
+  WorldLifecyclePhase,
+  WorldStartupFailureKind,
+} from '../lifecycle/index.mjs';
 import { createHostStream, newStreamId } from './host-stream.mjs';
+import { createNdjsonSpanSink } from '../observability/ndjson-span-sink.mjs';
+import { attemptRecovery, findScenarioForKind } from '../recovery/index.mjs';
 import { detectHaltChunk } from './halt-detect.mjs';
 import { spawnUpgraderContainer } from './upgrade-spawner.mjs';
 import { parseProxyPath, perWorldBase, proxyToWorld } from './proxy.mjs';
@@ -74,6 +82,7 @@ import {
   handleServerBridges,
 } from './routes/process-port.mjs';
 import { instrumentHandler, renderMetrics } from './metrics.mjs';
+import { handleDispatchFromEmail } from './lib/email-dispatch.mjs';
 
 // ── Deployment-mode detection ─────────────────────────────────────
 //
@@ -142,6 +151,20 @@ const OLAM_REPO_HOST_PATH = process.env.OLAM_REPO_HOST_PATH ?? '';
 const OLAM_GH_CONFIG_HOST_PATH = process.env.OLAM_GH_CONFIG_HOST_PATH ?? '';
 const OLAM_UPGRADER_IMAGE = process.env.OLAM_UPGRADER_IMAGE ?? 'ghcr.io/pleri/olam-host-cp:latest';
 const WORKSPACES_DIR = process.env.OLAM_WORKSPACES_DIR ?? '/data/workspaces';
+// Email-trigger surface (PR feat/email-as-world-trigger). The signing
+// secret is the operator-shared key with the CF Email Worker — see
+// docs/architecture/email-as-trigger.md. The allowlist is enforced
+// defense-in-depth: the worker rejects at SMTP-time so bounces reach
+// senders; we re-check at HTTP-time so a misrouted direct POST cannot
+// bypass it. Both empty → endpoint stays mis-configured and returns
+// 500/403 (fail-closed).
+const OLAM_EMAIL_SIGNING_SECRET = process.env.OLAM_EMAIL_SIGNING_SECRET ?? '';
+const OLAM_EMAIL_ALLOWED_SENDERS = process.env.OLAM_EMAIL_ALLOWED_SENDERS ?? '';
+const OLAM_EMAIL_ATTACHMENTS_ROOT =
+  process.env.OLAM_EMAIL_ATTACHMENTS_ROOT ??
+  (HOST_CP_MODE === 'container'
+    ? '/data/email-attachments'
+    : path.join(os.homedir(), '.olam', 'email-attachments'));
 const WORLD_NAMES_PATH =
   process.env.OLAM_WORLD_NAMES_PATH ??
   (HOST_CP_MODE === 'container'
@@ -458,6 +481,15 @@ const sseGate = new SseGate({ maxConcurrent: SSE_CAP });
 // poll-every-2s `useListeningServers` loop.
 const hostStream = createHostStream({ log: (m) => console.log(`[host-stream] ${m}`) });
 
+// Zero-config NDJSON span sink. Subscribes to host-stream `event: span`
+// broadcasts and appends to ~/.olam/logs/host.trace.ndjson (override via
+// OLAM_TRACE_LOG_PATH). Fail-open: a sink-bootstrap error logs a warning
+// and proceeds without tracing rather than blocking host-cp boot.
+const ndjsonSpanSink = await createNdjsonSpanSink({ hostStream }).catch((err) => {
+  console.warn(`[trace] NDJSON span sink unavailable: ${err?.message ?? err}`);
+  return null;
+});
+
 // A4: coalesce docker-event bursts into a single servers.snapshot. World
 // boot fires `create` + `start` + healthcheck transitions in <100ms; we
 // don't want a broadcast storm. Window matches plan-source.md P3 target.
@@ -485,6 +517,93 @@ const stopEvents = subscribeDockerEvents({
     // this callback is by construction an olam world.
     scheduleServersSnapshot();
   },
+  // Killshot #2 — emit typed world.lifecycle events alongside the cache
+  // invalidate. Docker actions map onto phases as follows:
+  //   start | restart → Spawning   (container boot kicked off)
+  //   stop            → Finished   (clean operator-initiated stop)
+  //   die  | kill     → Failed     (involuntary exit; carries exit code +
+  //                                 classifier-derived failureKind)
+  // The lifecycle module's classifier runs against a synthetic evidence
+  // bundle so the trace records *why* the bucket was chosen. TrustRequired,
+  // ReadyForPrompt, and Running emissions are not observable from
+  // host-cp's docker-events surface — those transitions happen inside
+  // container-cp and are wired in a follow-up (see ADR 033 § Open
+  // questions for the planned container-cp → host-cp emission seam).
+  onWorldLifecycleEvent: ({ worldId, action, exitCode }) => {
+    const now = Date.now();
+    if (action === 'start' || action === 'restart') {
+      recordWorldLifecycle(hostStream, {
+        worldId,
+        phase: WorldLifecyclePhase.Spawning,
+        at: now,
+      });
+      return;
+    }
+    if (action === 'stop') {
+      recordWorldLifecycle(hostStream, {
+        worldId,
+        phase: WorldLifecyclePhase.Finished,
+        at: now,
+      });
+      return;
+    }
+    if (action === 'die' || action === 'kill') {
+      const ev = emptyEvidence(worldId, now);
+      ev.lastPhase = WorldLifecyclePhase.Running;
+      ev.lastPhaseAt = now;
+      if (exitCode !== undefined) ev.processExitCode = exitCode;
+      // For involuntary exit with a code we know the bucket up front;
+      // skip the classifier inference and pass it through explicitly so
+      // the trace records the exact docker-derived signal.
+      const failureKind =
+        exitCode !== undefined ? WorldStartupFailureKind.ProviderProcessGone : undefined;
+      const lifecycleEvent = recordWorldLifecycle(hostStream, {
+        worldId,
+        phase: WorldLifecyclePhase.Failed,
+        at: now,
+        evidence: ev,
+        failureKind,
+      });
+
+
+      // Killshot #3 — bounded auto-recovery. Attempt once per
+      // (worldId, failureKind) pair; the engine enforces idempotency.
+      // Emit recovery.* events on the host-stream so the NDJSON trace
+      // sink captures the full attempt trail.
+      const resolvedKind = lifecycleEvent.failureKind ?? null;
+      const scenario = findScenarioForKind(resolvedKind);
+      if (scenario !== undefined) {
+        hostStream.broadcast('recovery.attempt-started', {
+          worldId,
+          scenario: scenario?.name ?? 'unmatched',
+          recipe: scenario?.recipe ?? null,
+        });
+        attemptRecovery(worldId, ev, resolvedKind)
+          .then((entry) => {
+            if (entry.outcome === 'escalated') {
+              hostStream.broadcast('recovery.escalated', {
+                worldId,
+                ledgerEntry: entry,
+              });
+            } else if (entry.outcome === 'success') {
+              hostStream.broadcast('recovery.attempt-succeeded', {
+                worldId,
+                ledgerEntry: entry,
+              });
+            } else {
+              hostStream.broadcast('recovery.attempt-failed', {
+                worldId,
+                ledgerEntry: entry,
+              });
+            }
+          })
+          .catch((err) => {
+            // Recovery engine always resolves — this path is a safety net.
+            console.error(`[recovery] unexpected engine rejection for ${worldId}: ${err?.message}`);
+          });
+      }
+    }
+  },
 });
 
 // Initial servers.snapshot so subscribers connecting before any docker
@@ -2070,6 +2189,59 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
   //     B5's CLI uses).
   // When unset, returns 503 with a clear setup hint instead of failing
   // silently — operators wire when they're ready for cloud-mode dogfood.
+  // POST /v1/dispatch-from-email — see docs/architecture/email-as-trigger.md.
+  //
+  // The CF Email Worker (packages/email-worker-cloudflare) HMAC-signs the
+  // canonical payload (Decision 022) and POSTs it here. The host re-validates
+  // the signature, re-checks the sender allowlist (defense in depth), persists
+  // attachments under OLAM_EMAIL_ATTACHMENTS_ROOT/<worldId>/<timestampMs>/,
+  // and either routes the dispatch to a known world or persists a
+  // spawn-pending request for the MCP/CLI layer to drain.
+  //
+  // The body cap here is 30 MiB — 25 MiB attachment ceiling + 5 MiB margin
+  // for the JSON envelope. Larger payloads are rejected at 413.
+  if (url.pathname === '/v1/dispatch-from-email' && req.method === 'POST') {
+    const chunks = [];
+    let size = 0;
+    const MAX_BODY = 30 * 1024 * 1024;
+    let aborted = false;
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY) {
+        aborted = true;
+        jsonReply(res, 413, { error: 'body_too_large', maxBytes: MAX_BODY });
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', async () => {
+      if (aborted) return;
+      let dispatch;
+      try {
+        dispatch = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+      } catch (err) {
+        return jsonReply(res, 400, { error: 'invalid_json', message: err.message });
+      }
+      try {
+        const result = await handleDispatchFromEmail({
+          dispatch,
+          worlds: WORLDS,
+          secret: OLAM_EMAIL_SIGNING_SECRET,
+          attachmentsRoot: OLAM_EMAIL_ATTACHMENTS_ROOT,
+          allowlist: OLAM_EMAIL_ALLOWED_SENDERS,
+        });
+        return jsonReply(res, result.status, result.body);
+      } catch (err) {
+        return jsonReply(res, 500, {
+          error: 'dispatch_failed',
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    });
+    return;
+  }
+
   if (url.pathname === '/api/cloud-dispatch' && req.method === 'POST') {
     const cloudUrl = process.env.OLAM_CLOUD_URL;
     const showcasePw = process.env.OLAM_SHOWCASE_PASSWORD;
@@ -3078,6 +3250,7 @@ for (const sig of ['SIGTERM', 'SIGINT']) {
     stopListeningSnapshotLoop();
     if (serversSnapshotTimer) { clearTimeout(serversSnapshotTimer); serversSnapshotTimer = null; }
     hostStream.close();
+    if (ndjsonSpanSink) ndjsonSpanSink.close().catch(() => {});
     clearInterval(versionPollTimer);
     cache.clear();
     server.close(() => process.exit(0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pleri/olam-cli",
-  "version": "0.1.169",
+  "version": "0.1.170",
   "type": "module",
   "bin": {
     "olam": "./bin/olam.cjs"