@tea-agent/loop-agent 0.11.0 → 0.13.0-alpha.0

package/dist/worker/observe/paths.js

@@ -1,5 +1,22 @@
 import { existsSync, realpathSync } from "node:fs";
 import path from "node:path";
+const ALLOWED_ARTIFACT_EXTENSIONS = new Set([
+    ".csv",
+    ".diff",
+    ".json",
+    ".jsonl",
+    ".log",
+    ".md",
+    ".patch",
+    ".txt",
+    ".tsv",
+    ".xml",
+    ".yaml",
+    ".yml",
+]);
+export function isAllowedArtifactTextPath(artifactPath) {
+    return ALLOWED_ARTIFACT_EXTENSIONS.has(path.extname(artifactPath).toLowerCase());
+}
 export function resolveArtifactPath(repoRoot, artifactPath) {
     if (!artifactPath) {
         return null;

package/dist/worker/observe/routes.js

@@ -1,11 +1,15 @@
 import { existsSync } from "node:fs";
-import { readFile, stat } from "node:fs/promises";
+import { open as openFile, readFile, stat } from "node:fs/promises";
 import path from "node:path";
+import { redactSecrets, truncateUtf8Preview } from "../../shared/preview.js";
 import { parseWorkerEventLine } from "../observability/events.js";
 import { isSafeObservabilityIdentifier } from "../observability/event-store.js";
-import { buildGlobalSnapshot } from "../observability/read-model.js";
+import { clampEventHistoryLimit, listBatchEventHistory, listPoolEventHistory, } from "../observability/event-history.js";
+import { buildGlobalSnapshot, clampTaskRunHistoryLimit, listTaskRunHistory, resolveLegacyTask, } from "../observability/read-model.js";
 import { getTaskPoolRoot } from "../pool/run-store.js";
-import { resolveArtifactPath, toRepoRelativeArtifactPath, } from "./paths.js";
+import { isAllowedArtifactTextPath, resolveArtifactPath, toRepoRelativeArtifactPath, } from "./paths.js";
+import { extractSpecEvidence, } from "./spec-evidence.js";
+const ARTIFACT_PREVIEW_MAX_BYTES = 64 * 1024;
 export function createObserveSnapshotCache() {
     return { expiresAt: 0 };
 }
@@ -13,9 +17,43 @@ const ROUTES = [
     { method: "GET", pattern: /^\/api\/health$/, handler: handleHealth },
     { method: "GET", pattern: /^\/api\/snapshot$/, handler: handleSnapshot },
     { method: "GET", pattern: /^\/api\/batches$/, handler: handleBatches },
-    { method: "GET", pattern: /^\/api\/batches\/([^/]+)$/, handler: handleBatchById },
+    {
+        method: "GET",
+        pattern: /^\/api\/batches\/([^/]+)\/events$/,
+        handler: handleBatchEvents,
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/batches\/([^/]+)$/,
+        handler: handleBatchById,
+    },
+    /**
+     * Pool bounded event history (cursor/limit). Distinct from SSE `/api/events/stream`
+     * and from run/session `?after=<line-offset>` integer offsets.
+     */
+    { method: "GET", pattern: /^\/api\/events$/, handler: handlePoolEvents },
     { method: "GET", pattern: /^\/api\/tasks$/, handler: handleTasks },
-    { method: "GET", pattern: /^\/api\/tasks\/([^/]+)$/, handler: handleTaskById },
+    // Canonical feature-scoped task routes (must precede legacy /api/tasks/:id).
+    {
+        method: "GET",
+        pattern: /^\/api\/features\/([^/]+)\/tasks\/([^/]+)\/runs$/,
+        handler: handleFeatureTaskRuns,
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/features\/([^/]+)\/tasks\/([^/]+)$/,
+        handler: handleFeatureTaskById,
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/tasks\/([^/]+)\/runs$/,
+        handler: handleTaskRuns,
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/tasks\/([^/]+)$/,
+        handler: handleTaskById,
+    },
     { method: "GET", pattern: /^\/api\/runs\/([^/]+)$/, handler: handleRunById },
     {
         method: "GET",
@@ -32,9 +70,22 @@ const ROUTES = [
         pattern: /^\/api\/dag-runs\/([^/]+)\/nodes\/([^/]+)\/session-events$/,
         handler: handleDagNodeSessionEvents,
     },
-    { method: "GET", pattern: /^\/api\/dag-runs\/([^/]+)$/, handler: handleDagRunById },
+    {
+        method: "GET",
+        pattern: /^\/api\/dag-runs\/([^/]+)\/nodes\/([^/]+)\/spec-evidence$/,
+        handler: handleDagNodeSpecEvidence,
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/dag-runs\/([^/]+)$/,
+        handler: handleDagRunById,
+    },
     { method: "GET", pattern: /^\/api\/artifacts$/, handler: handleArtifactRead },
-    { method: "GET", pattern: /^\/api\/events\/stream$/, handler: handleEventStream },
+    {
+        method: "GET",
+        pattern: /^\/api\/events\/stream$/,
+        handler: handleEventStream,
+    },
 ];
 export async function handleRequest(req, res, ctx) {
     const method = req.method ?? "GET";
@@ -82,7 +133,8 @@ export async function serveStatic(req, res, staticDir) {
     const filePath = path.join(staticDir, pathname);
     const resolvedStatic = path.resolve(staticDir);
     const resolvedFile = path.resolve(filePath);
-    if (!resolvedFile.startsWith(resolvedStatic + path.sep) && resolvedFile !== resolvedStatic) {
+    if (!resolvedFile.startsWith(resolvedStatic + path.sep) &&
+        resolvedFile !== resolvedStatic) {
         sendJson(res, 404, { error: "Not found" });
         return;
     }
@@ -141,19 +193,149 @@ async function handleBatchById(_req, res, match, ctx) {
     }
     sendJson(res, 200, batch);
 }
+/**
+ * Bounded batch event history. Query: `limit` (default 50, max 200), `cursor`
+ * (opaque history cursor). Not the same as run/SSE `after` line offsets.
+ */
+async function handleBatchEvents(_req, res, match, ctx) {
+    const batchRunId = match.params.id;
+    if (!isSafeObservabilityIdentifier(batchRunId)) {
+        sendJson(res, 404, { error: "Batch not found" });
+        return;
+    }
+    const limit = clampEventHistoryLimit(parsePositiveInt(match.query.get("limit"), NaN));
+    const cursor = match.query.get("cursor") ?? undefined;
+    const page = await listBatchEventHistory(ctx.repoRoot, batchRunId, {
+        limit,
+        cursor,
+    });
+    sendJson(res, 200, page);
+}
+/**
+ * Bounded pool-wide event history. Path is `/api/events` (JSON page), not
+ * `/api/events/stream` (SSE). Uses `cursor`/`limit`, not integer `after`.
+ */
+async function handlePoolEvents(_req, res, match, ctx) {
+    const limit = clampEventHistoryLimit(parsePositiveInt(match.query.get("limit"), NaN));
+    const cursor = match.query.get("cursor") ?? undefined;
+    const page = await listPoolEventHistory(ctx.repoRoot, { limit, cursor });
+    sendJson(res, 200, page);
+}
 async function handleTasks(_req, res, _match, ctx) {
     const snapshot = await getSnapshot(ctx);
     sendJson(res, 200, snapshot.tasks);
 }
-async function handleTaskById(_req, res, match, ctx) {
+async function handleFeatureTaskById(_req, res, match, ctx) {
+    const resolved = resolveFeatureTaskParams(match);
+    if (!resolved) {
+        sendJson(res, 400, { error: "Invalid task identifier" });
+        return;
+    }
+    if (!isSafeObservabilityIdentifier(resolved.featureId) ||
+        !isSafeObservabilityIdentifier(resolved.taskId)) {
+        sendJson(res, 400, { error: "Invalid task identifier" });
+        return;
+    }
     const snapshot = await getSnapshot(ctx);
-    const task = snapshot.tasks.find((t) => t.taskId === match.params.id);
+    const task = snapshot.tasks.find((t) => t.featureId === resolved.featureId && t.taskId === resolved.taskId);
     if (!task) {
         sendJson(res, 404, { error: "Task not found" });
         return;
     }
     sendJson(res, 200, task);
 }
+async function handleFeatureTaskRuns(_req, res, match, ctx) {
+    const resolved = resolveFeatureTaskParams(match);
+    if (!resolved) {
+        sendJson(res, 400, { error: "Invalid task identifier" });
+        return;
+    }
+    if (!isSafeObservabilityIdentifier(resolved.featureId) ||
+        !isSafeObservabilityIdentifier(resolved.taskId)) {
+        sendJson(res, 400, { error: "Invalid task identifier" });
+        return;
+    }
+    const limit = clampTaskRunHistoryLimit(parsePositiveInt(match.query.get("limit"), 0) || undefined);
+    const before = match.query.get("before");
+    const page = await listTaskRunHistory(ctx.repoRoot, resolved.featureId, resolved.taskId, {
+        limit,
+        before: before && before.length > 0 ? before : null,
+    });
+    // 404 only when neither snapshot row nor ledger history exists for this composite id.
+    if (page.runs.length === 0) {
+        const snapshot = await getSnapshot(ctx);
+        const known = snapshot.tasks.some((t) => t.featureId === resolved.featureId && t.taskId === resolved.taskId);
+        if (!known) {
+            sendJson(res, 404, { error: "Task not found" });
+            return;
+        }
+    }
+    sendJson(res, 200, page);
+}
+async function handleTaskById(_req, res, match, ctx) {
+    const taskId = match.params.id;
+    if (!isSafeObservabilityIdentifier(taskId)) {
+        sendJson(res, 400, { error: "Invalid task identifier" });
+        return;
+    }
+    const snapshot = await getSnapshot(ctx);
+    const resolved = resolveLegacyTask(snapshot.tasks, taskId);
+    if (resolved.kind === "missing") {
+        sendJson(res, 404, { error: "Task not found" });
+        return;
+    }
+    if (resolved.kind === "ambiguous") {
+        sendJson(res, 409, ambiguousTaskBody(taskId, resolved.candidates));
+        return;
+    }
+    sendJson(res, 200, resolved.task);
+}
+async function handleTaskRuns(_req, res, match, ctx) {
+    const taskId = match.params.id;
+    if (!isSafeObservabilityIdentifier(taskId)) {
+        sendJson(res, 400, { error: "Invalid task identifier" });
+        return;
+    }
+    const snapshot = await getSnapshot(ctx);
+    const resolved = resolveLegacyTask(snapshot.tasks, taskId);
+    if (resolved.kind === "ambiguous") {
+        sendJson(res, 409, ambiguousTaskBody(taskId, resolved.candidates));
+        return;
+    }
+    if (resolved.kind === "missing") {
+        // No snapshot row: do not guess featureId for history.
+        sendJson(res, 404, { error: "Task not found" });
+        return;
+    }
+    const featureId = resolved.task.featureId;
+    if (!featureId) {
+        sendJson(res, 404, { error: "Task not found" });
+        return;
+    }
+    const limit = clampTaskRunHistoryLimit(parsePositiveInt(match.query.get("limit"), 0) || undefined);
+    const before = match.query.get("before");
+    const page = await listTaskRunHistory(ctx.repoRoot, featureId, taskId, {
+        limit,
+        before: before && before.length > 0 ? before : null,
+    });
+    sendJson(res, 200, page);
+}
+function ambiguousTaskBody(taskId, candidates) {
+    return {
+        error: "Task identity ambiguous",
+        taskId,
+        candidates,
+    };
+}
+/** Extract featureId/taskId from /api/features/:featureId/tasks/:taskId[...]. */
+function resolveFeatureTaskParams(match) {
+    // handleRequest maps capture groups to params.id (group 1) and params.sub (group 2).
+    const featureId = match.params.featureId ?? match.params.id;
+    const taskId = match.params.taskId ?? match.params.sub;
+    if (!featureId || !taskId)
+        return null;
+    return { featureId, taskId };
+}
 async function handleRunById(_req, res, match, ctx) {
     if (!isSafeObservabilityIdentifier(match.params.id)) {
         sendJson(res, 400, { error: "Invalid run identifier" });
@@ -226,7 +408,8 @@ async function handleDagRunById(_req, res, match, ctx) {
 async function handleDagNodeSessionEvents(_req, res, match, ctx) {
     const dagRunId = match.params.id;
     const nodeId = match.params.sub;
-    if (!isSafeObservabilityIdentifier(dagRunId) || !isSafeObservabilityIdentifier(nodeId)) {
+    if (!isSafeObservabilityIdentifier(dagRunId) ||
+        !isSafeObservabilityIdentifier(nodeId)) {
         sendJson(res, 400, { error: "Invalid dag run or node identifier" });
         return;
     }
@@ -248,7 +431,7 @@ async function handleDagNodeSessionEvents(_req, res, match, ctx) {
 async function handleArtifactRead(_req, res, match, ctx) {
     const relativePath = match.query.get("path") ?? "";
     const resolved = resolveArtifactPath(ctx.repoRoot, relativePath);
-    if (!resolved) {
+    if (!resolved || !isAllowedArtifactTextPath(relativePath)) {
         sendJson(res, 400, { error: "Invalid artifact path" });
         return;
     }
@@ -256,18 +439,47 @@ async function handleArtifactRead(_req, res, match, ctx) {
         sendJson(res, 404, { error: "Artifact not found" });
         return;
     }
-    const raw = await readFile(resolved, "utf-8");
+    const artifactStat = await stat(resolved);
+    if (!artifactStat.isFile()) {
+        sendJson(res, 400, { error: "Artifact is not a readable text file" });
+        return;
+    }
+    const sourceBytes = artifactStat.size;
+    const start = Math.max(0, sourceBytes - ARTIFACT_PREVIEW_MAX_BYTES);
+    const length = Math.min(sourceBytes, ARTIFACT_PREVIEW_MAX_BYTES);
+    const buffer = Buffer.alloc(length);
+    const handle = await openFile(resolved, "r");
+    let bytesRead = 0;
+    try {
+        ({ bytesRead } = await handle.read(buffer, 0, length, start));
+    }
+    finally {
+        await handle.close();
+    }
+    let raw = buffer.subarray(0, bytesRead).toString("utf-8");
+    let truncated = start > 0;
+    if (truncated) {
+        const firstCompleteLine = raw.indexOf("\n");
+        raw = firstCompleteLine >= 0 ? raw.slice(firstCompleteLine + 1) : "";
+    }
     const tail = match.query.get("tail");
     if (tail !== null) {
         const tailLines = parsePositiveInt(tail, 0);
         if (tailLines > 0) {
             const lines = raw.replace(/\n$/, "").split("\n");
-            const content = lines.slice(-tailLines).join("\n");
-            sendJson(res, 200, { content });
-            return;
+            truncated = truncated || lines.length > tailLines;
+            raw = lines.slice(-tailLines).join("\n");
         }
     }
-    sendJson(res, 200, { content: raw });
+    const redacted = redactSecrets(raw);
+    const content = truncateUtf8Preview(redacted, ARTIFACT_PREVIEW_MAX_BYTES);
+    truncated = truncated || content !== redacted;
+    sendJson(res, 200, {
+        content,
+        truncated,
+        sourceBytes,
+        maxBytes: ARTIFACT_PREVIEW_MAX_BYTES,
+    });
 }
 async function handleEventStream(req, res, match, ctx) {
     const batchRunId = match.query.get("batchRunId");
@@ -277,16 +489,34 @@ async function handleEventStream(req, res, match, ctx) {
     }
     res.writeHead(200, {
         "Content-Type": "text/event-stream",
-        "Cache-Control": "no-cache",
+        "Cache-Control": "no-cache, no-transform",
         Connection: "keep-alive",
+        // Disable proxy buffering (nginx) so heartbeats reach the client.
+        "X-Accel-Buffering": "no",
     });
+    // Flush headers immediately for proxies that wait on first body byte.
+    if (typeof res.flushHeaders === "function") {
+        res.flushHeaders();
+    }
     const observabilityRoot = path.join(getTaskPoolRoot(ctx.repoRoot), "observability");
     const eventsPath = path.join(observabilityRoot, "events.jsonl");
     let offset = 0;
     let knownFileSize;
     let timer;
     let closed = false;
+    let lastHeartbeatAt = 0;
+    const heartbeatEveryMs = Math.max(15_000, ctx.pollIntervalMs * 10);
+    const writeHeartbeat = () => {
+        if (closed || res.writableEnded)
+            return;
+        const now = Date.now();
+        if (now - lastHeartbeatAt < heartbeatEveryMs)
+            return;
+        lastHeartbeatAt = now;
+        res.write(`: keepalive ${new Date(now).toISOString()}\n\n`);
+    };
     const sendMatchingEvents = async (initial) => {
+        writeHeartbeat();
         let currentFileSize;
         try {
             currentFileSize = (await stat(eventsPath)).size;
@@ -338,7 +568,9 @@ async function handleEventStream(req, res, match, ctx) {
 }
 function findRunByWorkerRunId(tasks, batches, workerRunId) {
     return (tasks.find((task) => task.workerRunId === workerRunId) ??
-        batches.flatMap((batch) => batch.tasks).find((task) => task.workerRunId === workerRunId));
+        batches
+            .flatMap((batch) => batch.tasks)
+            .find((task) => task.workerRunId === workerRunId));
 }
 async function readJsonlLines(filePath, after) {
     const page = await readJsonlPage(filePath, after);
@@ -351,14 +583,17 @@ async function readJsonlPage(filePath, after) {
             .split("\n")
             .map((line) => line.trim())
             .filter(Boolean);
-        const events = lines.slice(after).map((line) => {
+        const events = lines
+            .slice(after)
+            .map((line) => {
             try {
                 return JSON.parse(line);
             }
             catch {
                 return undefined;
             }
-        }).filter((line) => line !== undefined);
+        })
+            .filter((line) => line !== undefined);
         return { events, nextOffset: lines.length };
     }
     catch {
@@ -367,7 +602,8 @@ async function readJsonlPage(filePath, after) {
 }
 const DAG_RUN_LIFECYCLE_DIRS = ["active", "completed", "paused"];
 function resolveSessionEventsPath(repoRoot, dagRunId, nodeId, dagRunDir) {
-    if (!isSafeObservabilityIdentifier(dagRunId) || !isSafeObservabilityIdentifier(nodeId)) {
+    if (!isSafeObservabilityIdentifier(dagRunId) ||
+        !isSafeObservabilityIdentifier(nodeId)) {
         return null;
     }
     const dagRunsRoot = path.resolve(repoRoot, ".harness", "dag-runs");
@@ -407,7 +643,7 @@ function isExpectedSessionEventsRelativePath(dagRunsRoot, resolvedPath, dagRunId
 function isPathInside(root, target) {
     const normalizedRoot = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
     const normalizedTarget = path.normalize(target);
-    return normalizedTarget === root || normalizedTarget.startsWith(normalizedRoot);
+    return (normalizedTarget === root || normalizedTarget.startsWith(normalizedRoot));
 }
 async function readFilteredEvents(filePath, offset, batchRunId, repoRoot) {
     try {
@@ -469,6 +705,57 @@ function sendJson(res, status, body) {
     });
     res.end(payload);
 }
+async function handleDagNodeSpecEvidence(_req, res, match, ctx) {
+    const dagRunId = match.params.id;
+    const nodeId = match.params.sub;
+    if (!isSafeObservabilityIdentifier(dagRunId) || !isSafeObservabilityIdentifier(nodeId)) {
+        sendJson(res, 400, { error: "Invalid dag run or node identifier" });
+        return;
+    }
+    // Extract skill injection info from the DAG run spec (run.json)
+    const skillInjection = { skills: [], references: [] };
+    const dagRunsRoot = path.resolve(ctx.repoRoot, ".harness", "dag-runs");
+    for (const lifecycle of ["active", "completed", "paused"]) {
+        const runJsonPath = path.join(dagRunsRoot, lifecycle, dagRunId, "run.json");
+        try {
+            const runRaw = await readFile(runJsonPath, "utf-8");
+            const runSpec = JSON.parse(runRaw);
+            const task = runSpec.tasks?.find((t) => t.id === nodeId);
+            if (task?.skills && Array.isArray(task.skills)) {
+                skillInjection.skills = task.skills;
+            }
+            break;
+        }
+        catch {
+            // run.json may not exist; continue to next lifecycle
+        }
+    }
+    const evidence = await extractSpecEvidence(ctx.repoRoot, dagRunId, nodeId);
+    if (!evidence) {
+        sendJson(res, 200, {
+            dagRunId,
+            nodeId,
+            status: "no-evidence",
+            skillInjection: { skills: [], references: [] },
+            specReads: [],
+            specSearches: [],
+            knowledgeBaseQueries: [],
+            summary: "未找到该节点的 session events 记录。",
+        });
+        return;
+    }
+    evidence.skillInjection = skillInjection;
+    // Recompute status considering skill injection
+    if (evidence.specReads.length === 0 && evidence.knowledgeBaseQueries.length === 0) {
+        if (evidence.specSearches.length > 0) {
+            evidence.status = "search-only";
+        }
+        else if (skillInjection.skills.length > 0) {
+            evidence.status = "spec-injected";
+        }
+    }
+    sendJson(res, 200, evidence);
+}
 function contentTypeFor(pathname) {
     if (pathname.endsWith(".html"))
         return "text/html; charset=utf-8";

package/dist/worker/observe/server.js

@@ -3,14 +3,18 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createObserveSnapshotCache, handleRequest, serveStatic, } from "./routes.js";
 const STATIC_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "static");
+/** Align with common reverse-proxy keepalive (e.g. nginx 75s). */
+const DEFAULT_KEEP_ALIVE_TIMEOUT_MS = 65_000;
 export function createObserveServer(options) {
     const repoRoot = path.resolve(options.repoRoot);
     const host = options.host ?? "127.0.0.1";
     if (!isLoopbackHost(host)) {
-        return Promise.reject(new Error(`observe serve is local-only; refusing non-loopback host ${host}`));
+        process.stderr.write(`observe serve: binding non-loopback host ${host} (read-only; no auth — expose only on trusted networks)\n`);
     }
     const port = options.port ?? 0;
     const pollIntervalMs = options.pollIntervalMs ?? 1000;
+    const debug = options.debug === true;
+    const keepAliveTimeoutMs = options.keepAliveTimeoutMs ?? DEFAULT_KEEP_ALIVE_TIMEOUT_MS;
     const routeContext = {
         repoRoot,
         pollIntervalMs,
@@ -19,6 +23,24 @@ export function createObserveServer(options) {
     };
     return new Promise((resolve, reject) => {
         const server = createServer((req, res) => {
+            const startedAt = Date.now();
+            req.socket?.on("error", () => {
+                // Ignore client resets; avoid unhandled socket error noise.
+            });
+            if (debug) {
+                let logged = false;
+                const onceLog = (note) => {
+                    if (logged)
+                        return;
+                    logged = true;
+                    logRequest(req, res, startedAt, note);
+                };
+                res.on("finish", () => onceLog());
+                res.on("close", () => {
+                    if (!res.writableFinished)
+                        onceLog("aborted");
+                });
+            }
             void dispatch(req, res).catch((error) => {
                 if (!res.headersSent) {
                     const payload = JSON.stringify({
@@ -32,6 +54,19 @@ export function createObserveServer(options) {
                 }
             });
         });
+        server.keepAliveTimeout = keepAliveTimeoutMs;
+        // Must exceed keepAliveTimeout or Node resets the timer incorrectly.
+        server.headersTimeout = keepAliveTimeoutMs + 5_000;
+        // Allow long-lived SSE; per-request work still finishes promptly.
+        server.requestTimeout = 0;
+        server.on("clientError", (err, socket) => {
+            if (debug) {
+                process.stderr.write(`[observe] ${new Date().toISOString()} clientError ${err.message}\n`);
+            }
+            if (!socket.destroyed) {
+                socket.end("HTTP/1.1 400 Bad Request\r\n\r\n");
+            }
+        });
         async function dispatch(req, res) {
             const handled = await handleRequest(req, res, routeContext);
             if (!handled) {
@@ -45,6 +80,9 @@ export function createObserveServer(options) {
                 reject(new Error("Failed to get server address"));
                 return;
             }
+            if (debug) {
+                process.stderr.write(`[observe] debug logging enabled; keepAliveTimeout=${keepAliveTimeoutMs}ms\n`);
+            }
             resolve({
                 url: `http://${host}:${addr.port}`,
                 close: () => new Promise((closeResolve, closeReject) => {
@@ -61,3 +99,23 @@ function isLoopbackHost(host) {
         normalized === "[::1]" ||
         /^127(?:\.\d{1,3}){3}$/.test(normalized));
 }
+function requestSource(req) {
+    const forwarded = req.headers["x-forwarded-for"];
+    if (typeof forwarded === "string" && forwarded.trim()) {
+        return forwarded.split(",")[0]?.trim() || forwarded.trim();
+    }
+    if (Array.isArray(forwarded) && forwarded[0]) {
+        return forwarded[0].split(",")[0]?.trim() || forwarded[0];
+    }
+    const realIp = req.headers["x-real-ip"];
+    if (typeof realIp === "string" && realIp.trim()) {
+        return realIp.trim();
+    }
+    return req.socket.remoteAddress ?? "-";
+}
+function logRequest(req, res, startedAt, note) {
+    const ms = Date.now() - startedAt;
+    const ua = String(req.headers["user-agent"] ?? "-").slice(0, 120);
+    const suffix = note ? ` ${note}` : "";
+    process.stderr.write(`[observe] ${new Date().toISOString()} ${req.method ?? "?"} ${req.url ?? "/"} ${res.statusCode} ${ms}ms from=${requestSource(req)} ua=${JSON.stringify(ua)}${suffix}\n`);
+}