@hexis-ai/engram-server 0.1.1 → 0.1.4

package/dist/adapters/postgres.d.ts

@@ -8,6 +8,8 @@ import { type StorageAdapter } from "../storage";
  */
 export interface SqlClient {
     <T = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+    /** Raw query for DDL / multi-statement strings. */
+    unsafe: (query: string) => Promise<unknown>;
 }
 export interface PostgresAdapterOptions {
     /** Workspace scope baked into every row. Required for multi-tenant isolation. */
@@ -20,9 +22,7 @@ export declare class PostgresAdapter implements StorageAdapter {
     constructor(opts: PostgresAdapterOptions);
     /**
      * Create the schema. Call once at boot. Safe to invoke repeatedly.
-     * Postgres pg-tag template clients accept multi-statement strings via
-     * `sql.unsafe()` in the real driver; for portability we issue them
-     * separately so any tagged-template impl works.
+     * Uses `sql.unsafe()` to ship the multi-statement DDL as a single batch.
      */
     ensureSchema(): Promise<void>;
     createSession(init: SessionInit & {

package/dist/adapters/postgres.js

@@ -34,16 +34,10 @@ export class PostgresAdapter {
     }
     /**
      * Create the schema. Call once at boot. Safe to invoke repeatedly.
-     * Postgres pg-tag template clients accept multi-statement strings via
-     * `sql.unsafe()` in the real driver; for portability we issue them
-     * separately so any tagged-template impl works.
+     * Uses `sql.unsafe()` to ship the multi-statement DDL as a single batch.
      */
     async ensureSchema() {
-        const stmts = SCHEMA_SQL.split(/;\s*\n/).map((s) => s.trim()).filter(Boolean);
-        for (const stmt of stmts) {
-            // Tagged-template invocation with no interpolations.
-            await this.sql([stmt + ";"]);
-        }
+        await this.sql.unsafe(SCHEMA_SQL);
     }
     async createSession(init) {
         await this.sql `
@@ -63,6 +57,10 @@ export class PostgresAdapter {
         if (events.length === 0)
             return;
         for (const ev of events) {
+            // Pass the event object directly: postgres serializes JS objects as
+            // JSON for jsonb columns. Doing JSON.stringify ourselves then casting
+            // ::jsonb produced a doubly-encoded string value (jsonb containing
+            // a string instead of an object).
             await this.sql `
         INSERT INTO engram_events (workspace_id, session_id, seq, type, at, payload)
         VALUES (
@@ -71,7 +69,7 @@ export class PostgresAdapter {
           ${ev.seq},
           ${ev.type},
           ${ev.at},
-          ${JSON.stringify(ev)}::jsonb
+          ${ev}
         )
         ON CONFLICT (workspace_id, session_id, seq) DO NOTHING
       `;

package/dist/logger.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Structured logging for engram-server.
+ *
+ * Emits one JSON object per line so Cloud Logging picks it up natively:
+ * {severity, message, ...fields}. Severity matches Google's "LogSeverity"
+ * enum names (DEBUG, INFO, WARNING, ERROR) so log explorer auto-classifies.
+ *
+ * Keep this dependency-free; structured logging is a small enough surface
+ * that pulling pino/winston isn't worth the dep weight.
+ */
+export interface LogFields {
+    request_id?: string;
+    [key: string]: unknown;
+}
+export declare const log: {
+    debug: (message: string, fields?: LogFields) => void;
+    info: (message: string, fields?: LogFields) => void;
+    warn: (message: string, fields?: LogFields) => void;
+    error: (message: string, fields?: LogFields) => void;
+};
+/**
+ * Generate a short request id when no upstream `x-request-id` is supplied.
+ * Not cryptographically strong — just enough to correlate one container's
+ * log lines for a single request.
+ */
+export declare function newRequestId(): string;

package/dist/logger.js

@@ -0,0 +1,33 @@
+/**
+ * Structured logging for engram-server.
+ *
+ * Emits one JSON object per line so Cloud Logging picks it up natively:
+ * {severity, message, ...fields}. Severity matches Google's "LogSeverity"
+ * enum names (DEBUG, INFO, WARNING, ERROR) so log explorer auto-classifies.
+ *
+ * Keep this dependency-free; structured logging is a small enough surface
+ * that pulling pino/winston isn't worth the dep weight.
+ */
+function emit(severity, message, fields) {
+    const line = JSON.stringify({ severity, message, ...fields });
+    if (severity === "ERROR")
+        console.error(line);
+    else if (severity === "WARNING")
+        console.warn(line);
+    else
+        console.log(line);
+}
+export const log = {
+    debug: (message, fields) => emit("DEBUG", message, fields),
+    info: (message, fields) => emit("INFO", message, fields),
+    warn: (message, fields) => emit("WARNING", message, fields),
+    error: (message, fields) => emit("ERROR", message, fields),
+};
+/**
+ * Generate a short request id when no upstream `x-request-id` is supplied.
+ * Not cryptographically strong — just enough to correlate one container's
+ * log lines for a single request.
+ */
+export function newRequestId() {
+    return Math.random().toString(36).slice(2, 12);
+}

package/dist/main.d.ts

@@ -0,0 +1,5 @@
+declare const _default: {
+    port: number;
+    fetch: (request: Request, Env?: unknown, executionCtx?: import("hono").ExecutionContext) => Response | Promise<Response>;
+};
+export default _default;

package/dist/main.js

@@ -0,0 +1,53 @@
+/**
+ * Production entrypoint.
+ *
+ * Reads configuration from environment:
+ *
+ *   ENGRAM_API_KEY      required        single bearer key. Multi-tenant deploys
+ *                                       should swap this for a real key store.
+ *   PORT                default 8080    HTTP listen port.
+ *   DATABASE_URL        optional        if set, uses PostgresAdapter; otherwise
+ *                                       falls back to InMemoryAdapter (NOT
+ *                                       durable across restarts).
+ *   DATABASE_SOCKET_PATH optional       Cloud SQL Auth Proxy unix socket dir.
+ *                                       When set, postgres connects via
+ *                                       `host=<DATABASE_SOCKET_PATH>`.
+ *   ENGRAM_WORKSPACE_ID default "default"
+ *                                       workspace id baked into the postgres
+ *                                       adapter for this single-tenant deploy.
+ */
+import { createServer } from "./server";
+import { InMemoryAdapter } from "./adapters/memory";
+import { PostgresAdapter } from "./adapters/postgres";
+const PORT = Number(process.env.PORT ?? 8080);
+const API_KEY = process.env.ENGRAM_API_KEY;
+const WORKSPACE_ID = process.env.ENGRAM_WORKSPACE_ID ?? "default";
+const DATABASE_URL = process.env.DATABASE_URL;
+const DATABASE_SOCKET_PATH = process.env.DATABASE_SOCKET_PATH;
+if (!API_KEY) {
+    console.error("[engram-server] ENGRAM_API_KEY is required");
+    process.exit(1);
+}
+const storage = await (async () => {
+    if (!DATABASE_URL) {
+        console.warn("[engram-server] DATABASE_URL not set — using InMemoryAdapter (data is volatile)");
+        return new InMemoryAdapter();
+    }
+    // postgres is a peer dep so we import it lazily; absence is a hard error here.
+    const { default: postgres } = await import("postgres");
+    const sql = DATABASE_SOCKET_PATH
+        ? postgres(DATABASE_URL, { host: DATABASE_SOCKET_PATH })
+        : postgres(DATABASE_URL);
+    const adapter = new PostgresAdapter({
+        workspaceId: WORKSPACE_ID,
+        sql: sql,
+    });
+    await adapter.ensureSchema();
+    console.log(`[engram-server] postgres adapter ready (workspace=${WORKSPACE_ID})`);
+    return adapter;
+})();
+const app = createServer({
+    auth: (key) => (key === API_KEY ? { workspaceId: WORKSPACE_ID, storage } : null),
+});
+console.log(`[engram-server] listening on :${PORT}`);
+export default { port: PORT, fetch: app.fetch };

package/dist/server.d.ts

@@ -29,6 +29,7 @@ export interface CreateServerOptions {
 interface Env {
     Variables: {
         ctx: WorkspaceContext;
+        request_id: string;
     };
 }
 export declare function createServer(opts: CreateServerOptions): Hono<Env>;

package/dist/server.js

@@ -1,16 +1,64 @@
 import { Hono } from "hono";
 import { buildIndex, search, } from "@hexis-ai/engram-core";
+import { log, newRequestId } from "./logger";
 export function createServer(opts) {
     const newId = opts.newSessionId ?? (() => crypto.randomUUID());
     const defaultLimit = opts.defaultListLimit ?? 100;
     const maxLimit = opts.maxListLimit ?? 500;
     const app = new Hono();
+    // Request id + access log middleware. Runs for every route.
+    app.use("*", async (c, next) => {
+        const rid = c.req.header("x-request-id") ?? newRequestId();
+        c.set("request_id", rid);
+        c.header("x-request-id", rid);
+        const start = Date.now();
+        let status = 500;
+        try {
+            await next();
+            status = c.res.status;
+        }
+        finally {
+            log.info("request", {
+                request_id: rid,
+                method: c.req.method,
+                path: c.req.path,
+                status,
+                duration_ms: Date.now() - start,
+            });
+        }
+    });
+    app.onError((err, c) => {
+        log.error("unhandled", {
+            request_id: c.var.request_id,
+            path: c.req.path,
+            error: err instanceof Error ? err.message : String(err),
+            stack: err instanceof Error ? err.stack : undefined,
+        });
+        return c.json({ error: "internal_error" }, 500);
+    });
+    // Unauthenticated service info. Useful for browser sanity checks and
+    // health probes (Cloud Run, k8s, uptime monitors).
+    app.get("/", (c) => c.json({
+        service: "@hexis-ai/engram-server",
+        ok: true,
+        routes: {
+            sessions: "POST/GET /v1/sessions",
+            sessionById: "GET /v1/sessions/:id",
+            events: "POST /v1/sessions/:id/events",
+            search: "POST /v1/search",
+        },
+    }));
+    app.get("/healthz", (c) => c.json({ ok: true }));
     app.use("/v1/*", async (c, next) => {
-        const auth = c.req.header("authorization");
-        const m = auth?.match(/^Bearer\s+(.+)$/i);
-        if (!m)
+        // Prefer X-Api-Key so callers can use the Authorization header for
+        // platform-level auth (Cloud Run IAM with an ID token, for example)
+        // without collision. Falls back to Authorization: Bearer <key> for
+        // existing clients.
+        const apiKey = c.req.header("x-api-key") ??
+            c.req.header("authorization")?.match(/^Bearer\s+(.+)$/i)?.[1];
+        if (!apiKey)
             return c.json({ error: "unauthorized" }, 401);
-        const ctx = await opts.auth(m[1]);
+        const ctx = await opts.auth(apiKey);
         if (!ctx)
             return c.json({ error: "unauthorized" }, 401);
         c.set("ctx", ctx);

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@hexis-ai/engram-server",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Engram server: ingest agent session events, persist via a pluggable adapter, expose search.",
   "keywords": ["engram", "agents", "search", "hono", "postgres", "server"],
-  "homepage": "https://github.com/hexis-ai/engram#readme",
+  "homepage": "https://github.com/hexis-ltd/engram#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/hexis-ai/engram.git",
+    "url": "git+https://github.com/hexis-ltd/engram.git",
     "directory": "packages/server"
   },
-  "bugs": "https://github.com/hexis-ai/engram/issues",
+  "bugs": "https://github.com/hexis-ltd/engram/issues",
   "author": "hexis ltd.",
   "license": "MIT",
   "type": "module",
@@ -41,8 +41,8 @@
     "dev": "bun --hot src/dev.ts"
   },
   "dependencies": {
-    "@hexis-ai/engram-core": "^0.1.1",
-    "@hexis-ai/engram-sdk": "^0.1.1",
+    "@hexis-ai/engram-core": "^0.1.4",
+    "@hexis-ai/engram-sdk": "^0.1.4",
     "hono": "^4.6.0"
   },
   "peerDependencies": {
@@ -51,6 +51,9 @@
   "peerDependenciesMeta": {
     "postgres": { "optional": true }
   },
+  "devDependencies": {
+    "postgres": "^3.4.0"
+  },
   "publishConfig": {
     "access": "public"
   }