@schlessera/brain-ui-server 0.31.0 → 0.33.0

package/src/cron/run-job.ts

@@ -0,0 +1,254 @@
+/**
+ * Execute one container-cron job while recording its status and activity.
+ * Tracking is fail-open: database or activity failures never prevent the job
+ * from running, and the wrapper always returns the child's exit code.
+ */
+import { unlinkSync } from "fs";
+
+import { ingestSpanSink } from "../activity/span-sink.js";
+import { createActivityStore } from "../activity/store.js";
+import { createUiDb } from "../db/client.js";
+import { recordCronRun } from "./scheduler.js";
+
+/** Tail of stderr retained for the cron_runs error row. */
+export const STDERR_TAIL_CHARS = 2_000;
+/** Tail of combined stdout/stderr retained as the job_output activity event. */
+export const OUTPUT_TAIL_CHARS = 8_000;
+/** Heartbeat cadence, comfortably inside the activity store's stale threshold. */
+export const HEARTBEAT_MS = 30_000;
+/** Child-visible path where span-sink JSONL may be appended. */
+export const SPAN_SINK_ENV = "BRAIN_ACTIVITY_SPAN_SINK";
+
+interface TextSink {
+  write(text: string): unknown;
+}
+
+interface SpawnedJob {
+  stdout: ReadableStream<Uint8Array>;
+  stderr: ReadableStream<Uint8Array>;
+  exited: Promise<number>;
+  signalCode: string | null;
+}
+
+interface RunRecorder {
+  finish(error: string | undefined, output: string, exitCode: number): void;
+  close(): void;
+}
+
+export interface RunJobOptions {
+  jobName: string;
+  command: string[];
+  dbPath: string;
+  childEnv: Record<string, string | undefined>;
+  stdout?: TextSink;
+  stderr?: TextSink;
+}
+
+export interface RunJobDependencies {
+  spawn?: (
+    command: string[],
+    options: {
+      stdin: "inherit";
+      stdout: "pipe";
+      stderr: "pipe";
+      env: Record<string, string | undefined>;
+    }
+  ) => SpawnedJob;
+  sinkPath?: string;
+  startRecord?: (
+    name: string,
+    sinkPath: string,
+    command: string[],
+    dbPath: string,
+    stderr: TextSink
+  ) => Promise<RunRecorder | null>;
+  removeSink?: (path: string) => void;
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function writeLine(sink: TextSink, text: string): void {
+  sink.write(`${text}\n`);
+}
+
+/** Forward a stream verbatim while exposing decoded chunks for tail capture. */
+export async function teeStream(
+  stream: ReadableStream<Uint8Array>,
+  sink: TextSink,
+  onText: (text: string) => void
+): Promise<void> {
+  const decoder = new TextDecoder();
+  for await (const chunk of stream) {
+    const text = decoder.decode(chunk, { stream: true });
+    sink.write(text);
+    onText(text);
+  }
+}
+
+/** Keep the last `cap` characters, never the head. */
+export function appendTail(current: string, text: string, cap: number): string {
+  return (current + text).slice(-cap);
+}
+
+async function startRecord(
+  name: string,
+  sinkPath: string,
+  command: string[],
+  dbPath: string,
+  stderr: TextSink
+): Promise<RunRecorder | null> {
+  try {
+    const db = createUiDb(dbPath);
+    const record = recordCronRun(db, name);
+    const store = createActivityStore(db, { writer: `cron:${process.pid}` });
+    const runId = `cron-${name}-${Date.now()}`;
+    const rootSpanId = `${runId}:root`;
+    store.startSpan({
+      spanId: rootSpanId,
+      runId,
+      name: `cron ${name}`,
+      kind: "cron",
+      origin: "cron",
+      jobName: name,
+    });
+
+    let sinkOffset = 0;
+    const ingest = () => {
+      try {
+        const result = ingestSpanSink(
+          store,
+          sinkPath,
+          { runId, rootSpanId, jobName: name },
+          sinkOffset
+        );
+        sinkOffset = result.offset;
+      } catch {
+        // Sink lines are best-effort enrichment.
+      }
+    };
+
+    const heartbeat = setInterval(() => {
+      try {
+        store.heartbeat(rootSpanId);
+      } catch {
+        // Tracking remains fail-open after startup too.
+      }
+      ingest();
+    }, HEARTBEAT_MS);
+
+    return {
+      finish(error, output, exitCode) {
+        record.finish(error);
+        try {
+          ingest();
+          if (output) {
+            try {
+              store.appendEvent(rootSpanId, "job_output", output, undefined, OUTPUT_TAIL_CHARS);
+            } catch {
+              // Output capture is enrichment; never fail a run over it.
+            }
+          }
+          store.endSpan(rootSpanId, {
+            outcome: error === undefined ? "success" : "error",
+            reason: error,
+            attrs: {
+              "cron.command": command.join(" "),
+              "cron.exit_code": exitCode,
+            },
+          });
+          store.cascadeClose(runId, "cancelled", "job finished");
+          store.rollupRun(runId);
+        } catch (error) {
+          writeLine(stderr, `[cron-run] failed to close activity span: ${messageOf(error)}`);
+        } finally {
+          clearInterval(heartbeat);
+        }
+      },
+      close() {
+        clearInterval(heartbeat);
+        db.close();
+      },
+    };
+  } catch (error) {
+    writeLine(
+      stderr,
+      `[cron-run] tracking unavailable (job runs anyway): ${messageOf(error)}`
+    );
+    return null;
+  }
+}
+
+/** Run a job as argv (never through a shell) and return its exact exit code. */
+export async function runJob(
+  options: RunJobOptions,
+  dependencies: RunJobDependencies = {}
+): Promise<number> {
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const sinkPath =
+    dependencies.sinkPath ??
+    `/tmp/brain-activity-sink-${process.pid}-${Date.now()}.jsonl`;
+  const beginRecord = dependencies.startRecord ?? startRecord;
+  const recorder = await beginRecord(
+    options.jobName,
+    sinkPath,
+    options.command,
+    options.dbPath,
+    stderr
+  );
+
+  let exitCode: number;
+  let errorMessage: string | undefined;
+  let outputTail = "";
+
+  try {
+    const spawn = dependencies.spawn ?? ((command, spawnOptions) => Bun.spawn(command, spawnOptions));
+    const proc = spawn(options.command, {
+      stdin: "inherit",
+      stdout: "pipe",
+      stderr: "pipe",
+      env: { ...options.childEnv, [SPAN_SINK_ENV]: sinkPath },
+    });
+
+    let stderrTail = "";
+    await Promise.all([
+      teeStream(proc.stdout, stdout, (text) => {
+        outputTail = appendTail(outputTail, text, OUTPUT_TAIL_CHARS);
+      }),
+      teeStream(proc.stderr, stderr, (text) => {
+        stderrTail = appendTail(stderrTail, text, STDERR_TAIL_CHARS);
+        outputTail = appendTail(outputTail, text, OUTPUT_TAIL_CHARS);
+      }),
+    ]);
+
+    exitCode = await proc.exited;
+    if (exitCode !== 0) {
+      const cause = proc.signalCode ? `killed by ${proc.signalCode}` : `exit code ${exitCode}`;
+      const trimmedTail = stderrTail.trim();
+      errorMessage = trimmedTail ? `${cause}; stderr tail: ${trimmedTail}` : cause;
+    }
+  } catch (error) {
+    exitCode = 127;
+    errorMessage = messageOf(error);
+    writeLine(stderr, `[cron-run] failed to start job command: ${errorMessage}`);
+  }
+
+  if (recorder) {
+    try {
+      recorder.finish(errorMessage, outputTail.trim(), exitCode);
+      recorder.close();
+    } catch (error) {
+      writeLine(stderr, `[cron-run] failed to record run outcome: ${messageOf(error)}`);
+    }
+  }
+
+  try {
+    (dependencies.removeSink ?? unlinkSync)(sinkPath);
+  } catch {
+    // Never emitted, or already gone.
+  }
+
+  return exitCode;
+}

package/src/files/walker.ts

@@ -1,6 +1,5 @@
-import { readdir, readFile, stat, realpath } from "node:fs/promises";
-import { join, resolve, sep, posix, dirname } from "node:path";
-import { existsSync } from "node:fs";
+import { lstat, readdir, readFile, stat, realpath } from "node:fs/promises";
+import { join, relative, resolve, sep, posix, dirname } from "node:path";
 import ignore, { type Ignore } from "ignore";
 import type { FileEntry, FileContentKind } from "@schlessera/brain-ui-sdk/protocol";
 import { FILE_SIZE_CAP_BYTES } from "@schlessera/brain-ui-sdk/protocol";
@@ -25,6 +24,15 @@ const HARD_EXCLUDE_FILE_NAMES = new Set(
   ].map((n) => n.toLowerCase())
 );
 
+const UNRESOLVABLE_PATH_CODES = new Set([
+  "ENOENT",
+  "ENOTDIR",
+  "ENAMETOOLONG",
+  "ELOOP",
+  "EACCES",
+  "EPERM",
+]);
+
 export class PathEscapeError extends Error {
   constructor(rel: string) {
     super(`path_escape: ${rel}`);
@@ -52,8 +60,14 @@ export class TooLargeError extends Error {
  */
 export async function safeResolve(rel: string, root: string): Promise<string> {
   if (typeof rel !== "string") throw new PathEscapeError(String(rel));
-  // Reject absolute paths and null bytes
-  if (rel.startsWith("/") || rel.startsWith("\\") || rel.includes("\0")) {
+  const requestSegments = rel.split("/");
+  // Reject absolute paths, null bytes, and Windows path syntax before resolving.
+  if (
+    rel.startsWith("/") ||
+    rel.startsWith("\\") ||
+    rel.includes("\0") ||
+    requestSegments.some((segment) => segment.includes(":") || segment.includes("\\"))
+  ) {
     throw new PathEscapeError(rel);
   }
   // Normalize separators; reject ".." segments anywhere
@@ -61,14 +75,49 @@ export async function safeResolve(rel: string, root: string): Promise<string> {
   for (const seg of normalized.split("/")) {
     if (seg === "..") throw new PathEscapeError(rel);
   }
-  const absRoot = resolve(root);
+  const lexicalRoot = resolve(root);
+  let absRoot: string;
+  try {
+    absRoot = await realpath(lexicalRoot);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    absRoot = lexicalRoot;
+  }
   const abs = resolve(absRoot, normalized);
   if (abs !== absRoot && !abs.startsWith(absRoot + sep)) {
     throw new PathEscapeError(rel);
   }
-  // Check for symlink escape via realpath when the path exists
-  if (existsSync(abs)) {
-    const real = await realpath(abs);
+  // Canonicalize every existing component. Stopping at the first genuinely
+  // missing component permits callers to create a new path, while lstat
+  // distinguishes that case from a dangling symlink, which must fail closed.
+  let candidate = absRoot;
+  const candidates = [candidate];
+  for (const segment of relative(absRoot, abs).split(sep)) {
+    if (!segment || segment === ".") continue;
+    candidate = join(candidate, segment);
+    candidates.push(candidate);
+  }
+
+  for (const existing of candidates) {
+    try {
+      await lstat(existing);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code && UNRESOLVABLE_PATH_CODES.has(code)) break;
+      throw err;
+    }
+
+    let real: string;
+    try {
+      real = await realpath(existing);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === "ENOENT" || code === "ENOTDIR") {
+        throw new PathEscapeError(rel);
+      }
+      if (code && UNRESOLVABLE_PATH_CODES.has(code)) break;
+      throw err;
+    }
     if (real !== absRoot && !real.startsWith(absRoot + sep)) {
       throw new PathEscapeError(rel);
     }
@@ -373,7 +422,14 @@ export async function buildWikilinkMap(root: string): Promise<Record<string, str
       }
 
       if (childStat.isDirectory()) {
-        await walk(relChild);
+        try {
+          await walk(relChild);
+        } catch (err) {
+          // Directory names come from readdir rather than an external request.
+          // Keep request-facing validation strict, but skip a discovered path
+          // that safeResolve rejects instead of discarding the whole map.
+          if (!(err instanceof PathEscapeError)) throw err;
+        }
         continue;
       }
       const lower = d.name.toLowerCase();

package/src/index.ts

@@ -40,6 +40,9 @@ export {
   type ModelDiscoveryState,
 } from "./agent/backend.js";
 export {
+  authGuard,
+  bumpSessionsEpoch,
+  isWsAuthorized,
   resolveAuthMode,
   type AuthMode,
   type AuthRuntime,
@@ -73,7 +76,11 @@ export {
 
 // Brain repo access (spawned CLI wrapper) — useful for embedders that add
 // their own routes on top.
-export { createBrainClient, type BrainClient } from "./brain/client.js";
+export {
+  createBrainClient,
+  MIN_BRAIN_CLI_VERSION,
+  type BrainClient,
+} from "./brain/client.js";
 
 // Cron run history. Scheduling belongs to the deployment (container crontab);
 // an external scheduler's wrapper records each run here so /api/status's
@@ -107,6 +114,11 @@ export {
 // intake route also sweeps opportunistically on every share.
 export { pruneShareStaging, shareStagingRoot } from "./share/staging.js";
 
+// Skill archive transport sizing for deployment shells. The route keeps the
+// application-level check; consumers use this value only to avoid setting a
+// smaller process-level request ceiling.
+export { MAX_ARCHIVE_BYTES } from "./skills/install.js";
+
 // Observability: the producing side is the OpenTelemetry API, the consuming
 // side is ours. Swap the consumer to change where a deployment reports; a test
 // swaps in the recording one and asserts on what the server actually said.