@hexis-ai/engram-server 0.3.0 → 0.4.0

package/dist/openapi.js

@@ -11,6 +11,11 @@
  *
  * `info.version` is the API version (the `/v1` surface), not the npm package
  * version — it changes only when the wire contract changes.
+ *
+ * The human-readable strings (`summary`, `description`, response and
+ * parameter descriptions) are written in Japanese — the API reference is
+ * read by the Hexis team. Identifiers, paths, schema names and status
+ * codes stay as-is.
  */
 import { z } from "zod";
 import { createWorkspaceSchema, eventBatchSchema, issueKeySchema, personCreateSchema, personUpdateSchema, searchRequestSchema, sessionInitSchema, } from "./schemas";
@@ -37,212 +42,276 @@ const res = (description) => ({ description });
 /** Default security: a workspace API key. `/admin/v1` paths override this. */
 const workspaceAuth = [{ workspaceKey: [] }];
 const adminAuth = [{ adminToken: [] }];
-const limitParam = queryParam("limit", "Page size; clamped server-side.", {
+// ---------------------------------------------------------------------
+// Tags — group the rendered reference (Scalar, on monet-web /docs/engram)
+// into a per-domain sidebar instead of one flat list of 19 operations.
+//
+//   The tag *definitions* (sidebar order + Japanese descriptions) live
+//   in TAG_DEFS; `tagged()` stamps a tag onto every operation in a
+//   path-item, so each path in buildPaths() declares its tag once,
+//   inline. test/openapi.test.ts guards that no operation slips through
+//   untagged and no operation references an undefined tag.
+// ---------------------------------------------------------------------
+/** Every tag, in sidebar order, with a Japanese description. */
+const TAG_DEFS = [
+    { name: "Me", description: "識別プローブ" },
+    { name: "Sessions", description: "セッションの作成・取得・イベント追加" },
+    { name: "Search", description: "ワークスペースコーパスへのスコアリング検索" },
+    { name: "Persons", description: "person の作成・更新・検索" },
+    {
+        name: "Workspaces (admin)",
+        description: "ワークスペースの管理（管理者トークン必須）",
+    },
+    {
+        name: "API Keys (admin)",
+        description: "ワークスペース API キーの発行・無効化（管理者トークン必須）",
+    },
+];
+/**
+ * Stamp `tag` onto every operation in a path-item. The path declares its
+ * tag once — `tagged("Sessions", { post: {…}, get: {…} })` — rather than
+ * repeating `tags` on each method.
+ */
+function tagged(tag, pathItem) {
+    const out = {};
+    for (const [method, op] of Object.entries(pathItem)) {
+        out[method] = { ...op, tags: [tag] };
+    }
+    return out;
+}
+const limitParam = queryParam("limit", "ページサイズ。サーバー側で上限が適用される。", {
     type: "integer",
     minimum: 1,
 });
-const channelParam = queryParam("channel", "Filter by session channel.");
+const channelParam = queryParam("channel", "セッションのチャンネルで絞り込む。");
 function buildPaths() {
     return {
-        "/v1/me": {
+        "/v1/me": tagged("Me", {
             get: {
-                summary: "Identity probe — the workspace the caller's key resolves to.",
-                responses: { "200": res("workspace id"), "401": res("unauthorized") },
+                summary: "識別プローブ — 呼び出し元のキーが解決するワークスペースを返す。",
+                responses: {
+                    "200": res("ワークスペース id"),
+                    "401": res("認証エラー"),
+                },
             },
-        },
-        "/v1/sessions": {
+        }),
+        "/v1/sessions": tagged("Sessions", {
             post: {
-                summary: "Create a session.",
+                summary: "セッションを作成する。",
                 requestBody: jsonBody("SessionInit"),
                 responses: {
-                    "200": res("created session id"),
-                    "400": res("invalid body"),
-                    "401": res("unauthorized"),
+                    "200": res("作成されたセッション id"),
+                    "400": res("リクエストボディが不正"),
+                    "401": res("認証エラー"),
                 },
             },
             get: {
-                summary: "List recent sessions plus their persons map.",
+                summary: "最近のセッション一覧と、それに紐づく persons マップを取得する。",
                 parameters: [limitParam, channelParam],
-                responses: { "200": res("session list envelope"), "401": res("unauthorized") },
+                responses: {
+                    "200": res("セッション一覧のエンベロープ"),
+                    "401": res("認証エラー"),
+                },
             },
-        },
-        "/v1/sessions/{id}": {
+        }),
+        "/v1/sessions/{id}": tagged("Sessions", {
             get: {
-                summary: "Fetch one session plus its persons map.",
-                parameters: [pathParam("id", "Session id.")],
+                summary: "単一セッションと、それに紐づく persons マップを取得する。",
+                parameters: [pathParam("id", "セッション id。")],
                 responses: {
-                    "200": res("session envelope"),
-                    "404": res("session not found"),
-                    "401": res("unauthorized"),
+                    "200": res("セッションのエンベロープ"),
+                    "404": res("セッションが見つからない"),
+                    "401": res("認証エラー"),
                 },
             },
-        },
-        "/v1/sessions/{id}/events": {
+        }),
+        "/v1/sessions/{id}/events": tagged("Sessions", {
             post: {
-                summary: "Append events to a session.",
-                parameters: [pathParam("id", "Session id.")],
+                summary: "セッションにイベントを追加する。",
+                parameters: [pathParam("id", "セッション id。")],
                 requestBody: jsonBody("EventBatch"),
                 responses: {
-                    "204": res("appended"),
-                    "400": res("invalid body"),
-                    "404": res("session not found"),
-                    "401": res("unauthorized"),
+                    "204": res("追加完了"),
+                    "400": res("リクエストボディが不正"),
+                    "404": res("セッションが見つからない"),
+                    "401": res("認証エラー"),
                 },
             },
-        },
-        "/v1/search": {
+            get: {
+                summary: "セッションの生イベントログを seq 順で取得する（fold せず、各イベントの時刻つき）。",
+                parameters: [pathParam("id", "セッション id。")],
+                responses: {
+                    "200": res("イベントログ"),
+                    "404": res("セッションが見つからない"),
+                    "401": res("認証エラー"),
+                },
+            },
+        }),
+        "/v1/search": tagged("Search", {
             post: {
-                summary: "Score the workspace corpus against a query session.",
+                summary: "クエリセッションに対してワークスペースのコーパスをスコアリングする。",
                 requestBody: jsonBody("SearchRequest"),
                 responses: {
-                    "200": res("scored results plus persons map"),
-                    "400": res("invalid body"),
-                    "404": res("query session not found"),
-                    "401": res("unauthorized"),
+                    "200": res("スコアリング結果と persons マップ"),
+                    "400": res("リクエストボディが不正"),
+                    "404": res("クエリセッションが見つからない"),
+                    "401": res("認証エラー"),
                 },
             },
-        },
-        "/v1/persons": {
+        }),
+        "/v1/persons": tagged("Persons", {
             post: {
-                summary: "Create a person (server allocates the id).",
+                summary: "person を作成する（id はサーバーが採番する）。",
                 requestBody: jsonBody("PersonCreate"),
                 responses: {
-                    "201": res("created person"),
-                    "400": res("invalid body"),
-                    "401": res("unauthorized"),
+                    "201": res("作成された person"),
+                    "400": res("リクエストボディが不正"),
+                    "401": res("認証エラー"),
                 },
             },
             get: {
-                summary: "List or free-text search persons.",
-                parameters: [limitParam, queryParam("q", "Free-text query over id + display_name.")],
-                responses: { "200": res("person list"), "401": res("unauthorized") },
+                summary: "person の一覧取得、またはフリーテキスト検索を行う。",
+                parameters: [
+                    limitParam,
+                    queryParam("q", "id と display_name に対するフリーテキストクエリ。"),
+                ],
+                responses: {
+                    "200": res("person 一覧"),
+                    "401": res("認証エラー"),
+                },
             },
-        },
-        "/v1/persons/{id}": {
+        }),
+        "/v1/persons/{id}": tagged("Persons", {
             put: {
-                summary: "Upsert a person at a caller-supplied id.",
-                parameters: [pathParam("id", "Person id.")],
+                summary: "呼び出し元が指定した id で person を upsert する。",
+                parameters: [pathParam("id", "person id。")],
                 requestBody: jsonBody("PersonCreate"),
                 responses: {
-                    "200": res("upserted person"),
-                    "400": res("invalid body"),
-                    "401": res("unauthorized"),
+                    "200": res("upsert された person"),
+                    "400": res("リクエストボディが不正"),
+                    "401": res("認証エラー"),
                 },
             },
             patch: {
-                summary: "Patch a person's profile fields.",
-                parameters: [pathParam("id", "Person id.")],
+                summary: "person のプロフィール項目を部分更新する。",
+                parameters: [pathParam("id", "person id。")],
                 requestBody: jsonBody("PersonUpdate"),
                 responses: {
-                    "200": res("updated person"),
-                    "400": res("invalid body"),
-                    "404": res("person not found"),
-                    "401": res("unauthorized"),
+                    "200": res("更新された person"),
+                    "400": res("リクエストボディが不正"),
+                    "404": res("person が見つからない"),
+                    "401": res("認証エラー"),
                 },
             },
             get: {
-                summary: "Fetch one person.",
-                parameters: [pathParam("id", "Person id.")],
+                summary: "単一の person を取得する。",
+                parameters: [pathParam("id", "person id。")],
                 responses: {
                     "200": res("person"),
-                    "404": res("person not found"),
-                    "401": res("unauthorized"),
+                    "404": res("person が見つからない"),
+                    "401": res("認証エラー"),
                 },
             },
-        },
-        "/v1/persons/{id}/sessions": {
+        }),
+        "/v1/persons/{id}/sessions": tagged("Persons", {
             get: {
-                summary: "Sessions this person participates in (or can view).",
+                summary: "この person が参加している（または閲覧可能な）セッション一覧。",
                 parameters: [
-                    pathParam("id", "Person id."),
+                    pathParam("id", "person id。"),
                     limitParam,
                     channelParam,
-                    queryParam("scope", "`participant` (default) or `viewable`.", {
+                    queryParam("scope", "`participant`（デフォルト）または `viewable`。", {
                         type: "string",
                         enum: ["participant", "viewable"],
                     }),
                 ],
-                responses: { "200": res("session list envelope"), "401": res("unauthorized") },
+                responses: {
+                    "200": res("セッション一覧のエンベロープ"),
+                    "401": res("認証エラー"),
+                },
             },
-        },
-        "/admin/v1/workspaces": {
+        }),
+        "/admin/v1/workspaces": tagged("Workspaces (admin)", {
             post: {
-                summary: "Create a workspace (and, by default, an initial key).",
+                summary: "ワークスペースを作成する（デフォルトで初期キーも発行する）。",
                 security: adminAuth,
                 requestBody: jsonBody("CreateWorkspace"),
                 responses: {
-                    "200": res("workspace, plus key unless issueKey=false"),
-                    "400": res("invalid body or workspace id"),
-                    "401": res("unauthorized"),
+                    "200": res("ワークスペース（issueKey=false でない限りキーも含む）"),
+                    "400": res("リクエストボディまたはワークスペース id が不正"),
+                    "401": res("認証エラー"),
                 },
             },
             get: {
-                summary: "List all workspaces.",
+                summary: "全ワークスペースを一覧取得する。",
                 security: adminAuth,
-                responses: { "200": res("workspace list"), "401": res("unauthorized") },
+                responses: {
+                    "200": res("ワークスペース一覧"),
+                    "401": res("認証エラー"),
+                },
             },
-        },
-        "/admin/v1/workspaces/{id}": {
+        }),
+        "/admin/v1/workspaces/{id}": tagged("Workspaces (admin)", {
             get: {
-                summary: "Fetch one workspace.",
+                summary: "単一のワークスペースを取得する。",
                 security: adminAuth,
-                parameters: [pathParam("id", "Workspace id.")],
+                parameters: [pathParam("id", "ワークスペース id。")],
                 responses: {
-                    "200": res("workspace"),
-                    "404": res("workspace not found"),
-                    "401": res("unauthorized"),
+                    "200": res("ワークスペース"),
+                    "404": res("ワークスペースが見つからない"),
+                    "401": res("認証エラー"),
                 },
             },
             delete: {
-                summary: "Delete a workspace (cascades to keys, sessions, events).",
+                summary: "ワークスペースを削除する（キー・セッション・イベントにカスケードする）。",
                 security: adminAuth,
-                parameters: [pathParam("id", "Workspace id.")],
+                parameters: [pathParam("id", "ワークスペース id。")],
                 responses: {
-                    "204": res("deleted"),
-                    "404": res("workspace not found"),
-                    "401": res("unauthorized"),
+                    "204": res("削除完了"),
+                    "404": res("ワークスペースが見つからない"),
+                    "401": res("認証エラー"),
                 },
             },
-        },
-        "/admin/v1/workspaces/{id}/keys": {
+        }),
+        "/admin/v1/workspaces/{id}/keys": tagged("API Keys (admin)", {
             post: {
-                summary: "Issue a new API key for a workspace.",
+                summary: "ワークスペースに新しい API キーを発行する。",
                 security: adminAuth,
-                parameters: [pathParam("id", "Workspace id.")],
+                parameters: [pathParam("id", "ワークスペース id。")],
                 requestBody: jsonBody("IssueKey", false),
                 responses: {
-                    "200": res("issued key (raw key returned once)"),
-                    "400": res("invalid body"),
-                    "404": res("workspace not found"),
-                    "401": res("unauthorized"),
+                    "200": res("発行されたキー（生のキーは一度のみ返却）"),
+                    "400": res("リクエストボディが不正"),
+                    "404": res("ワークスペースが見つからない"),
+                    "401": res("認証エラー"),
                 },
             },
             get: {
-                summary: "List a workspace's API keys (hashes only).",
+                summary: "ワークスペースの API キー一覧を取得する（ハッシュのみ）。",
                 security: adminAuth,
-                parameters: [pathParam("id", "Workspace id.")],
+                parameters: [pathParam("id", "ワークスペース id。")],
                 responses: {
-                    "200": res("key list"),
-                    "404": res("workspace not found"),
-                    "401": res("unauthorized"),
+                    "200": res("キー一覧"),
+                    "404": res("ワークスペースが見つからない"),
+                    "401": res("認証エラー"),
                 },
             },
-        },
-        "/admin/v1/workspaces/{id}/keys/{keyId}": {
+        }),
+        "/admin/v1/workspaces/{id}/keys/{keyId}": tagged("API Keys (admin)", {
             delete: {
-                summary: "Revoke an API key.",
+                summary: "API キーを無効化する。",
                 security: adminAuth,
                 parameters: [
-                    pathParam("id", "Workspace id."),
-                    pathParam("keyId", "Key id."),
+                    pathParam("id", "ワークスペース id。"),
+                    pathParam("keyId", "キー id。"),
                 ],
                 responses: {
-                    "204": res("revoked (idempotent)"),
-                    "404": res("key not found"),
-                    "401": res("unauthorized"),
+                    "204": res("無効化完了（冪等）"),
+                    "404": res("キーが見つからない"),
+                    "401": res("認証エラー"),
                 },
             },
-        },
+        }),
     };
 }
 /**
@@ -256,12 +325,14 @@ export function buildOpenApiDocument() {
         info: {
             title: "engram-server",
             version: "1.0",
-            description: "Cross-session retrieval for AI agents. Request bodies are derived " +
-                "from the server's Zod schemas (src/schemas.ts); response schemas " +
-                "are described by status only for now and are a planned follow-up.",
+            description: "AI エージェント向けのクロスセッション検索。リクエストボディは" +
+                "サーバーの Zod スキーマ（src/schemas.ts）から導出される。" +
+                "レスポンススキーマは現状ステータスコードのみの記述で、" +
+                "本格的な記述は今後対応予定。",
         },
+        tags: TAG_DEFS.map((t) => ({ ...t })),
         servers: [
-            { url: "/", description: "relative to the deployed engram-server" },
+            { url: "/", description: "デプロイされた engram-server からの相対パス" },
         ],
         security: workspaceAuth,
         components: {
@@ -269,13 +340,14 @@ export function buildOpenApiDocument() {
                 workspaceKey: {
                     type: "http",
                     scheme: "bearer",
-                    description: "Workspace API key (`eng_…`). Also accepted as the `X-Api-Key` header.",
+                    description: "ワークスペース API キー（`eng_…`）。`X-Api-Key` ヘッダーでも受け付ける。",
                 },
                 adminToken: {
                     type: "apiKey",
                     in: "header",
                     name: "X-Admin-Token",
-                    description: "Platform admin token for `/admin/v1/*`. Also accepted as `Authorization: Bearer`.",
+                    description: "`/admin/v1/*` 用のプラットフォーム管理者トークン。" +
+                        "`Authorization: Bearer` でも受け付ける。",
                 },
             },
             schemas: {

package/dist/routes/sessions.d.ts

@@ -3,9 +3,10 @@ import type { Env } from "../context";
 import { type RouteConfig } from "./helpers";
 /**
  * Session routes. Mount under `/v1`:
- *   POST /v1/sessions            create a session
- *   POST /v1/sessions/:id/events append events
- *   GET  /v1/sessions/:id        fetch one session + its persons map
- *   GET  /v1/sessions            list recent sessions + persons map
+ *   POST /v1/sessions             create a session
+ *   POST /v1/sessions/:id/events  append events
+ *   GET  /v1/sessions/:id         fetch one session + its persons map
+ *   GET  /v1/sessions/:id/events  fetch the raw, ordered event log
+ *   GET  /v1/sessions             list recent sessions + persons map
  */
 export declare function sessionsRoutes(cfg: RouteConfig): Hono<Env>;

package/dist/routes/sessions.js

@@ -3,10 +3,11 @@ import { eventBatchSchema, parseJsonBody, sessionInitSchema } from "../schemas";
 import { clampLimit, resolvePersonMap } from "./helpers";
 /**
  * Session routes. Mount under `/v1`:
- *   POST /v1/sessions            create a session
- *   POST /v1/sessions/:id/events append events
- *   GET  /v1/sessions/:id        fetch one session + its persons map
- *   GET  /v1/sessions            list recent sessions + persons map
+ *   POST /v1/sessions             create a session
+ *   POST /v1/sessions/:id/events  append events
+ *   GET  /v1/sessions/:id         fetch one session + its persons map
+ *   GET  /v1/sessions/:id/events  fetch the raw, ordered event log
+ *   GET  /v1/sessions             list recent sessions + persons map
  */
 export function sessionsRoutes(cfg) {
     const app = new Hono();
@@ -40,6 +41,13 @@ export function sessionsRoutes(cfg) {
         const persons = await resolvePersonMap(c.var.ctx.storage, [s]);
         return c.json({ session: s, persons });
     });
+    app.get("/sessions/:id/events", async (c) => {
+        const id = c.req.param("id");
+        const events = await c.var.ctx.storage.getSessionEvents(id);
+        if (events === null)
+            return c.json({ error: "session_not_found" }, 404);
+        return c.json({ events });
+    });
     app.get("/sessions", async (c) => {
         const limit = clampLimit(c, cfg.defaultListLimit, cfg.maxListLimit);
         const channel = c.req.query("channel") || undefined;

package/dist/server.js

@@ -53,6 +53,7 @@ export function createServer(opts) {
             sessions: "POST/GET /v1/sessions",
             sessionById: "GET /v1/sessions/:id",
             events: "POST /v1/sessions/:id/events",
+            sessionEvents: "GET /v1/sessions/:id/events",
             search: "POST /v1/search",
             persons: "POST/GET /v1/persons",
             personById: "GET/PUT/PATCH /v1/persons/:id",

package/dist/storage.d.ts

@@ -18,6 +18,14 @@ export interface StorageAdapter {
     appendEvents(sessionId: string, events: SessionEvent[]): Promise<void>;
     /** Materialize a session (events folded into Session shape). */
     getSession(sessionId: string): Promise<Session | null>;
+    /**
+     * Raw event log for a session, ordered by `seq`. Unlike `getSession`,
+     * this does not fold events — callers get per-event timestamps and the
+     * participant / title / end events as recorded. Returns `null` when the
+     * session doesn't exist (distinct from an existing session with no
+     * events, which returns `[]`).
+     */
+    getSessionEvents(sessionId: string): Promise<SessionEvent[] | null>;
     /** List recent sessions. */
     listSessions(opts: {
         limit: number;