neotoma 0.8.0 → 0.9.1

package/README.md

@@ -23,6 +23,8 @@ Neotoma is a deterministic state layer for AI agents. It stores structured recor
 
 Not retrieval memory (RAG, vector search, semantic lookup). Neotoma enforces deterministic state evolution: same observations always produce the same entity state, regardless of when or in what order they are processed.
 
+The **Inspector** — Neotoma's visual control plane for browsing the entity graph, timeline, schema editor, and agent attribution — is bundled and served at `/inspector` by default when the server starts. No separate build or configuration required. Override with `NEOTOMA_INSPECTOR_DISABLE`, `NEOTOMA_PUBLIC_INSPECTOR_URL`, `NEOTOMA_INSPECTOR_STATIC_DIR`, or `NEOTOMA_INSPECTOR_BASE_PATH` (see `.env.example`).
+
 ## Architecture
 
 ```mermaid
@@ -186,6 +188,7 @@ Neotoma stores user data and requires secure configuration.
 
 ```bash
 npm run dev          # MCP server (stdio)
+npm run dev:mcp:dev-shim  # stable stdio shim for MCP source iteration
 npm run dev:ui       # Frontend
 npm run dev:server   # API only (MCP at /mcp)
 npm run dev:full     # API + UI + build watch
@@ -216,7 +219,9 @@ Neotoma exposes state via MCP. Local storage only in preview. Local built-in aut
 
 **Setup guides:** [Cursor](https://neotoma.io/neotoma-with-cursor) · [Claude Code](https://neotoma.io/neotoma-with-claude-code) · [Claude](https://neotoma.io/neotoma-with-claude) · [ChatGPT](https://neotoma.io/neotoma-with-chatgpt) · [Codex](https://neotoma.io/neotoma-with-codex) · [OpenClaw](https://neotoma.io/neotoma-with-openclaw)
 
-**Agent behavior contract:** Store first, retrieve before storing, extract entities from user input, create tasks for commitments. Full instructions: [MCP instructions](docs/developer/mcp/instructions.md) and [CLI agent instructions](docs/developer/cli_agent_instructions.md).
+For local source iteration, use the stable dev shim (`scripts/run_neotoma_mcp_stdio_dev_shim.sh` or `npm run dev:mcp:dev-shim`) instead of pointing installed MCP clients at a `tsx watch` stdio process. The shim keeps the client-facing JSON-RPC stream stable and asks clients to refresh or reconnect when the tool interface changes.
+
+**Agent behavior contract:** Store first, retrieve before storing, extract entities from user input, create tasks for commitments, and attach bounded host context such as repository name/root scope when available. Full instructions: [MCP instructions](docs/developer/mcp/instructions.md) and [CLI agent instructions](docs/developer/cli_agent_instructions.md).
 
 **Representative actions:** `store`, `retrieve_entities`, `retrieve_entity_snapshot`, `merge_entities`, `list_observations`, `create_relationship`, `list_relationships`, `list_timeline_events`, `retrieve_graph_neighborhood`. Full list: [MCP spec](docs/specs/MCP_SPEC.md).
 

package/dist/actions.d.ts

@@ -22,6 +22,14 @@ export declare function isLocalRequest(req: express.Request): boolean;
  * a different authority. See src/middleware/aauth_verify.ts.
  */
 export declare function canonicalAauthAuthority(): string;
+type StoreRelationshipRef = {
+    relationship_type: string;
+    source_index?: number;
+    target_index?: number;
+    source_entity_id?: string;
+    target_entity_id?: string;
+    metadata?: Record<string, unknown>;
+};
 export declare function storeStructuredForApi(params: {
     userId: string;
     entities: Record<string, unknown>[];
@@ -29,11 +37,7 @@ export declare function storeStructuredForApi(params: {
     observationSource?: import("./shared/action_schemas.js").ObservationSource;
     idempotencyKey: string;
     originalFilename?: string;
-    relationships?: Array<{
-        relationship_type: string;
-        source_index: number;
-        target_index: number;
-    }>;
+    relationships?: StoreRelationshipRef[];
     commit?: boolean;
     strict?: boolean;
 }): Promise<{
@@ -92,4 +96,5 @@ export declare function startHTTPServer(): Promise<{
     server: import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;
     port: number;
 } | undefined>;
+export {};
 //# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAiJ9B,eAAO,MAAM,GAAG,6CAAY,CAAC;AAwZ7B;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,GAAG,OAAO,CAU5D;AA4PD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAmBhD;AA2kHD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,4BAA4B,EAAE,iBAAiB,CAAC;IAC3E,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,KAAK,CAAC;QACpB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;;;;;;;;;;;;;cAkfS,MAAM;gBACJ,MAAM;2BACK,MAAM;qBACZ,MAAM;mBACR,MAAM;wBACD,MAAM;uBACP,MAAM;;;;;;;;;mBA9IV,MAAM;qBACJ,MAAM;wBACH,MAAM,GAAG,IAAI;2BACV,MAAM;;wBAET,MAAM;uBACP,MAAM,EAAE;wBACP,MAAM;uBACP,MAAM;;kBA9NX,MAAM;oBACJ,MAAM;yBACD,MAAM;4BACH,MAAM;2BACP,MAAM;;+BA4NF,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;;;2BAkFlC,MAAM;0BACP,MAAM;0BACN,MAAM;;GA8E3B;AA29DD,wBAAsB,eAAe;;;eA6EpC"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAmK9B,eAAO,MAAM,GAAG,6CAAY,CAAC;AAif7B;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,GAAG,OAAO,CAU5D;AA4PD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAmBhD;AAyrHD,KAAK,oBAAoB,GAAG;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,4BAA4B,EAAE,iBAAiB,CAAC;IAC3E,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACvC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;;;;;;;;;;;;;cA+fS,MAAM;gBACJ,MAAM;2BACK,MAAM;qBACZ,MAAM;mBACR,MAAM;wBACD,MAAM;uBACP,MAAM;;;;;;;;;mBA3JV,MAAM;qBACJ,MAAM;wBACH,MAAM,GAAG,IAAI;2BACV,MAAM;;wBAET,MAAM;uBACP,MAAM,EAAE;wBACP,MAAM;uBACP,MAAM;;kBA9NX,MAAM;oBACJ,MAAM;yBACD,MAAM;4BACH,MAAM;2BACP,MAAM;;+BA4NF,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;;;2BAkFlC,MAAM;0BACP,MAAM;0BACN,MAAM;;GA2F3B;AAuhED,wBAAsB,eAAe;;;eA2FpC"}

package/dist/actions.js

@@ -1,4 +1,5 @@
 import express from "express";
+import cookieParser from "cookie-parser";
 import cors from "cors";
 import helmet from "helmet";
 import morgan from "morgan";
@@ -34,13 +35,15 @@ import { logger } from "./utils/logger.js";
 import { OAuthError } from "./services/mcp_oauth_errors.js";
 import { ensureLocalDevUser, ensureSandboxAauthUser, ensureSandboxPublicUser, LOCAL_DEV_USER_ID, SANDBOX_PUBLIC_USER_ID, } from "./services/local_auth.js";
 import { isSandboxMode, sandboxDestructiveGuard, sandboxHeaderMiddleware, } from "./services/sandbox_mode.js";
-import { buildLandingContext, buildRootLandingHtml, buildRootLandingJson, buildRootLandingMarkdown, buildRobotsTxt, wantsHtml as acceptWantsHtml, wantsMarkdown as acceptWantsMarkdown, } from "./services/root_landing/index.js";
+import { createSandboxSession, redeemOneTimeCode, resolveSessionFromRequest, revokeSession, purgeSessionUserData, sweepExpiredSessions, SESSION_COOKIE_NAME, } from "./services/sandbox/sessions.js";
+import { buildLandingContext, buildRootLandingHtml, buildRootLandingJson, buildRootLandingMarkdown, buildRobotsTxt, readNeotomaConfigEnvironment, wantsHtml as acceptWantsHtml, wantsMarkdown as acceptWantsMarkdown, } from "./services/root_landing/index.js";
+import { installInspectorMount } from "./services/inspector_mount.js";
 import { getSandboxTermsResponse } from "./services/sandbox/terms.js";
 import { resolveSandboxReportTransport } from "./services/sandbox/transport.js";
 import { getSqliteDb } from "./repositories/sqlite/sqlite_client.js";
 import { getMcpAuthToken } from "./crypto/mcp_auth_token.js";
 import { isOauthKeyCredentialValid, normalizeOauthNextPath, OAuthKeySessionStore, } from "./services/oauth_key_gate.js";
-import { AnalyzeSchemaCandidatesRequestSchema, CorrectEntityRequestSchema, CreateRelationshipRequestSchema, DeleteEntityRequestSchema, DeleteRelationshipRequestSchema, EntitiesQueryRequestSchema, EntitySnapshotRequestSchema, FieldProvenanceRequestSchema, GetSchemaRecommendationsRequestSchema, ListObservationsRequestSchema, ListRelationshipsRequestSchema, MergeEntitiesRequestSchema, SplitEntityRequestSchema, ObservationsQueryRequestSchema, RegisterSchemaRequestSchema, RelationshipSnapshotRequestSchema, RestoreEntityRequestSchema, RestoreRelationshipRequestSchema, RetrieveEntityByIdentifierSchema, RetrieveGraphNeighborhoodSchema, RetrieveRelatedEntitiesSchema, StoreRequestSchema, StoreUnstructuredRequestSchema, UpdateSchemaIncrementalRequestSchema, } from "./shared/action_schemas.js";
+import { AnalyzeSchemaCandidatesRequestSchema, CorrectEntityRequestSchema, CreateRelationshipsRequestSchema, CreateRelationshipRequestSchema, DeleteEntityRequestSchema, DeleteRelationshipRequestSchema, EntitiesQueryRequestSchema, EntitySnapshotRequestSchema, FieldProvenanceRequestSchema, GetSchemaRecommendationsRequestSchema, ListObservationsRequestSchema, ListRelationshipsRequestSchema, MergeEntitiesRequestSchema, SplitEntityRequestSchema, ObservationsQueryRequestSchema, RegisterSchemaRequestSchema, RelationshipSnapshotRequestSchema, RestoreEntityRequestSchema, RestoreRelationshipRequestSchema, RetrieveEntityByIdentifierSchema, RetrieveGraphNeighborhoodSchema, RetrieveRelatedEntitiesSchema, StoreRequestSchema, StoreUnstructuredRequestSchema, UpdateSchemaIncrementalRequestSchema, } from "./shared/action_schemas.js";
 import { getMimeTypeFromExtension } from "./services/file_text_extraction.js";
 import { queryEntitiesWithCount } from "./shared/action_handlers/entity_handlers.js";
 import { retrieveEntityByIdentifierWithFallback } from "./shared/action_handlers/entity_identifier_handler.js";
@@ -48,7 +51,9 @@ import { prepareEntitySnapshotWithEmbedding, upsertEntitySnapshotWithEmbedding,
 import { readOpenApiActionsFile, readOpenApiFile } from "./shared/openapi_file.js";
 import { buildSmitheryServerCard } from "./mcp_server_card.js";
 import { listRecentRecordActivity, parseRecordActivityTypesQuery, } from "./services/recent_record_activity.js";
-import { listRecentConversations } from "./services/recent_conversations.js";
+import { getRecentConversationById, listRecentConversations } from "./services/recent_conversations.js";
+import { listConversationTurns, getConversationTurn, } from "./services/conversation_turn.js";
+import { buildComplianceScorecard } from "./services/compliance/scorecard.js";
 import { getAgent, listAgentRecords, listAgents } from "./services/agents_directory.js";
 export const app = express();
 // Trust proxy headers (required for express-rate-limit when X-Forwarded-For is present)
@@ -102,6 +107,7 @@ app.use(express.json({
     },
 }));
 app.use(morgan("dev"));
+app.use(cookieParser());
 app.use(unknownFieldsGuard);
 // Sandbox-mode response header. Stamped on every response so clients can
 // detect public-sandbox deployments (sandbox.neotoma.io) without an extra
@@ -110,37 +116,125 @@ if (isSandboxMode()) {
     app.use(sandboxHeaderMiddleware);
     logger.info("[Sandbox] NEOTOMA_SANDBOX_MODE=1 — bearer bypass to SANDBOX_PUBLIC_USER_ID, destructive routes gated, weekly reset expected");
 }
-// Inspector SPA mount. When NEOTOMA_INSPECTOR_STATIC_DIR is set, serve the
-// pre-built Inspector bundle at NEOTOMA_INSPECTOR_BASE_PATH (default /app).
-// Deliberately registered before all auth / rate-limit middleware so the SPA
-// shell + assets are reachable without a bearer — the API calls it makes still
-// flow through the normal auth stack below.
-const inspectorStaticDir = (process.env.NEOTOMA_INSPECTOR_STATIC_DIR || "").trim();
-const inspectorBasePath = ((process.env.NEOTOMA_INSPECTOR_BASE_PATH || "/app").trim() || "/app").replace(/\/$/, "");
-if (inspectorStaticDir) {
-    try {
-        const indexHtmlPath = path.resolve(inspectorStaticDir, "index.html");
-        // express.static with fallthrough so 404s on unknown files fall into the
-        // SPA history handler below rather than short-circuiting.
-        app.use(inspectorBasePath, express.static(inspectorStaticDir, {
-            index: false,
-            fallthrough: true,
-            maxAge: "1h",
-        }));
-        app.get([`${inspectorBasePath}`, `${inspectorBasePath}/*`], (req, res, next) => {
-            // Only respond if the request was headed for the SPA (accepts html).
-            if (req.method !== "GET")
-                return next();
-            res.sendFile(indexHtmlPath, (err) => {
-                if (err)
-                    next(err);
+// Inspector SPA mount. Deliberately registered before all auth / rate-limit
+// middleware so the SPA shell + assets are reachable without a bearer — the
+// API calls the Inspector makes still flow through the normal auth stack below.
+installInspectorMount(app, process.env, logger);
+// ── Sandbox session endpoints ───────────────────────────────────────────
+// Registered before general auth so the session handshake works for
+// unauthenticated visitors. Routes exist only when NEOTOMA_SANDBOX_MODE=1.
+if (isSandboxMode()) {
+    const sessionRateLimit = rateLimit({
+        windowMs: 60 * 60 * 1000,
+        limit: 10,
+        standardHeaders: true,
+        legacyHeaders: false,
+        keyGenerator: (req) => `ip:${ipKeyGenerator(req.ip || "")}`,
+        validate: { trustProxy: false },
+    });
+    app.post("/sandbox/session/new", sessionRateLimit, (req, res) => {
+        try {
+            const packId = typeof req.body?.pack_id === "string" ? req.body.pack_id : "generic";
+            const session = createSandboxSession(packId);
+            res.cookie(SESSION_COOKIE_NAME, session.bearerToken, {
+                httpOnly: true,
+                sameSite: "lax",
+                path: "/",
+                expires: new Date(session.expiresAt),
+            });
+            res.json({
+                one_time_code: session.oneTimeCode,
+                expires_at: session.expiresAt,
+                pack_id: session.packId,
             });
+        }
+        catch (err) {
+            logger.error(`[Sandbox] session/new failed: ${err.message}`);
+            res.status(500).json({ error_code: "SESSION_CREATE_FAILED", message: err.message });
+        }
+    });
+    app.post("/sandbox/session/redeem", (req, res) => {
+        try {
+            const code = typeof req.body?.code === "string" ? req.body.code : "";
+            if (!code) {
+                res.status(400).json({ error_code: "MISSING_CODE", message: "code is required" });
+                return;
+            }
+            const result = redeemOneTimeCode(code);
+            if (!result) {
+                res.status(404).json({ error_code: "INVALID_CODE", message: "Code expired or already redeemed" });
+                return;
+            }
+            res.cookie(SESSION_COOKIE_NAME, result.bearerToken, {
+                httpOnly: true,
+                sameSite: "lax",
+                path: "/",
+                expires: new Date(result.expiresAt),
+            });
+            res.json({
+                bearer_token: result.bearerToken,
+                user_id: result.userId,
+                expires_at: result.expiresAt,
+                pack_id: result.packId,
+            });
+        }
+        catch (err) {
+            logger.error(`[Sandbox] session/redeem failed: ${err.message}`);
+            res.status(500).json({ error_code: "SESSION_REDEEM_FAILED", message: err.message });
+        }
+    });
+    app.get("/sandbox/session", (req, res) => {
+        const session = resolveSessionFromRequest(req);
+        if (!session) {
+            res.status(401).json({ error_code: "NO_SESSION", message: "No active sandbox session" });
+            return;
+        }
+        res.json({
+            user_id: session.userId,
+            pack_id: session.packId,
+            created_at: session.createdAt,
+            expires_at: session.expiresAt,
         });
-        logger.info(`[Inspector] Serving SPA from ${inspectorStaticDir} at ${inspectorBasePath}`);
-    }
-    catch (err) {
-        logger.warn(`[Inspector] Failed to mount SPA: ${err.message}`);
-    }
+    });
+    app.post("/sandbox/session/reset", (req, res) => {
+        const session = resolveSessionFromRequest(req);
+        if (!session) {
+            res.status(401).json({ error_code: "NO_SESSION", message: "No active sandbox session" });
+            return;
+        }
+        const packId = typeof req.body?.pack_id === "string" ? req.body.pack_id : undefined;
+        purgeSessionUserData(session.userId);
+        const newSession = createSandboxSession(packId ?? session.packId);
+        res.cookie(SESSION_COOKIE_NAME, newSession.bearerToken, {
+            httpOnly: true,
+            sameSite: "lax",
+            path: "/",
+            expires: new Date(newSession.expiresAt),
+        });
+        res.json({
+            user_id: newSession.userId,
+            pack_id: newSession.packId,
+            expires_at: newSession.expiresAt,
+        });
+    });
+    app.delete("/sandbox/session", (req, res) => {
+        const session = resolveSessionFromRequest(req);
+        if (!session) {
+            res.status(401).json({ error_code: "NO_SESSION", message: "No active sandbox session" });
+            return;
+        }
+        revokeSession(session.userId);
+        purgeSessionUserData(session.userId);
+        res.clearCookie(SESSION_COOKIE_NAME, { path: "/" });
+        res.json({ ok: true });
+    });
+    setInterval(() => {
+        const purged = sweepExpiredSessions();
+        if (purged > 0) {
+            logger.info(`[Sandbox] Swept ${purged} expired session(s)`);
+        }
+    }, 15 * 60 * 1000);
+    logger.info("[Sandbox] Session endpoints registered");
 }
 // Rate limiters for OAuth endpoints
 // validate.trustProxy: false — we use trust proxy behind one proxy; skip strict IP check
@@ -399,6 +493,7 @@ app.get("/server-info", (_req, res) => {
         httpPort,
         apiBase: config.apiBase,
         mcpUrl,
+        neotoma_env: readNeotomaConfigEnvironment(),
     });
 });
 // ============================================================================
@@ -1803,6 +1898,16 @@ app.use(async (req, res, next) => {
         logger.info(`[Auth] ${req.method} ${req.path} auth_method=local_no_bearer user_id=${devUser.id}`);
         return next();
     }
+    // Sandbox ephemeral session: resolve from cookie or Bearer token before
+    // falling back to the shared public user. Expired/revoked sessions 401.
+    if (isSandboxMode()) {
+        const sessionInfo = resolveSessionFromRequest(req);
+        if (sessionInfo) {
+            req.authenticatedUserId = sessionInfo.userId;
+            logger.info(`[Auth] ${req.method} ${req.path} auth_method=sandbox_session user_id=${sessionInfo.userId}`);
+            return next();
+        }
+    }
     // Sandbox mode: public deployment at sandbox.neotoma.io where anonymous
     // callers are attributed to SANDBOX_PUBLIC_USER_ID without a Bearer. AAuth
     // still runs (earlier in the chain via aauthVerify) so agents exercising the
@@ -3167,6 +3272,21 @@ app.get("/agents/:key/records", async (req, res) => {
         return handleApiError(req, res, error, "Failed to list agent records", "DB_QUERY_FAILED", "APIError:agents_records");
     }
 });
+// GET /recent_conversations/:conversation_id — Inspector: one conversation with nested messages
+app.get("/recent_conversations/:conversation_id", async (req, res) => {
+    try {
+        const userId = await getAuthenticatedUserId(req, req.query.user_id);
+        const conversationId = String(req.params.conversation_id ?? "").trim();
+        const item = getRecentConversationById(userId, conversationId);
+        if (!item) {
+            return sendError(res, 404, "RESOURCE_NOT_FOUND", "Conversation not found");
+        }
+        return res.json(item);
+    }
+    catch (error) {
+        return handleApiError(req, res, error, "Failed to load conversation", "DB_QUERY_FAILED", "APIError:recent_conversation_detail");
+    }
+});
 // GET /recent_conversations — Inspector: conversations with nested messages (SQLite)
 app.get("/recent_conversations", async (req, res) => {
     try {
@@ -3175,7 +3295,9 @@ app.get("/recent_conversations", async (req, res) => {
         const offset = parseInt(String(req.query.offset ?? "0"), 10) || 0;
         const activity_after = typeof req.query.activity_after === "string" ? req.query.activity_after.trim() || null : null;
         const activity_before = typeof req.query.activity_before === "string" ? req.query.activity_before.trim() || null : null;
-        const agent_key = typeof req.query.agent_key === "string" ? req.query.agent_key.trim() || null : null;
+        const agentKeyRaw = typeof req.query.agent_key === "string" ? req.query.agent_key.trim() : "";
+        // UI and bookmarks may send agent_key=all; never treat that as a real deriveAgentKey value.
+        const agent_key = agentKeyRaw.length > 0 && agentKeyRaw.toLowerCase() !== "all" ? agentKeyRaw : null;
         const result = listRecentConversations(userId, limit, offset, {
             activity_after,
             activity_before,
@@ -3187,6 +3309,69 @@ app.get("/recent_conversations", async (req, res) => {
         return handleApiError(req, res, error, "Failed to list recent conversations", "DB_QUERY_FAILED", "APIError:recent_conversations");
     }
 });
+// GET /turns — Inspector: paginated conversation_turn index
+app.get("/turns", async (req, res) => {
+    try {
+        const userId = await getAuthenticatedUserId(req, req.query.user_id);
+        const limit = parseInt(String(req.query.limit ?? "25"), 10) || 25;
+        const offset = parseInt(String(req.query.offset ?? "0"), 10) || 0;
+        const harness = typeof req.query.harness === "string" ? req.query.harness.trim() || null : null;
+        const status = typeof req.query.status === "string" ? req.query.status.trim() || null : null;
+        const activity_after = typeof req.query.activity_after === "string" ? req.query.activity_after.trim() || null : null;
+        const activity_before = typeof req.query.activity_before === "string" ? req.query.activity_before.trim() || null : null;
+        const result = listConversationTurns(userId, limit, offset, {
+            harness,
+            status,
+            activity_after,
+            activity_before,
+        });
+        return res.json(result);
+    }
+    catch (error) {
+        return handleApiError(req, res, error, "Failed to list turns", "DB_QUERY_FAILED", "APIError:turns");
+    }
+});
+// GET /turns/:turn_key — Inspector: conversation_turn detail
+app.get("/turns/:turn_key", async (req, res) => {
+    try {
+        const userId = await getAuthenticatedUserId(req, req.query.user_id);
+        const turnKey = decodeURIComponent(req.params.turn_key);
+        const result = getConversationTurn(userId, turnKey);
+        if (!result) {
+            return res.status(404).json({ error: "Turn not found", code: "NOT_FOUND" });
+        }
+        return res.json(result);
+    }
+    catch (error) {
+        return handleApiError(req, res, error, "Failed to get turn", "DB_QUERY_FAILED", "APIError:turn_detail");
+    }
+});
+// GET /admin/compliance/scorecard — Inspector: aggregated hook compliance (SQLite)
+app.get("/admin/compliance/scorecard", async (req, res) => {
+    try {
+        const userId = await getAuthenticatedUserId(req, req.query.user_id);
+        const since = typeof req.query.since === "string" ? req.query.since : undefined;
+        const until = typeof req.query.until === "string" ? req.query.until : undefined;
+        const group_by = typeof req.query.group_by === "string" ? req.query.group_by : undefined;
+        const min_turns = parseInt(String(req.query.min_turns ?? ""), 10);
+        const min_backfill_rate = parseFloat(String(req.query.min_backfill_rate ?? ""));
+        const top_missed_steps = parseInt(String(req.query.top_missed_steps ?? ""), 10);
+        const include_synthetic = req.query.include_synthetic === "1" || String(req.query.include_synthetic).toLowerCase() === "true";
+        const result = buildComplianceScorecard(userId, {
+            since,
+            until,
+            group_by,
+            min_turns: Number.isFinite(min_turns) ? min_turns : undefined,
+            min_backfill_rate: Number.isFinite(min_backfill_rate) ? min_backfill_rate : undefined,
+            top_missed_steps: Number.isFinite(top_missed_steps) ? top_missed_steps : undefined,
+            include_synthetic,
+        });
+        return res.json(result);
+    }
+    catch (error) {
+        return handleApiError(req, res, error, "Failed to build compliance scorecard", "DB_QUERY_FAILED", "APIError:compliance_scorecard");
+    }
+});
 // GET /api/sources - Get source list (FU-301)
 app.get("/sources", async (req, res) => {
     try {
@@ -4044,30 +4229,41 @@ export async function storeStructuredForApi(params) {
     if (commit && relationships && relationships.length > 0) {
         const { relationshipsService } = await import("./services/relationships.js");
         for (const rel of relationships) {
-            const source = resolved[rel.source_index];
-            const target = resolved[rel.target_index];
-            if (!source || !target) {
-                logger.warn(`[STORE] Skipping relationship: invalid source_index=${rel.source_index} ` +
-                    `or target_index=${rel.target_index} (have ${resolved.length} entities).`);
+            const sourceEntityId = typeof rel.source_entity_id === "string"
+                ? rel.source_entity_id
+                : typeof rel.source_index === "number"
+                    ? resolved[rel.source_index]?.entity_id
+                    : undefined;
+            const targetEntityId = typeof rel.target_entity_id === "string"
+                ? rel.target_entity_id
+                : typeof rel.target_index === "number"
+                    ? resolved[rel.target_index]?.entity_id
+                    : undefined;
+            if (!sourceEntityId || !targetEntityId) {
+                logger.warn(`[STORE] Skipping relationship: invalid source reference ` +
+                    `(source_index=${rel.source_index}, source_entity_id=${rel.source_entity_id}) ` +
+                    `or target reference (target_index=${rel.target_index}, ` +
+                    `target_entity_id=${rel.target_entity_id}); have ${resolved.length} entities.`);
                 continue;
             }
             try {
                 await relationshipsService.createRelationship({
-                    source_entity_id: source.entity_id,
-                    target_entity_id: target.entity_id,
+                    source_entity_id: sourceEntityId,
+                    target_entity_id: targetEntityId,
                     relationship_type: rel.relationship_type,
                     source_id: storageResult.sourceId,
+                    metadata: rel.metadata ?? {},
                     user_id: userId,
                 });
                 relationshipsCreated.push({
                     relationship_type: rel.relationship_type,
-                    source_entity_id: source.entity_id,
-                    target_entity_id: target.entity_id,
+                    source_entity_id: sourceEntityId,
+                    target_entity_id: targetEntityId,
                 });
             }
             catch (relErr) {
                 logger.warn(`Failed to create relationship ${rel.relationship_type} ` +
-                    `${source.entity_id} -> ${target.entity_id}: ${relErr instanceof Error ? relErr.message : String(relErr)}`);
+                    `${sourceEntityId} -> ${targetEntityId}: ${relErr instanceof Error ? relErr.message : String(relErr)}`);
             }
         }
     }
@@ -4635,6 +4831,63 @@ app.post("/create_relationship", async (req, res) => {
         return sendError(res, 500, "DB_QUERY_FAILED", error instanceof Error ? error.message : "Failed to create relationship");
     }
 });
+// Create relationships in batch
+app.post("/create_relationships", async (req, res) => {
+    const parsed = CreateRelationshipsRequestSchema.safeParse(req.body);
+    if (!parsed.success) {
+        logWarn("ValidationError:create_relationships", req, {
+            issues: parsed.error.issues,
+        });
+        return sendValidationError(res, parsed.error.issues);
+    }
+    const { relationships, source_id, user_id } = parsed.data;
+    const { relationshipsService } = await import("./services/relationships.js");
+    try {
+        const userId = await getAuthenticatedUserId(req, user_id);
+        const created = [];
+        const errors = [];
+        for (const [index, relationship] of relationships.entries()) {
+            try {
+                const snapshot = await relationshipsService.createRelationship({
+                    relationship_type: relationship.relationship_type,
+                    source_entity_id: relationship.source_entity_id,
+                    target_entity_id: relationship.target_entity_id,
+                    source_id: relationship.source_id || source_id || null,
+                    metadata: relationship.metadata || {},
+                    user_id: userId,
+                });
+                created.push({
+                    index,
+                    ...snapshot,
+                });
+            }
+            catch (error) {
+                errors.push({
+                    index,
+                    relationship,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        logDebug("Success:create_relationships", req, {
+            requested: relationships.length,
+            created: created.length,
+            errors: errors.length,
+        });
+        return res.json({
+            success: errors.length === 0,
+            requested: relationships.length,
+            created_count: created.length,
+            error_count: errors.length,
+            relationships: created,
+            errors,
+        });
+    }
+    catch (error) {
+        logError("RelationshipCreationError:create_relationships", req, error);
+        return sendError(res, 500, "DB_QUERY_FAILED", error instanceof Error ? error.message : "Failed to create relationships");
+    }
+});
 // List relationships
 app.post("/list_relationships", async (req, res) => {
     const parsed = ListRelationshipsRequestSchema.safeParse(req.body);
@@ -5665,6 +5918,16 @@ export async function startHTTPServer() {
     }
     // Initialize encryption service
     await initServerKeys();
+    // Seed `neotoma_feedback` schema unconditionally so local-only installs
+    // (no AGENT_SITE_BASE_URL) can mirror feedback into the entity graph.
+    try {
+        const { seedNeotomaFeedbackSchema } = await import("./services/feedback/seed_schema.js");
+        await seedNeotomaFeedbackSchema();
+        logger.info("[Feedback] neotoma_feedback schema seeded");
+    }
+    catch (err) {
+        logger.warn(`[Feedback] failed to seed neotoma_feedback schema: ${err.message}`);
+    }
     // Sandbox mode: ensure the `sandbox_abuse_report` entity type is registered
     // before any report comes in so forwarded records can attach cleanly to the
     // entity graph. Non-sandbox deployments still benefit from having the schema