@remnic/core 1.1.11 → 1.1.13

package/src/negative.ts

@@ -0,0 +1,72 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { log } from "./logger.js";
+
+export interface NegativeExampleEntry {
+  notUseful: number;
+  lastUpdatedAt: string;
+  notes?: string[];
+}
+
+type NegativeState = Record<string, NegativeExampleEntry>;
+
+export class NegativeExampleStore {
+  private readonly statePath: string;
+  private state: NegativeState = {};
+
+  constructor(memoryDir: string) {
+    this.statePath = path.join(memoryDir, "state", "negative_examples.json");
+  }
+
+  async load(): Promise<void> {
+    try {
+      const raw = await readFile(this.statePath, "utf-8");
+      const parsed = JSON.parse(raw) as NegativeState;
+      if (parsed && typeof parsed === "object") this.state = parsed;
+    } catch {
+      this.state = {};
+    }
+  }
+
+  /**
+   * Record that a memory was retrieved but not useful for the user.
+   * This should be lightweight and never block agent execution.
+   */
+  async recordNotUseful(memoryIds: string[], note?: string): Promise<void> {
+    const now = new Date().toISOString();
+
+    for (const memoryId of memoryIds) {
+      const existing = this.state[memoryId] ?? { notUseful: 0, lastUpdatedAt: now };
+      const next: NegativeExampleEntry = {
+        notUseful: existing.notUseful + 1,
+        lastUpdatedAt: now,
+        notes: note
+          ? [...(existing.notes ?? []).slice(-19), note]
+          : existing.notes,
+      };
+      this.state[memoryId] = next;
+    }
+
+    try {
+      await mkdir(path.dirname(this.statePath), { recursive: true });
+      await writeFile(this.statePath, JSON.stringify(this.state, null, 2), "utf-8");
+    } catch (err) {
+      log.debug(`negative example store write failed: ${err}`);
+    }
+  }
+
+  /**
+   * Convert negative examples into a small score penalty.
+   * Intended as a soft bias, not a hard filter.
+   */
+  penalty(memoryId: string, opts: { perHit: number; cap: number }): number {
+    const entry = this.state[memoryId];
+    if (!entry) return 0;
+
+    // Cap effect to avoid runaway ranking distortion.
+    const hits = Math.min(10, entry.notUseful);
+    const raw = hits * opts.perHit;
+    return Math.min(opts.cap, raw);
+  }
+}
+

package/src/network/tailscale.ts

@@ -0,0 +1,179 @@
+import { stat } from "node:fs/promises";
+import { launchProcess } from "../runtime/child-process.js";
+
+export interface TailscaleCommandResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+export type TailscaleCommandRunner = (
+  command: string,
+  args: string[],
+  options?: { timeoutMs?: number },
+) => Promise<TailscaleCommandResult>;
+
+export interface TailscaleStatus {
+  available: boolean;
+  running: boolean;
+  backendState?: string;
+  version?: string;
+  selfHostname?: string;
+  selfIp?: string;
+}
+
+export interface TailscaleSyncOptions {
+  sourceDir: string;
+  destination: string;
+  delete?: boolean;
+  dryRun?: boolean;
+  extraArgs?: string[];
+}
+
+export interface TailscaleHelperOptions {
+  tailscaleBinary?: string;
+  rsyncBinary?: string;
+  timeoutMs?: number;
+  runner?: TailscaleCommandRunner;
+}
+
+interface TailscaleStatusJson {
+  BackendState?: string;
+  Version?: string;
+  Self?: {
+    HostName?: string;
+    TailscaleIPs?: string[];
+  };
+}
+
+export class TailscaleHelper {
+  private readonly tailscaleBinary: string;
+  private readonly rsyncBinary: string;
+  private readonly timeoutMs: number;
+  private readonly runner: TailscaleCommandRunner;
+
+  constructor(options: TailscaleHelperOptions = {}) {
+    this.tailscaleBinary = options.tailscaleBinary ?? "tailscale";
+    this.rsyncBinary = options.rsyncBinary ?? "rsync";
+    this.timeoutMs = options.timeoutMs ?? 10_000;
+    this.runner = options.runner ?? defaultCommandRunner;
+  }
+
+  async isAvailable(): Promise<boolean> {
+    const result = await this.runner(this.tailscaleBinary, ["version"], { timeoutMs: this.timeoutMs });
+    return result.code === 0;
+  }
+
+  async status(): Promise<TailscaleStatus> {
+    const available = await this.isAvailable();
+    if (!available) {
+      return { available: false, running: false };
+    }
+
+    const result = await this.runner(this.tailscaleBinary, ["status", "--json"], { timeoutMs: this.timeoutMs });
+    if (result.code !== 0) {
+      return { available: true, running: false };
+    }
+
+    let parsed: TailscaleStatusJson;
+    try {
+      parsed = JSON.parse(result.stdout) as TailscaleStatusJson;
+    } catch {
+      throw new Error("tailscale status returned invalid JSON");
+    }
+
+    const backendState = parsed.BackendState ?? "";
+    return {
+      available: true,
+      running: backendState === "Running",
+      backendState,
+      version: parsed.Version,
+      selfHostname: parsed.Self?.HostName,
+      selfIp: parsed.Self?.TailscaleIPs?.[0],
+    };
+  }
+
+  async syncDirectory(options: TailscaleSyncOptions): Promise<void> {
+    await assertReadableDirectory(options.sourceDir);
+
+    const tailscaleStatus = await this.status();
+    if (!tailscaleStatus.available) {
+      throw new Error("tailscale is not installed or not available in PATH");
+    }
+    if (!tailscaleStatus.running) {
+      throw new Error("tailscale daemon is not running");
+    }
+
+    const args: string[] = ["-az"];
+    if (options.delete) args.push("--delete");
+    if (options.dryRun) args.push("--dry-run");
+    if (options.extraArgs?.length) args.push(...options.extraArgs);
+
+    const sourceWithTrailingSlash = options.sourceDir.endsWith("/") ? options.sourceDir : `${options.sourceDir}/`;
+    args.push(sourceWithTrailingSlash, options.destination);
+
+    const result = await this.runner(this.rsyncBinary, args);
+    if (result.code !== 0) {
+      const stderr = result.stderr.trim();
+      throw new Error(stderr ? `rsync failed: ${stderr}` : "rsync failed");
+    }
+  }
+}
+
+async function assertReadableDirectory(dir: string): Promise<void> {
+  const info = await stat(dir);
+  if (!info.isDirectory()) {
+    throw new Error(`sourceDir must be a directory: ${dir}`);
+  }
+}
+
+const defaultCommandRunner: TailscaleCommandRunner = (command, args, options) => {
+  return new Promise((resolve) => {
+    const child = launchProcess(command, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (!child.stdout || !child.stderr) {
+      resolve({ code: 1, stdout: "", stderr: "command pipes unavailable" });
+      return;
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+
+    const timeoutMs = options?.timeoutMs;
+    const timeout = typeof timeoutMs === "number" && timeoutMs > 0
+      ? setTimeout(() => {
+          if (settled) return;
+          settled = true;
+          child.kill("SIGKILL");
+          resolve({
+            code: 124,
+            stdout,
+            stderr: stderr || "command timed out",
+          });
+        }, timeoutMs)
+      : null;
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf-8");
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf-8");
+    });
+
+    child.on("error", () => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      resolve({ code: 1, stdout, stderr });
+    });
+
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      resolve({ code: code ?? 1, stdout, stderr });
+    });
+  });
+};

package/src/network/webdav.ts

@@ -0,0 +1,385 @@
+import { createReadStream } from "node:fs";
+import { mkdir, readdir, realpath, stat } from "node:fs/promises";
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { timingSafeEqual } from "node:crypto";
+import path from "node:path";
+import { pipeline } from "node:stream/promises";
+import { URL } from "node:url";
+
+export function hostToUrlAuthority(host: string): string {
+  if (host.includes(":") && !host.startsWith("[") && !host.endsWith("]")) {
+    return `[${host}]`;
+  }
+  return host;
+}
+
+export interface WebDavAuth {
+  username: string;
+  password: string;
+}
+
+export interface WebDavServerOptions {
+  enabled?: boolean;
+  host?: string;
+  port: number;
+  allowlistDirs: string[];
+  auth?: WebDavAuth;
+}
+
+export interface WebDavServerStatus {
+  running: boolean;
+  host: string;
+  port: number;
+  rootCount: number;
+}
+
+interface AllowedRoot {
+  absolute: string;
+  name: string;
+}
+
+export class WebDavServer {
+  private readonly options: Required<Omit<WebDavServerOptions, "auth">> & Pick<WebDavServerOptions, "auth">;
+  private readonly allowedRoots: AllowedRoot[];
+  private server: Server | null = null;
+  private boundPort: number;
+
+  private constructor(
+    options: Required<Omit<WebDavServerOptions, "auth">> & Pick<WebDavServerOptions, "auth">,
+    allowedRoots: AllowedRoot[],
+  ) {
+    this.options = options;
+    this.allowedRoots = allowedRoots;
+    this.boundPort = options.port;
+  }
+
+  static async create(input: WebDavServerOptions): Promise<WebDavServer> {
+    const options: Required<Omit<WebDavServerOptions, "auth">> & Pick<WebDavServerOptions, "auth"> = {
+      enabled: input.enabled ?? false,
+      host: input.host ?? "127.0.0.1",
+      port: input.port,
+      allowlistDirs: input.allowlistDirs,
+      auth: input.auth,
+    };
+
+    if (!Array.isArray(options.allowlistDirs) || options.allowlistDirs.length === 0) {
+      throw new Error("webdav allowlistDirs must include at least one directory");
+    }
+    if (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535) {
+      throw new Error(`invalid webdav port: ${options.port}`);
+    }
+
+    const allowedRoots: AllowedRoot[] = [];
+    const aliasSet = new Set<string>();
+    for (const dir of options.allowlistDirs) {
+      const resolved = path.resolve(dir);
+      await mkdir(resolved, { recursive: true });
+      const canonical = await realpath(resolved);
+      const alias = path.basename(canonical) || "root";
+      if (aliasSet.has(alias)) {
+        throw new Error(`duplicate webdav allowlist alias: ${alias}`);
+      }
+      aliasSet.add(alias);
+      allowedRoots.push({ absolute: canonical, name: alias });
+    }
+
+    return new WebDavServer(options, allowedRoots);
+  }
+
+  async start(): Promise<WebDavServerStatus> {
+    if (!this.options.enabled) {
+      throw new Error("webdav server is disabled; set enabled=true to start");
+    }
+    if (this.server) {
+      return this.status();
+    }
+
+    const server = createServer((req, res) => {
+      this.handle(req, res).catch((err) => {
+        if (res.headersSent) {
+          res.destroy(err as Error);
+          return;
+        }
+        res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+        res.end("webdav error");
+      });
+    });
+    this.server = server;
+
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const onError = (err: Error) => {
+          server.removeListener("listening", onListening);
+          reject(err);
+        };
+        const onListening = () => {
+          server.removeListener("error", onError);
+          resolve();
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(this.options.port, this.options.host);
+      });
+    } catch (err) {
+      this.server = null;
+      server.close();
+      throw err;
+    }
+
+    const address = server.address();
+    if (address && typeof address !== "string") {
+      this.boundPort = address.port;
+    }
+
+    return this.status();
+  }
+
+  async stop(): Promise<void> {
+    if (!this.server) return;
+    const server = this.server;
+    this.server = null;
+    this.boundPort = this.options.port;
+    await new Promise<void>((resolve, reject) => {
+      server.close((err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  status(): WebDavServerStatus {
+    return {
+      running: this.server !== null,
+      host: this.options.host,
+      port: this.boundPort,
+      rootCount: this.allowedRoots.length,
+    };
+  }
+
+  private async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    if (!this.isAuthorized(req)) {
+      res.writeHead(401, {
+        "WWW-Authenticate": 'Basic realm="Engram WebDAV"',
+        "Content-Type": "text/plain; charset=utf-8",
+      });
+      res.end("authentication required");
+      return;
+    }
+
+    const method = (req.method ?? "GET").toUpperCase();
+    if (method === "OPTIONS") {
+      res.writeHead(204, {
+        Allow: "OPTIONS, PROPFIND, GET, HEAD",
+        DAV: "1",
+      });
+      res.end();
+      return;
+    }
+
+    const parsed = new URL(req.url ?? "/", `http://${hostToUrlAuthority(this.options.host)}`);
+    const resolved = await this.resolvePath(parsed.pathname);
+    if (!resolved.ok) {
+      res.writeHead(resolved.code, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end(resolved.message);
+      return;
+    }
+
+    if (method === "PROPFIND") {
+      await this.handlePropfind(resolved.absolutePath, resolved.displayPath, res);
+      return;
+    }
+
+    if (method === "GET" || method === "HEAD") {
+      await this.handleRead(method, resolved.absolutePath, res);
+      return;
+    }
+
+    res.writeHead(405, {
+      Allow: "OPTIONS, PROPFIND, GET, HEAD",
+      "Content-Type": "text/plain; charset=utf-8",
+    });
+    res.end("method not allowed");
+  }
+
+  private isAuthorized(req: IncomingMessage): boolean {
+    if (!this.options.auth) return true;
+    const raw = req.headers.authorization;
+    if (!raw) return false;
+    const separator = raw.indexOf(" ");
+    if (separator <= 0) return false;
+    const scheme = raw.slice(0, separator).toLowerCase();
+    if (scheme !== "basic") return false;
+    const encodedPart = raw.slice(separator + 1).trim();
+    if (!encodedPart) return false;
+
+    try {
+      const decoded = Buffer.from(encodedPart, "base64").toString("utf-8");
+      const credentialSeparator = decoded.indexOf(":");
+      if (credentialSeparator < 0) return false;
+      const username = decoded.slice(0, credentialSeparator);
+      const password = decoded.slice(credentialSeparator + 1);
+      const usernameOk = this.timingSafeStringEqual(username, this.options.auth.username);
+      const passwordOk = this.timingSafeStringEqual(password, this.options.auth.password);
+      return Boolean((usernameOk ? 1 : 0) & (passwordOk ? 1 : 0));
+    } catch {
+      return false;
+    }
+  }
+
+  private timingSafeStringEqual(a: string, b: string): boolean {
+    const left = this.encodeAuthField(a);
+    const right = this.encodeAuthField(b);
+    if (!left || !right) return false;
+    return timingSafeEqual(left, right);
+  }
+
+  private encodeAuthField(value: string): Buffer | null {
+    const maxBytes = 512;
+    const encoded = Buffer.from(value, "utf-8");
+    if (encoded.length > maxBytes) return null;
+    const out = Buffer.alloc(2 + maxBytes);
+    out.writeUInt16BE(encoded.length, 0);
+    encoded.copy(out, 2);
+    return out;
+  }
+
+  private async resolvePath(requestPathname: string): Promise<
+    | { ok: true; absolutePath: string; displayPath: string }
+    | { ok: false; code: number; message: string }
+  > {
+    let decodedPath: string;
+    try {
+      decodedPath = decodeURIComponent(requestPathname || "/");
+    } catch {
+      return { ok: false, code: 400, message: "invalid path encoding" };
+    }
+    if (decodedPath.includes("\0")) {
+      return { ok: false, code: 400, message: "invalid path" };
+    }
+
+    const normalized = path.posix.normalize(decodedPath);
+    const segments = normalized.split("/").filter((segment) => segment.length > 0);
+
+    if (segments.length === 0) {
+      return { ok: false, code: 403, message: "root listing is not allowed" };
+    }
+
+    const rootName = segments[0];
+    const root = this.allowedRoots.find((entry) => entry.name === rootName);
+    if (!root) {
+      return { ok: false, code: 403, message: "path is outside allowlist" };
+    }
+
+    const relative = segments.slice(1);
+    if (relative.some((segment) => segment === ".." || segment.includes("\\"))) {
+      return { ok: false, code: 403, message: "path traversal is not allowed" };
+    }
+
+    const candidate = path.resolve(root.absolute, ...relative);
+    if (!this.isPathInside(root.absolute, candidate)) {
+      return { ok: false, code: 403, message: "path escaped allowlist" };
+    }
+
+    try {
+      const canonicalCandidate = await realpath(candidate);
+      if (!this.isPathInside(root.absolute, canonicalCandidate)) {
+        return { ok: false, code: 403, message: "path escaped allowlist via symlink" };
+      }
+      return { ok: true, absolutePath: canonicalCandidate, displayPath: `/${segments.join("/")}` };
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === "ENOENT") {
+        return { ok: true, absolutePath: candidate, displayPath: `/${segments.join("/")}` };
+      }
+      if (code === "ENOTDIR" || code === "ELOOP") {
+        return { ok: false, code: 400, message: "invalid path" };
+      }
+      throw err;
+    }
+  }
+
+  private async handleRead(method: "GET" | "HEAD", absolutePath: string, res: ServerResponse): Promise<void> {
+    let info;
+    try {
+      info = await stat(absolutePath);
+    } catch {
+      res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end("not found");
+      return;
+    }
+
+    if (!info.isFile()) {
+      res.writeHead(403, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end("path is not a file");
+      return;
+    }
+
+    res.writeHead(200, {
+      "Content-Length": String(info.size),
+      "Content-Type": "application/octet-stream",
+    });
+
+    if (method === "HEAD") {
+      res.end();
+      return;
+    }
+
+    await pipeline(createReadStream(absolutePath), res);
+  }
+
+  private async handlePropfind(absolutePath: string, displayPath: string, res: ServerResponse): Promise<void> {
+    let info;
+    try {
+      info = await stat(absolutePath);
+    } catch {
+      res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end("not found");
+      return;
+    }
+
+    const entries: string[] = [];
+    if (info.isDirectory()) {
+      const children = await readdir(absolutePath, { withFileTypes: true });
+      for (const child of children) {
+        const childHref = toEncodedHref(`${displayPath.replace(/\/$/, "")}/${child.name}`);
+        entries.push(`
+  <d:response>
+    <d:href>${xmlEscape(childHref)}</d:href>
+    <d:propstat><d:prop><d:resourcetype>${child.isDirectory() ? "<d:collection/>" : ""}</d:resourcetype></d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat>
+  </d:response>`);
+      }
+    }
+
+    const xml = `<?xml version="1.0" encoding="utf-8"?>
+<d:multistatus xmlns:d="DAV:">
+  <d:response>
+    <d:href>${xmlEscape(toEncodedHref(displayPath))}</d:href>
+    <d:propstat><d:prop><d:resourcetype>${info.isDirectory() ? "<d:collection/>" : ""}</d:resourcetype></d:prop><d:status>HTTP/1.1 200 OK</d:status></d:propstat>
+  </d:response>${entries.join("")}
+</d:multistatus>`;
+
+    res.writeHead(207, { "Content-Type": "application/xml; charset=utf-8" });
+    res.end(xml);
+  }
+
+  private isPathInside(root: string, target: string): boolean {
+    if (target === root) return true;
+    if (root === path.parse(root).root) {
+      return target.startsWith(root);
+    }
+    return target.startsWith(`${root}${path.sep}`);
+  }
+}
+
+function xmlEscape(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+function toEncodedHref(pathname: string): string {
+  return pathname
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}