neotoma 0.9.0 → 0.9.1

package/README.md

@@ -188,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
@@ -218,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;AAiK9B,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;AA6nHD,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;;;eA2FpC"}
+{"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

@@ -43,7 +43,7 @@ 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";
@@ -51,8 +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)
@@ -3271,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 {
@@ -3279,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,
@@ -3328,6 +3346,32 @@ app.get("/turns/:turn_key", async (req, res) => {
         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 {
@@ -4185,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)}`);
             }
         }
     }
@@ -4776,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);