neotoma 0.10.0 → 0.11.0

package/README.md

@@ -100,6 +100,7 @@ The agent handles npm install, initialization, and MCP configuration. **Manual i
 ```bash
 npm install -g neotoma
 neotoma init
+neotoma setup --tool <cursor|claude-code|codex> --yes
 neotoma mcp config
 ```
 
@@ -220,7 +221,7 @@ 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) · [OpenCode](docs/integrations/hooks/opencode.md) · [OpenClaw](https://neotoma.io/neotoma-with-openclaw) · [IronClaw](https://neotoma.io/neotoma-with-ironclaw)
 
-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.
+For local source iteration, use the stable dev shim (`scripts/run_neotoma_mcp_stdio_dev_shim.sh`) or signed shim (`scripts/run_neotoma_mcp_signed_stdio_dev_shim.sh`) instead of pointing installed MCP clients at a `tsx watch` stdio process. `neotoma mcp config` defaults to **`b`** for low-friction local stdio setup; use **`a`** for signed + AAuth HTTP `/mcp` proxy entries when the Neotoma API is running, **`c`** for direct stdio, or **`d`** when both MCP entries should target prod.
 
 **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).
 

package/dist/actions.d.ts

@@ -1,4 +1,5 @@
 import express from "express";
+import { type StoreInterpretationInput } from "./shared/action_schemas.js";
 export declare const app: import("express-serve-static-core").Express;
 /**
  * True when the request arrived over a loopback socket.
@@ -38,6 +39,8 @@ export declare function storeStructuredForApi(params: {
     idempotencyKey: string;
     originalFilename?: string;
     relationships?: StoreRelationshipRef[];
+    interpretation?: StoreInterpretationInput;
+    interpretationSourceId?: string;
     commit?: boolean;
     strict?: boolean;
 }): Promise<{
@@ -61,10 +64,6 @@ export declare function storeStructuredForApi(params: {
         identity_basis: string;
         identity_rule: string;
     }[] | undefined;
-    success: boolean;
-    replayed: boolean;
-    commit: boolean;
-    source_id: string | null;
     entities_created: number;
     observations_created: number;
     entities: {
@@ -91,6 +90,12 @@ export declare function storeStructuredForApi(params: {
         source_entity_id: string;
         target_entity_id: string;
     }[];
+    interpretation_id?: string | undefined;
+    interpretation_source_id?: string | undefined;
+    success: boolean;
+    replayed: boolean;
+    commit: boolean;
+    source_id: string | null;
 }>;
 export declare function startHTTPServer(): Promise<{
     server: import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;

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;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;AA4sHD,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"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AA4G9B,OAAO,EAyBL,KAAK,wBAAwB,EAE9B,MAAM,4BAA4B,CAAC;AA+BpC,eAAO,MAAM,GAAG,6CAAY,CAAC;AAygB7B;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,GAAG,OAAO,CAU5D;AA4PD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAmBhD;AAiyHD,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;AAuDF,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,cAAc,CAAC,EAAE,wBAAwB,CAAC;IAC1C,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;;;;;;;;;;;;;cA+gBS,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;;;;;;;;GAsG3B;AAmhED,wBAAsB,eAAe;;;eA8FpC"}

package/dist/actions.js

@@ -10,6 +10,7 @@ import { db } from "./db.js";
 import { config } from "./config.js";
 import fs from "fs";
 import path from "path";
+import { writeLocalHttpPortFile } from "./utils/local_http_port_file.js";
 import yaml from "js-yaml";
 import { ensurePublicKeyRegistered, getPublicKey, getUserIdFromBearerToken, isBearerTokenValid, } from "./services/public_key_registry.js";
 import { verifyRequest, parseAuthHeader } from "./crypto/auth.js";
@@ -19,10 +20,10 @@ import { aauthVerify, getAAuthContextFromRequest, getAttributionDecisionFromRequ
 import { attributionContext } from "./middleware/attribution_context.js";
 import { aauthAdmission, getAAuthAdmissionFromRequest, } from "./middleware/aauth_admission.js";
 import { buildSessionInfo } from "./services/session_info.js";
-import { AttributionPolicyError } from "./services/attribution_policy.js";
+import { AttributionPolicyError, enforceAttributionPolicy } from "./services/attribution_policy.js";
 import { registerFeedbackAdminProxyRoutes } from "./services/feedback/admin_proxy.js";
 import { AgentCapabilityError, contextFromAgentIdentity, enforceAgentCapability, } from "./services/agent_capabilities.js";
-import { getCurrentAAuthAdmission, getCurrentAgentIdentity, runWithRequestContext, } from "./services/request_context.js";
+import { getCurrentAAuthAdmission, getCurrentAgentIdentity, getCurrentAttribution, runWithRequestContext, } from "./services/request_context.js";
 import { assertCanWriteProtectedBatch } from "./services/protected_entity_types.js";
 import { createAgentIdentity as buildAgentIdentity, getAgentIdentityFromRequest, normaliseClientName, } from "./crypto/agent_identity.js";
 import { initServerKeys } from "./services/encryption_service.js";
@@ -43,7 +44,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, 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 { AnalyzeSchemaCandidatesRequestSchema, CorrectEntityRequestSchema, CreateInterpretationRequestSchema, CreateRelationshipsRequestSchema, CreateRelationshipRequestSchema, DeleteEntityRequestSchema, DeleteRelationshipRequestSchema, EntitiesQueryRequestSchema, EntitySnapshotRequestSchema, FieldProvenanceRequestSchema, GetSchemaRecommendationsRequestSchema, ListObservationsRequestSchema, ListRelationshipsRequestSchema, MergeEntitiesRequestSchema, SplitEntityRequestSchema, ObservationsQueryRequestSchema, RegisterSchemaRequestSchema, RelationshipSnapshotRequestSchema, RestoreEntityRequestSchema, RestoreRelationshipRequestSchema, RetrieveEntityByIdentifierSchema, RetrieveGraphNeighborhoodSchema, RetrieveRelatedEntitiesSchema, StoreRequestSchema, 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";
@@ -496,6 +497,24 @@ app.get("/server-info", (_req, res) => {
         neotoma_env: readNeotomaConfigEnvironment(),
     });
 });
+app.get("/mcp-interaction-instructions", (_req, res) => {
+    const instructionsPath = path.join(config.projectRoot, "docs", "developer", "mcp", "instructions.md");
+    try {
+        const raw = fs.readFileSync(instructionsPath, "utf-8");
+        const match = raw.match(/```\s*\n?([\s\S]*?)```/);
+        if (match && match[1]) {
+            const text = match[1].trim();
+            if (text) {
+                res.type("text/plain").send(text);
+                return;
+            }
+        }
+    }
+    catch {
+        // fall through to 404
+    }
+    res.status(404).json({ error: "instructions_not_found" });
+});
 // ============================================================================
 // MCP StreamableHTTP Endpoint (OAuth-enabled MCP transport)
 // ============================================================================
@@ -3791,6 +3810,83 @@ app.get("/interpretations", async (req, res) => {
         return sendError(res, 500, "DB_QUERY_FAILED", message);
     }
 });
+app.post("/interpretations/create", async (req, res) => {
+    const parsed = CreateInterpretationRequestSchema.safeParse(req.body);
+    if (!parsed.success) {
+        logWarn("ValidationError:interpretations_create", req, { issues: parsed.error.issues });
+        return sendValidationError(res, parsed.error.issues);
+    }
+    try {
+        const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
+        const { data: source, error: sourceError } = await db
+            .from("sources")
+            .select("id")
+            .eq("id", parsed.data.source_id)
+            .eq("user_id", userId)
+            .maybeSingle();
+        if (sourceError)
+            throw sourceError;
+        if (!source) {
+            return sendError(res, 404, "SOURCE_NOT_FOUND", "Source not found for authenticated user");
+        }
+        const { runInterpretation } = await import("./services/interpretation.js");
+        const interpretationResult = await runInterpretation({
+            userId,
+            sourceId: parsed.data.source_id,
+            extractedData: parsed.data.entities,
+            config: normalizeInterpretationConfig(parsed.data.interpretation_config),
+        });
+        const relationshipsCreated = [];
+        if (parsed.data.relationships?.length) {
+            const { relationshipsService } = await import("./services/relationships.js");
+            for (const rel of parsed.data.relationships) {
+                const sourceEntityId = typeof rel.source_entity_id === "string"
+                    ? rel.source_entity_id
+                    : typeof rel.source_index === "number"
+                        ? interpretationResult.entities[rel.source_index]?.entityId
+                        : undefined;
+                const targetEntityId = typeof rel.target_entity_id === "string"
+                    ? rel.target_entity_id
+                    : typeof rel.target_index === "number"
+                        ? interpretationResult.entities[rel.target_index]?.entityId
+                        : undefined;
+                if (!sourceEntityId || !targetEntityId)
+                    continue;
+                await relationshipsService.createRelationship({
+                    source_entity_id: sourceEntityId,
+                    target_entity_id: targetEntityId,
+                    relationship_type: rel.relationship_type,
+                    source_id: parsed.data.source_id,
+                    metadata: rel.metadata ?? {},
+                    user_id: userId,
+                });
+                relationshipsCreated.push({
+                    relationship_type: rel.relationship_type,
+                    source_entity_id: sourceEntityId,
+                    target_entity_id: targetEntityId,
+                });
+            }
+        }
+        return res.json({
+            success: true,
+            interpretation_id: interpretationResult.interpretationId,
+            source_id: parsed.data.source_id,
+            entities: interpretationResult.entities.map((entity) => ({
+                entity_id: entity.entityId,
+                entity_type: entity.entityType,
+                observation_id: entity.observationId,
+            })),
+            observations_created: interpretationResult.observationsCreated,
+            unknown_fields_count: interpretationResult.unknownFieldsCount,
+            relationships_created: relationshipsCreated,
+        });
+    }
+    catch (error) {
+        logError("APIError:interpretations_create", req, error);
+        const message = error instanceof Error ? error.message : "Failed to create interpretation";
+        return sendError(res, 500, "INTERPRETATION_CREATE_FAILED", message);
+    }
+});
 // GET /api/observations - Get observations with filters (FU-302, FU-601)
 // REQUIRES AUTHENTICATION - all queries filtered by authenticated user_id
 app.get("/observations", async (req, res) => {
@@ -3906,8 +4002,47 @@ app.post("/observations/create", async (req, res) => {
         return res.status(500).json(buildErrorEnvelope("DB_QUERY_FAILED", message));
     }
 });
+function normalizeInterpretationConfig(configInput) {
+    return {
+        extractor_type: "agent",
+        extractor_version: "unknown",
+        schema_version: "1.0",
+        ...configInput,
+    };
+}
+async function createInterpretationRunForSource(params) {
+    enforceAttributionPolicy("interpretations", getCurrentAgentIdentity());
+    const attribution = getCurrentAttribution();
+    const { data, error } = await db
+        .from("interpretations")
+        .insert({
+        user_id: params.userId,
+        source_id: params.sourceId,
+        interpretation_config: normalizeInterpretationConfig(params.interpretationConfig),
+        status: "running",
+        started_at: new Date().toISOString(),
+        ...(Object.keys(attribution).length > 0 ? { provenance: attribution } : {}),
+    })
+        .select("id")
+        .single();
+    if (error) {
+        throw new Error(`Failed to create interpretation run: ${error.message}`);
+    }
+    return data.id;
+}
+async function completeInterpretationRun(params) {
+    await db
+        .from("interpretations")
+        .update({
+        status: "completed",
+        completed_at: new Date().toISOString(),
+        observations_created: params.observationsCreated,
+        unknown_fields_count: params.unknownFieldsCount ?? 0,
+    })
+        .eq("id", params.interpretationId);
+}
 export async function storeStructuredForApi(params) {
-    const { userId, entities, sourcePriority, observationSource, idempotencyKey, originalFilename, relationships, commit: commitInput, strict: strictInput, } = params;
+    const { userId, entities, sourcePriority, observationSource, idempotencyKey, originalFilename, relationships, interpretation, interpretationSourceId, commit: commitInput, strict: strictInput, } = params;
     const commit = commitInput !== false;
     const strict = strictInput === true;
     // Capability scoping: when the caller is an AAuth-verified agent covered
@@ -3919,7 +4054,7 @@ export async function storeStructuredForApi(params) {
         const entityTypes = entities
             .map((entity) => entity?.entity_type)
             .filter((t) => typeof t === "string" && t.length > 0);
-        enforceAgentCapability("store_structured", entityTypes, capabilityCtx);
+        enforceAgentCapability("store", entityTypes, capabilityCtx);
         const relationshipOp = Array.isArray(relationships) && relationships.length > 0;
         if (relationshipOp) {
             enforceAgentCapability("create_relationship", entityTypes, capabilityCtx);
@@ -3935,7 +4070,7 @@ export async function storeStructuredForApi(params) {
             .filter((t) => typeof t === "string" && t.length > 0);
         assertCanWriteProtectedBatch({
             entity_types: entityTypes,
-            op: "store_structured",
+            op: "store",
             identity: getCurrentAgentIdentity(),
             admission: getCurrentAAuthAdmission(),
         });
@@ -4006,6 +4141,17 @@ export async function storeStructuredForApi(params) {
             source_priority: sourcePriority,
         },
     });
+    const resolvedInterpretationSourceId = interpretation?.source_id ??
+        interpretationSourceId ??
+        (interpretation?.source_ref === "structured" ? storageResult.sourceId : undefined);
+    const interpretationId = commit && interpretation && resolvedInterpretationSourceId
+        ? await createInterpretationRunForSource({
+            userId,
+            sourceId: resolvedInterpretationSourceId,
+            interpretationConfig: interpretation.interpretation_config,
+        })
+        : null;
+    const observationSourceId = resolvedInterpretationSourceId ?? storageResult.sourceId;
     // v0.5.1: structured guidance for the v0.5.0 breaking change where callers
     // nested fields under `attributes`. If resolution failed and the only
     // observed top-level keys are `attributes` (plus optionally `entity_type`),
@@ -4180,8 +4326,8 @@ export async function storeStructuredForApi(params) {
                 entity_id: r.entity_id,
                 entity_type: r.entity_type,
                 schema_version: "1.0",
-                source_id: storageResult.sourceId,
-                interpretation_id: null,
+                source_id: observationSourceId,
+                interpretation_id: interpretationId,
                 observed_at: new Date().toISOString(),
                 specificity_score: 1.0,
                 source_priority: sourcePriority,
@@ -4216,7 +4362,7 @@ export async function storeStructuredForApi(params) {
                         fields: r.fields,
                         schema: schemaEntry.schema_definition,
                         userId,
-                        sourceId: storageResult.sourceId,
+                        sourceId: observationSourceId,
                     });
                 }
             }
@@ -4268,7 +4414,7 @@ export async function storeStructuredForApi(params) {
                     source_entity_id: sourceEntityId,
                     target_entity_id: targetEntityId,
                     relationship_type: rel.relationship_type,
-                    source_id: storageResult.sourceId,
+                    source_id: observationSourceId,
                     metadata: rel.metadata ?? {},
                     user_id: userId,
                 });
@@ -4303,11 +4449,21 @@ export async function storeStructuredForApi(params) {
             });
         }
     }
+    if (commit && interpretationId) {
+        await completeInterpretationRun({
+            interpretationId,
+            observationsCreated: createdEntities.filter((e) => e.observation_id).length,
+            unknownFieldsCount: 0,
+        });
+    }
     return {
         success: true,
         replayed: false,
         commit,
         source_id: commit ? storageResult.sourceId : null,
+        ...(interpretationId
+            ? { interpretation_id: interpretationId, interpretation_source_id: observationSourceId }
+            : {}),
         entities_created: commit
             ? createdEntities.filter((e) => e.action === "created" || e.action === "extended").length
             : 0,
@@ -4364,23 +4520,7 @@ async function handleStorePost(req, res) {
         const hasUnstructured = hasFileContent || hasFilePath;
         let structuredResult;
         let unstructuredResult;
-        if (hasEntities) {
-            if (!parsed.data.idempotency_key) {
-                return sendError(res, 400, "VALIDATION_ERROR", "idempotency_key is required when entities are provided");
-            }
-            structuredResult = await storeStructuredForApi({
-                userId,
-                entities: parsed.data.entities,
-                sourcePriority: parsed.data.source_priority ?? 100,
-                observationSource: parsed.data.observation_source,
-                idempotencyKey: parsed.data.idempotency_key,
-                originalFilename: parsed.data.original_filename,
-                relationships: parsed.data.relationships,
-                commit: parsed.data.commit,
-                strict: parsed.data.strict,
-            });
-        }
-        if (hasUnstructured) {
+        const storeUnstructuredFromRequest = async () => {
             const fileContent = parsed.data.file_content;
             let mimeType = parsed.data.mime_type;
             let originalFilename = parsed.data.original_filename;
@@ -4397,9 +4537,10 @@ async function handleStorePost(req, res) {
                 originalFilename = originalFilename || path.basename(resolvedPath);
             }
             if ((!fileContent && !resolvedFileBuffer) || !mimeType) {
-                return sendError(res, 400, "VALIDATION_ERROR", "Unstructured store requires file_content+mime_type or file_path");
+                sendError(res, 400, "VALIDATION_ERROR", "Unstructured store requires file_content+mime_type or file_path");
+                return null;
             }
-            unstructuredResult = await storeUnstructuredForApi({
+            return await storeUnstructuredForApi({
                 userId,
                 fileContent,
                 fileBuffer: resolvedFileBuffer,
@@ -4408,6 +4549,42 @@ async function handleStorePost(req, res) {
                     (!hasEntities ? parsed.data.idempotency_key : undefined),
                 originalFilename,
             });
+        };
+        if (hasUnstructured && parsed.data.interpretation?.source_ref === "unstructured") {
+            const result = await storeUnstructuredFromRequest();
+            if (!result) {
+                return;
+            }
+            unstructuredResult = result;
+        }
+        if (hasEntities) {
+            if (!parsed.data.idempotency_key) {
+                return sendError(res, 400, "VALIDATION_ERROR", "idempotency_key is required when entities are provided");
+            }
+            structuredResult = await storeStructuredForApi({
+                userId,
+                entities: parsed.data.entities,
+                sourcePriority: parsed.data.source_priority ?? 100,
+                observationSource: parsed.data.observation_source,
+                idempotencyKey: parsed.data.idempotency_key,
+                originalFilename: parsed.data.original_filename,
+                relationships: parsed.data.relationships,
+                interpretation: parsed.data.interpretation,
+                interpretationSourceId: parsed.data.interpretation?.source_ref === "unstructured" &&
+                    unstructuredResult &&
+                    typeof unstructuredResult.source_id === "string"
+                    ? unstructuredResult.source_id
+                    : undefined,
+                commit: parsed.data.commit,
+                strict: parsed.data.strict,
+            });
+        }
+        if (hasUnstructured && !unstructuredResult) {
+            const result = await storeUnstructuredFromRequest();
+            if (!result) {
+                return;
+            }
+            unstructuredResult = result;
         }
         if (structuredResult && unstructuredResult) {
             return res.json({
@@ -4487,33 +4664,6 @@ if (isSandboxMode()) {
     app.post("/sandbox/aauth-only/store", writeRateLimit, aauthRequired, handleStorePost);
     logger.info("[Sandbox] AAuth-required write route enabled at POST /sandbox/aauth-only/store");
 }
-// POST /api/store/unstructured - Store raw file (base64), optional AI interpretation
-app.post("/store/unstructured", async (req, res) => {
-    const parsed = StoreUnstructuredRequestSchema.safeParse(req.body);
-    if (!parsed.success) {
-        logWarn("ValidationError:store_unstructured", req, { issues: parsed.error.issues });
-        return sendValidationError(res, parsed.error.issues);
-    }
-    try {
-        const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
-        const response = await storeUnstructuredForApi({
-            userId,
-            fileContent: parsed.data.file_content,
-            mimeType: parsed.data.mime_type,
-            idempotencyKey: parsed.data.idempotency_key,
-            originalFilename: parsed.data.original_filename,
-        });
-        return res.status(200).json(response);
-    }
-    catch (error) {
-        if (error instanceof Error && error.message.includes("Not authenticated")) {
-            return sendError(res, 401, "AUTH_REQUIRED", error.message);
-        }
-        logError("APIError:store_unstructured", req, error);
-        const message = error instanceof Error ? error.message : "Failed to store unstructured file";
-        return sendError(res, 500, "DB_QUERY_FAILED", message);
-    }
-});
 // POST /api/observations/query - Query observations
 app.post("/observations/query", async (req, res) => {
     const parsed = ObservationsQueryRequestSchema.safeParse(req.body);
@@ -5976,6 +6126,9 @@ export async function startHTTPServer() {
             }
             // eslint-disable-next-line no-console
             console.log(`HTTP Actions listening on :${boundPort}`);
+            if (process.env.NODE_ENV !== "test") {
+                writeLocalHttpPortFile(config.projectRoot, boundPort);
+            }
             // Start background OAuth state cleanup job
             import("./services/mcp_oauth.js").then((oauth) => {
                 oauth.startStateCleanupJob();