@chendpoc/pi-memory 0.1.0

package/src/sidecar/client.ts

@@ -0,0 +1,166 @@
+import { randomBytes } from "node:crypto";
+import http from "node:http";
+
+import {
+  classifyHTTP,
+  classifyTransportError,
+  ErrTransport,
+  type ErrorClass,
+} from "../errclass.js";
+import type {
+  HealthPayload,
+  QueryIntent,
+  QueryRequest,
+  ReloadResponse,
+  ResponseEnvelope,
+} from "../types.js";
+
+function requestId(): string {
+  return `req-${randomBytes(6).toString("hex")}`;
+}
+
+export class SidecarClient {
+  constructor(
+    private readonly socketPath: string,
+    private readonly timeoutMs: number,
+  ) {}
+
+  async health(signal?: AbortSignal): Promise<HealthPayload> {
+    return this.do<HealthPayload>("GET", "/health", undefined, signal);
+  }
+
+  async query(
+    intent: QueryIntent,
+    signal?: AbortSignal,
+  ): Promise<{
+    env: ResponseEnvelope | null;
+    errorClass: ErrorClass;
+    transportError?: Error;
+  }> {
+    const rid = requestId();
+    const body: QueryRequest = { intent, request_id: rid };
+    try {
+      const { status, data } = await this.doRaw<ResponseEnvelope>(
+        "POST",
+        "/query",
+        body,
+        signal,
+        rid,
+      );
+      return {
+        env: data,
+        errorClass: classifyHTTP(status, data),
+      };
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("transport")) {
+        return {
+          env: null,
+          errorClass: classifyTransportError(err),
+          transportError: err,
+        };
+      }
+      return {
+        env: null,
+        errorClass: "unavailable",
+        transportError: err instanceof Error ? err : new Error(String(err)),
+      };
+    }
+  }
+
+  async reload(signal?: AbortSignal): Promise<ReloadResponse> {
+    return this.do<ReloadResponse>("POST", "/bundle/reload", {}, signal);
+  }
+
+  private async do<T>(
+    method: string,
+    path: string,
+    body: unknown,
+    signal?: AbortSignal,
+    requestIdHeader?: string,
+  ): Promise<T> {
+    const { data } = await this.doRaw<T>(
+      method,
+      path,
+      body,
+      signal,
+      requestIdHeader,
+    );
+    return data;
+  }
+
+  private doRaw<T>(
+    method: string,
+    path: string,
+    body: unknown,
+    signal?: AbortSignal,
+    requestIdHeader?: string,
+  ): Promise<{ status: number; data: T }> {
+    return new Promise((resolve, reject) => {
+      const payload = body != null ? JSON.stringify(body) : undefined;
+      const req = http.request(
+        {
+          socketPath: this.socketPath,
+          path,
+          method,
+          headers: {
+            "X-Request-ID": requestIdHeader ?? requestId(),
+            ...(payload
+              ? {
+                  "Content-Type": "application/json",
+                  "Content-Length": Buffer.byteLength(payload),
+                }
+              : {}),
+          },
+          timeout: this.timeoutMs,
+        },
+        (res) => {
+          const chunks: Buffer[] = [];
+          res.on("data", (c) => chunks.push(c));
+          res.on("end", () => {
+            const text = Buffer.concat(chunks).toString("utf8");
+            if (!text) {
+              reject(new Error(`${ErrTransport.message}: empty body`));
+              return;
+            }
+            try {
+              resolve({
+                status: res.statusCode ?? 0,
+                data: JSON.parse(text) as T,
+              });
+            } catch (e) {
+              reject(
+                new Error(
+                  `${ErrTransport.message}: decode: ${e instanceof Error ? e.message : e}`,
+                ),
+              );
+            }
+          });
+        },
+      );
+
+      req.on("timeout", () => {
+        req.destroy(new Error(`${ErrTransport.message}: timeout`));
+      });
+      req.on("error", (err) => {
+        reject(new Error(`${ErrTransport.message}: ${err.message}`));
+      });
+
+      if (signal) {
+        if (signal.aborted) {
+          req.destroy(new Error(`${ErrTransport.message}: aborted`));
+          return;
+        }
+        signal.addEventListener(
+          "abort",
+          () => {
+            req.destroy(new Error(`${ErrTransport.message}: aborted`));
+          },
+          { once: true },
+        );
+      }
+
+      if (payload) req.write(payload);
+      req.end();
+    });
+  }
+}

package/src/sidecar/process.ts

@@ -0,0 +1,145 @@
+import { access, constants } from "node:fs/promises";
+import fs from "node:fs";
+import path from "node:path";
+import { spawn, type ChildProcess } from "node:child_process";
+
+import type { MemoryConfig } from "../config.js";
+import { SidecarClient } from "./client.js";
+
+export class SidecarProcess {
+  private child: ChildProcess | null = null;
+  private readonly client: SidecarClient;
+
+  constructor(private readonly cfg: MemoryConfig) {
+    this.client = new SidecarClient(
+      cfg.socketPath,
+      Math.min(cfg.clientRequestTimeoutMs, 5_000),
+    );
+  }
+
+  getClient(): SidecarClient {
+    return this.client;
+  }
+
+  async resolveBinary(): Promise<string> {
+    const bin = this.cfg.tlmPath;
+    if (path.isAbsolute(bin)) {
+      await access(bin, constants.X_OK);
+      return bin;
+    }
+    // PATH lookup: spawn with shell on unix
+    return bin;
+  }
+
+  async spawn(): Promise<void> {
+    const bin = await this.resolveBinary().catch(() => {
+      throw new Error("memory: tlm binary not found");
+    });
+
+    if (this.cfg.socketPath) {
+      try {
+        fs.unlinkSync(this.cfg.socketPath);
+      } catch {
+        /* absent */
+      }
+    }
+
+    const args = [
+      "serve",
+      "--socket",
+      this.cfg.socketPath,
+      "--bundle-root",
+      this.cfg.bundleRoot,
+    ];
+
+    this.child = spawn(bin, args, {
+      stdio: "ignore",
+      detached: process.platform !== "win32",
+    });
+
+    this.child.on("error", (err) => {
+      console.error("[pi-memory] sidecar spawn error:", err.message);
+    });
+
+    this.child.unref?.();
+  }
+
+  async waitReady(signal?: AbortSignal): Promise<void> {
+    const deadline = Date.now() + this.cfg.sidecarReadyTimeoutMs;
+    let lastCompat = "";
+    let lastSub = "";
+
+    while (Date.now() < deadline) {
+      if (signal?.aborted) throw signal.reason ?? new Error("aborted");
+
+      try {
+        const h = await this.client.health(signal);
+        lastCompat = h.compatibility ?? "";
+        lastSub = h.error ? String(h.error.details?.sub_code ?? "") : "";
+
+        if (h.ready === true) return;
+        if (h.compatibility === "unknown") return;
+        if (h.compatibility === "incompatible") {
+          // keep polling until ceiling — supervisor classifies schema mismatch
+        }
+      } catch {
+        /* sidecar still starting */
+      }
+
+      await sleep(500, signal);
+    }
+
+    throw new Error(
+      `memory: sidecar ready ceiling exceeded` +
+        (lastCompat === "incompatible" && lastSub
+          ? ` (incompatible: ${lastSub})`
+          : ""),
+    );
+  }
+
+  async stop(): Promise<void> {
+    const child = this.child;
+    this.child = null;
+    if (!child?.pid) return;
+
+    if (process.platform === "win32") {
+      spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"]);
+    } else {
+      try {
+        process.kill(-child.pid, "SIGTERM");
+      } catch {
+        try {
+          child.kill("SIGTERM");
+        } catch {
+          /* already dead */
+        }
+      }
+    }
+
+    await new Promise<void>((resolve) => {
+      const t = setTimeout(resolve, 2_000);
+      child.on("exit", () => {
+        clearTimeout(t);
+        resolve();
+      });
+    });
+  }
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error("aborted"));
+      return;
+    }
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(t);
+        reject(signal.reason ?? new Error("aborted"));
+      },
+      { once: true },
+    );
+  });
+}

package/src/tools/memoryAppend.ts

@@ -0,0 +1,113 @@
+import fs from "node:fs/promises";
+import { open } from "node:fs/promises";
+import path from "node:path";
+
+import type { ToolResult } from "../types.js";
+
+export const MEMORY_APPEND_NAME = "memory_append";
+
+export const MEMORY_APPEND_DESCRIPTION =
+  "Append new entries to MEMORY.md. Use this instead of file_write or file_edit for memory updates. " +
+  "Writes are append-only with a simple lock to avoid concurrent clobber.";
+
+export const MEMORY_APPEND_PROMPT_SNIPPET = "Append durable notes to MEMORY.md";
+
+export const MEMORY_APPEND_PROMPT_GUIDELINES = [
+  "Use memory_append to persist user preferences or facts the user explicitly asked to remember — not for transient task state.",
+] as const;
+
+export const MEMORY_APPEND_PARAMETERS = {
+  type: "object",
+  properties: {
+    content: {
+      type: "string",
+      description:
+        "New entries to append (markdown bullet points). Write in English by default.",
+    },
+  },
+  required: ["content"],
+} as const;
+
+const LOCK_RETRIES = 50;
+const LOCK_DELAY_MS = 20;
+
+async function withAppendLock<T>(
+  lockPath: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  let handle;
+  for (let i = 0; i < LOCK_RETRIES; i++) {
+    try {
+      handle = await open(lockPath, "wx");
+      break;
+    } catch {
+      await new Promise((r) => setTimeout(r, LOCK_DELAY_MS));
+    }
+  }
+  if (!handle) {
+    throw new Error("could not acquire MEMORY.md append lock");
+  }
+  try {
+    return await fn();
+  } finally {
+    await handle.close();
+    await fs.unlink(lockPath).catch(() => {});
+  }
+}
+
+export async function appendToMemoryMd(
+  memoryMdPath: string,
+  content: string,
+): Promise<void> {
+  const trimmed = content.trim();
+  if (!trimmed) {
+    throw new Error("content must not be empty");
+  }
+  await fs.mkdir(path.dirname(memoryMdPath), { recursive: true, mode: 0o700 });
+  const lockPath = `${memoryMdPath}.append.lock`;
+  const block = content.endsWith("\n") ? content : `${content}\n`;
+  await withAppendLock(lockPath, async () => {
+    await fs.appendFile(memoryMdPath, block, { encoding: "utf8", mode: 0o600 });
+  });
+}
+
+export class MemoryAppendTool {
+  constructor(private readonly memoryMdPath: string) {}
+
+  info() {
+    return {
+      name: MEMORY_APPEND_NAME,
+      description: MEMORY_APPEND_DESCRIPTION,
+      parameters: MEMORY_APPEND_PARAMETERS,
+    };
+  }
+
+  async run(argsJson: string): Promise<ToolResult> {
+    let raw: Record<string, unknown>;
+    try {
+      raw = JSON.parse(argsJson) as Record<string, unknown>;
+    } catch (e) {
+      return {
+        content: `invalid arguments: ${e instanceof Error ? e.message : e}`,
+        isError: true,
+      };
+    }
+    const content = typeof raw.content === "string" ? raw.content : "";
+    if (!content.trim()) {
+      return { content: "content must not be empty", isError: true };
+    }
+    try {
+      await appendToMemoryMd(this.memoryMdPath, content);
+      return { content: `appended to ${this.memoryMdPath}` };
+    } catch (e) {
+      return {
+        content: `error appending: ${e instanceof Error ? e.message : e}`,
+        isError: true,
+      };
+    }
+  }
+}
+
+export function createMemoryAppendTool(memoryMdPath: string): MemoryAppendTool {
+  return new MemoryAppendTool(memoryMdPath);
+}